Javadoc improvement and renamed IDProvider#createID(Object) to

resolveID(Object)

Signed-off-by: Rogiel <rogiel@rogiel.com>

src/main/java/com/l2jserver/model/id/object/provider/CharacterIDProvider.java

@@ -58,7 +58,7 @@ public class CharacterIDProvider implements ObjectIDProvider<CharacterID> {
 	}
 
 	@Override
-	public CharacterID createID(Integer id) {
+	public CharacterID resolveID(Integer id) {
 		CharacterID idObject = idService.resolve(id);
 		if (idObject == null) {
 			idObject = factory.create(id);

src/main/java/com/l2jserver/model/id/object/provider/ClanIDProvider.java

@@ -59,7 +59,7 @@ public class ClanIDProvider implements ObjectIDProvider<ClanID> {
 	}
 
 	@Override
-	public ClanID createID(Integer id) {
+	public ClanID resolveID(Integer id) {
 		ClanID idObject = idService.resolve(id);
 		if (idObject == null) {
 			idObject = factory.create(id);

src/main/java/com/l2jserver/model/id/object/provider/ItemIDProvider.java

@@ -59,7 +59,7 @@ public class ItemIDProvider implements ObjectIDProvider<ItemID> {
 	}
 
 	@Override
-	public ItemID createID(Integer id) {
+	public ItemID resolveID(Integer id) {
 		ItemID idObject = idService.resolve(id);
 		if (idObject == null) {
 			idObject = factory.create(id);

src/main/java/com/l2jserver/model/id/object/provider/NPCIDProvider.java

@@ -58,7 +58,7 @@ public class NPCIDProvider implements ObjectIDProvider<NPCID> {
 	}
 
 	@Override
-	public NPCID createID(Integer id) {
+	public NPCID resolveID(Integer id) {
 		NPCID idObject = idService.resolve(id);
 		if (idObject == null) {
 			idObject = factory.create(id);

src/main/java/com/l2jserver/model/id/object/provider/ObjectIDResolver.java

@@ -18,19 +18,34 @@ package com.l2jserver.model.id.object.provider;
 
 import com.google.inject.Inject;
 import com.l2jserver.model.id.ObjectID;
+import com.l2jserver.model.id.object.ActorID;
+import com.l2jserver.model.id.object.CharacterID;
+import com.l2jserver.model.id.object.NPCID;
 import com.l2jserver.service.game.world.WorldIDService;
 
 /**
- * <h1>THIS PROVIDER IS READ ONLY!</h1>
+ * <b>THIS PROVIDER IS READ ONLY!</b>
  * <p>
- * This is an ID resolver that will lookup for IDs in {@link WorldIDService}.
- * Since this is only a resolver, only read operations can be performed and
- * {@link #createID()} and {@link #destroy(ObjectID)} will throw
- * {@link UnsupportedOperationException}.
+ * This is an ID resolver that will lookup for <b>existing</b> IDs in
+ * {@link WorldIDService}. Since this is only a resolver, only read operations
+ * can be performed. Methods {@link #createID()} and {@link #destroy(ObjectID)}
+ * will throw {@link UnsupportedOperationException}.
  * <p>
- * Another important aspect is that in {@link #createID(Integer)} if the ID is
- * not found, it will <b>NOT</b> be created, instead <tt>null</tt> will be
+ * Another important aspect is that in {@link #resolveID(Integer)} if the ID is
+ * not found, it will <b>NOT</b> create it, instead <tt>null</tt> will be
  * returned. You must use specific a {@link ObjectIDProvider} for that.
+ * <p>
+ * <h1>Use case</h1>
+ * You should only use this class if you don't know which {@link ObjectID} to
+ * expect or you are expecting multiple types (like {@link CharacterID} or
+ * {@link NPCID} both of them extend {@link ActorID}).
+ * <p>
+ * <h1>Type safe notice</h1>
+ * All IDs returned by this class are {@link ObjectID}. However sub-types cannot
+ * be ensured and you must check them manually in order to avoid unneeded
+ * {@link ClassCastException}. Even if you are sure that an given
+ * {@link ObjectID} is from an certain sub-type, do not assume that it will be
+ * always and do an checking.
  * 
  * @author <a href="http://www.rogiel.com">Rogiel</a>
  */
@@ -45,13 +60,18 @@ public class ObjectIDResolver implements ObjectIDProvider<ObjectID<?>> {
 		this.idService = idService;
 	}
 
+	/**
+	 * Resolvers do not support creating new IDs
+	 * 
+	 * @throws UnsupportedOperationException
+	 */
 	@Override
 	public ObjectID<?> createID() {
 		throw new UnsupportedOperationException();
 	}
 
 	@Override
-	public ObjectID<?> createID(Integer id) {
+	public ObjectID<?> resolveID(Integer id) {
 		return idService.resolve(id);
 	}
 
@@ -67,9 +87,14 @@ public class ObjectIDResolver implements ObjectIDProvider<ObjectID<?>> {
 	 */
 	@SuppressWarnings("unchecked")
 	public <T extends ObjectID<?>> T resolve(Integer id) {
-		return (T) createID(id);
+		return (T) resolveID(id);
 	}
 
+	/**
+	 * Resolvers do not support destroying IDs
+	 * 
+	 * @throws UnsupportedOperationException
+	 */
 	@Override
 	public void destroy(ObjectID<?> id) {
 		throw new UnsupportedOperationException();

src/main/java/com/l2jserver/model/id/object/provider/PetIDProvider.java

@@ -59,7 +59,7 @@ public class PetIDProvider implements ObjectIDProvider<PetID> {
 	}
 
 	@Override
-	public PetID createID(Integer id) {
+	public PetID resolveID(Integer id) {
 		PetID idObject = idService.resolve(id);
 		if (idObject == null) {
 			idObject = factory.create(id);

src/main/java/com/l2jserver/model/id/provider/IDProvider.java

@@ -40,5 +40,5 @@ public interface IDProvider<I, T extends ID<I>> {
 	 * @param id
 	 * @return
 	 */
-	T createID(I id);
+	T resolveID(I id);
 }

src/main/java/com/l2jserver/model/world/npc/controller/TeleporterController.java

@@ -45,7 +45,7 @@ public class TeleporterController extends BaseNPCController {
 		if (args.length >= 2) {
 			if (args[0].equals("goto")) {
 				final TeleportationTemplate tele = teleportationIdProvider
-						.createID(Integer.parseInt(args[1])).getTemplate();
+						.resolveID(Integer.parseInt(args[1])).getTemplate();
 				if (tele == null) {
 					// TODO notify user that his destination is invalid
 					conn.sendActionFailed();