Javadoc improvement and renamed IDProvider#createID(Object) to

resolveID(Object)

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

src/dao/com/l2jserver/db/dao/jdbc/JDBCCharacterDAO.java

@@ -123,7 +123,7 @@ public abstract class JDBCCharacterDAO extends
 	private final Mapper<CharacterID> idMapper = new Mapper<CharacterID>() {
 		@Override
 		public CharacterID map(ResultSet rs) throws SQLException {
-			return idFactory.createID(rs.getInt(CHAR_ID));
+			return idFactory.resolveID(rs.getInt(CHAR_ID));
 		}
 	};
 
@@ -138,16 +138,16 @@ public abstract class JDBCCharacterDAO extends
 			final CharacterClass charClass = CharacterClass.valueOf(rs
 					.getString(CLASS));
 			final CharacterTemplateID templateId = templateIdFactory
-					.createID(charClass.id);
+					.resolveID(charClass.id);
 			final CharacterTemplate template = templateId.getTemplate();
 
 			final L2Character character = template.create();
 
 			character.setID(id);
-			character.setAccountID(accountIdFactory.createID(rs
+			character.setAccountID(accountIdFactory.resolveID(rs
 					.getString(ACCOUNT_ID)));
 			if (rs.getString(CLAN_ID) != null)
-				character.setClanID(clanIdFactory.createID(rs.getInt(CLAN_ID)));
+				character.setClanID(clanIdFactory.resolveID(rs.getInt(CLAN_ID)));
 
 			character.setName(rs.getString(NAME));
 

src/dao/com/l2jserver/db/dao/jdbc/JDBCCharacterFriendDAO.java

@@ -78,9 +78,9 @@ public abstract class JDBCCharacterFriendDAO extends
 	private final Mapper<FriendID> idMapper = new Mapper<FriendID>() {
 		@Override
 		public FriendID map(ResultSet rs) throws SQLException {
-			final CharacterID characterId = charIdProvider.createID(rs
+			final CharacterID characterId = charIdProvider.resolveID(rs
 					.getInt(CHAR_ID));
-			final CharacterID friendId = charIdProvider.createID(rs
+			final CharacterID friendId = charIdProvider.resolveID(rs
 					.getInt(CHAR_ID_FRIEND));
 			return idProvider.createID(characterId, friendId);
 		}

src/dao/com/l2jserver/db/dao/jdbc/JDBCChatMessageDAO.java

@@ -82,7 +82,7 @@ public abstract class JDBCChatMessageDAO extends
 	private final Mapper<ChatMessageID> idMapper = new Mapper<ChatMessageID>() {
 		@Override
 		public ChatMessageID map(ResultSet rs) throws SQLException {
-			return idFactory.createID(rs.getInt(MESSAGE_ID));
+			return idFactory.resolveID(rs.getInt(MESSAGE_ID));
 		}
 	};
 
@@ -100,13 +100,13 @@ public abstract class JDBCChatMessageDAO extends
 			message.setType(ChatMessageType.valueOf(rs.getString(TYPE)));
 			switch (message.getType()) {
 			case SHOUT:
-				message.setTarget(charIdFactory.createID(rs.getInt(CHANNEL_ID)));
+				message.setTarget(charIdFactory.resolveID(rs.getInt(CHANNEL_ID)));
 				break;
 			default:
 				message.setChannelID(rs.getInt(CHANNEL_ID));
 				break;
 			}
-			message.setSender(charIdFactory.createID(rs.getInt(SENDER)));
+			message.setSender(charIdFactory.resolveID(rs.getInt(SENDER)));
 			message.setDate(new Date(rs.getTimestamp(DATE).getTime()));
 			message.setMessage(rs.getString(MESSAGE));
 

src/dao/com/l2jserver/db/dao/jdbc/JDBCClanDAO.java

@@ -75,7 +75,7 @@ public abstract class JDBCClanDAO extends AbstractJDBCDAO<Clan, ClanID> implemen
 	private final Mapper<ClanID> idMapper = new Mapper<ClanID>() {
 		@Override
 		public ClanID map(ResultSet rs) throws SQLException {
-			return idFactory.createID(rs.getInt(CLAN_ID));
+			return idFactory.resolveID(rs.getInt(CLAN_ID));
 		}
 	};
 

src/dao/com/l2jserver/db/dao/jdbc/JDBCItemDAO.java

@@ -96,7 +96,7 @@ public abstract class JDBCItemDAO extends AbstractJDBCDAO<Item, ItemID> implemen
 	private final Mapper<ItemID> idMapper = new Mapper<ItemID>() {
 		@Override
 		public ItemID map(ResultSet rs) throws SQLException {
-			return idFactory.createID(rs.getInt(ITEM_ID));
+			return idFactory.resolveID(rs.getInt(ITEM_ID));
 		}
 	};
 
@@ -107,14 +107,14 @@ public abstract class JDBCItemDAO extends AbstractJDBCDAO<Item, ItemID> implemen
 			database, idMapper) {
 		@Override
 		public Item map(ItemID id, ResultSet rs) throws SQLException {
-			final ItemTemplateID templateId = templateIdFactory.createID(rs
+			final ItemTemplateID templateId = templateIdFactory.resolveID(rs
 					.getInt(TEMPLATE_ID));
 			final ItemTemplate template = templateId.getTemplate();
 			final Item item = template.create();
 
 			item.setID(id);
 			if (rs.getObject(CHAR_ID) != null)
-				item.setOwnerID(charIdFactory.createID(rs.getInt(CHAR_ID)));
+				item.setOwnerID(charIdFactory.resolveID(rs.getInt(CHAR_ID)));
 			if (rs.getObject(LOCATION) != null)
 				item.setLocation(InventoryLocation.valueOf(rs
 						.getString(LOCATION)));

src/dao/com/l2jserver/db/dao/jdbc/JDBCNPCDAO.java

@@ -93,7 +93,7 @@ public abstract class JDBCNPCDAO extends AbstractJDBCDAO<NPC, NPCID> implements
 		public NPCID map(ResultSet rs) throws SQLException {
 			if (rs.getString(NPC_ID) == null)
 				return null;
-			return idProvider.createID(rs.getInt(NPC_ID));
+			return idProvider.resolveID(rs.getInt(NPC_ID));
 		}
 	};
 
@@ -104,7 +104,7 @@ public abstract class JDBCNPCDAO extends AbstractJDBCDAO<NPC, NPCID> implements
 			idMapper) {
 		@Override
 		protected NPC map(NPCID id, ResultSet rs) throws SQLException {
-			NPCTemplateID templateId = templateIdProvider.createID(rs
+			NPCTemplateID templateId = templateIdProvider.resolveID(rs
 					.getInt(NPC_TEMPLATE_ID));
 			NPCTemplate template = templateId.getTemplate();
 			if (template == null) {

src/main/java/com/l2jserver/game/net/packet/client/CM_AUTH_LOGIN.java

@@ -81,7 +81,7 @@ public class CM_AUTH_LOGIN extends AbstractClientPacket {
 
 	@Override
 	public void process(final Lineage2Client conn) {
-		final AccountID accountId = accountIdFactory.createID(loginName);
+		final AccountID accountId = accountIdFactory.resolveID(loginName);
 		conn.setSession(new Lineage2Session(accountId, playKey1, playKey2,
 				loginKey1, loginKey2));
 

src/main/java/com/l2jserver/game/net/packet/client/CM_CHAR_CREATE.java

@@ -193,7 +193,7 @@ public class CM_CHAR_CREATE extends AbstractClientPacket {
 
 		// create template id and lookup for the template instance
 		final CharacterTemplateID templateId = characterTemplateIdProvider
-				.createID(characterClass.id);
+				.resolveID(characterClass.id);
 		final CharacterTemplate template = templateId.getTemplate();
 		log.debug("Creating character with template {}", template);
 

src/main/java/com/l2jserver/game/net/packet/client/CM_REQUEST_CHAR_TEMPLATE.java

@@ -80,7 +80,7 @@ public class CM_REQUEST_CHAR_TEMPLATE extends AbstractClientPacket {
 		final CharacterTemplate[] templates = new CharacterTemplate[TEMPLATE_CLASSES.length];
 		int i = 0;
 		for (final CharacterClass charClass : TEMPLATE_CLASSES) {
-			final CharacterTemplateID id = idFactory.createID(charClass.id);
+			final CharacterTemplateID id = idFactory.resolveID(charClass.id);
 			templates[i++] = id.getTemplate();
 		}
 		conn.write(new SM_CHAR_TEMPLATE(templates));

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();

src/main/java/com/l2jserver/service/game/chat/DatabaseChatLoggingService.java

@@ -58,7 +58,7 @@ public class DatabaseChatLoggingService extends AbstractService implements
 		switch (channel.getMessageType()) {
 		case SHOUT: // if type is SHOUT the ChannelID is the CharacterID
 					// (target)
-			message.setTarget(charIdProvider.createID(channel.getChannelID()));
+			message.setTarget(charIdProvider.resolveID(channel.getChannelID()));
 			break;
 		default:
 			message.setChannelID(channel.getChannelID());

src/main/java/com/l2jserver/util/jaxb/CharacterTemplateIDAdapter.java

@@ -41,7 +41,7 @@ public class CharacterTemplateIDAdapter extends
 	public CharacterTemplateID unmarshal(CharacterClass v) throws Exception {
 		if (v == null)
 			return null;
-		return provider.createID(v.id);
+		return provider.resolveID(v.id);
 	}
 
 	@Override

src/main/java/com/l2jserver/util/jaxb/ItemTemplateIDAdapter.java

@@ -45,7 +45,7 @@ public class ItemTemplateIDAdapter extends XmlAdapter<Integer, ItemTemplateID> {
 			return null;
 		if (provider == null)
 			return new ItemTemplateID(v, null);
-		return provider.createID(v);
+		return provider.resolveID(v);
 	}
 
 	@Override

src/main/java/com/l2jserver/util/jaxb/NPCTemplateIDAdapter.java

@@ -45,7 +45,7 @@ public class NPCTemplateIDAdapter extends XmlAdapter<Integer, NPCTemplateID> {
 			return null;
 		if (provider == null)
 			return new NPCTemplateID(v, null);
-		return provider.createID(v);
+		return provider.resolveID(v);
 	}
 
 	@Override

src/main/java/com/l2jserver/util/jaxb/SkillTemplateIDAdapter.java

@@ -46,7 +46,7 @@ public class SkillTemplateIDAdapter extends
 			return null;
 		if (provider == null)
 			return new SkillTemplateID(v, null);
-		return provider.createID(v);
+		return provider.resolveID(v);
 	}
 
 	@Override

src/main/java/com/l2jserver/util/jaxb/TeleportationTemplateIDAdapter.java

@@ -47,7 +47,7 @@ public class TeleportationTemplateIDAdapter extends
 			return null;
 		if (provider == null)
 			return new TeleportationTemplateID(v, null);
-		return provider.createID(v);
+		return provider.resolveID(v);
 	}
 
 	@Override

src/test/java/com/l2jserver/db/dao/mysql5/MySQL5CharacterDAOTest.java

@@ -45,9 +45,9 @@ public class MySQL5CharacterDAOTest {
 
 		final CharacterDAO dao = injector.getInstance(CharacterDAO.class);
 		final L2Character char1 = dao.select(injector.getInstance(
-				CharacterIDProvider.class).createID(268437456));
+				CharacterIDProvider.class).resolveID(268437456));
 		final L2Character char2 = dao.select(injector.getInstance(
-				CharacterIDProvider.class).createID(268437456));
+				CharacterIDProvider.class).resolveID(268437456));
 
 		Assert.assertSame(char1, char2);
 	}

src/test/java/com/l2jserver/model/id/factory/IDFactoryTest.java

@@ -66,7 +66,7 @@ public class IDFactoryTest {
 
 	@Test
 	public void testGetObject() throws ServiceStartException {
-		final CharacterID id = charIdFactory.createID(268437456);
+		final CharacterID id = charIdFactory.resolveID(268437456);
 		final L2Character character = id.getObject();
 
 		Assert.assertNotNull(character);

src/test/java/com/l2jserver/service/game/template/StaticTemplateServiceTest.java

@@ -36,6 +36,6 @@ public class StaticTemplateServiceTest {
 	@Test
 	public void testAdena() throws ServiceStartException {
 		injector.getInstance(ServiceManager.class).start(TemplateService.class);
-		System.out.println(factory.createID(57).getTemplate());
+		System.out.println(factory.resolveID(57).getTemplate());
 	}
 }