Small documentation changes

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

src/main/java/com/l2jserver/model/Model.java

@@ -17,6 +17,7 @@
 package com.l2jserver.model;
 
 import com.l2jserver.model.id.ID;
+import com.l2jserver.service.database.DatabaseService;
 
 /**
  * @author <a href="http://www.rogiel.com">Rogiel</a>
@@ -41,17 +42,59 @@ public interface Model<T extends ID<?>> {
 	void setID(T ID) throws IllegalStateException;
 
 	/**
+	 * Each object has an desire. Desires express what the
+	 * {@link DatabaseService} should do with the object. The service
+	 * automatically keep tracks of every database object (and release them when
+	 * they are garbage collected).
+	 * 
 	 * @return the database object desire
 	 */
 	ObjectDesire getObjectDesire();
 
 	/**
+	 * Each object has an desire. Desires express what the
+	 * {@link DatabaseService} should do with the object. The service
+	 * automatically keep tracks of every database object (and release them when
+	 * they are garbage collected).
+	 * 
 	 * @param desire
 	 *            the database object desire to set
 	 */
 	void setObjectDesire(ObjectDesire desire);
 
+	/**
+	 * Indicated what the object wants to do in the database. It indicates
+	 * whether the object should be inserted, updated or deleted from the
+	 * database.
+	 * 
+	 * @author <a href="http://www.rogiel.com">Rogiel</a>
+	 */
 	public enum ObjectDesire {
-		NONE, INSERT, UPDATE, DELETE;
+		/**
+		 * Don't do anything
+		 */
+		NONE,
+		/**
+		 * Insert a new object into database.
+		 * <p>
+		 * If the primary key is auto generated by the database a clone of this
+		 * object will be created.<br>
+		 * If the primary key is <b>not</b> auto generated by the database, an
+		 * database exception will occur.
+		 */
+		INSERT,
+
+		/**
+		 * Updates the object in the database.
+		 * <p>
+		 * If the object is not in the database nothing will happen.
+		 */
+		UPDATE,
+		/**
+		 * Deletes the object from the database.
+		 * <p>
+		 * If tge object is not in the database nothing will happen.
+		 */
+		DELETE;
 	}
 }

src/main/java/com/l2jserver/service/cache/CacheService.java

@@ -38,7 +38,7 @@ public interface CacheService extends Service {
 	 * @param <T>
 	 *            the <tt>instance</tt> type
 	 * @param interfaceType
-	 *            the interface type
+	 *            the interface type. Remember, this must be an interface!
 	 * @param instance
 	 *            the instance implementing the interface
 	 * @return the cache-decorated object

src/main/java/com/l2jserver/service/cache/EhCacheService.java

@@ -61,9 +61,9 @@ public class EhCacheService extends AbstractService implements CacheService {
 			final T instance) {
 		Preconditions.checkNotNull(interfaceType, "interfaceType");
 		Preconditions.checkNotNull(instance, "instance");
+		Preconditions.checkArgument(interfaceType.isInterface(),
+		"interfaceType is not an interface");
 
-		if (!interfaceType.isInterface())
-			return null;
 		@SuppressWarnings("unchecked")
 		final T proxy = (T) Proxy.newProxyInstance(this.getClass()
 				.getClassLoader(), new Class[] { interfaceType },

src/main/java/com/l2jserver/service/cache/SoftCacheService.java

@@ -51,9 +51,9 @@ public class SoftCacheService extends AbstractService implements CacheService {
 			final T instance) {
 		Preconditions.checkNotNull(interfaceType, "interfaceType");
 		Preconditions.checkNotNull(instance, "instance");
+		Preconditions.checkArgument(interfaceType.isInterface(),
+				"interfaceType is not an interface");
 
-		if (!interfaceType.isInterface())
-			return null;
 		@SuppressWarnings("unchecked")
 		final T proxy = (T) Proxy.newProxyInstance(this.getClass()
 				.getClassLoader(), new Class[] { interfaceType },

src/main/java/com/l2jserver/service/cache/WeakCacheService.java

@@ -51,9 +51,9 @@ public class WeakCacheService extends AbstractService implements CacheService {
 			final T instance) {
 		Preconditions.checkNotNull(interfaceType, "interfaceType");
 		Preconditions.checkNotNull(instance, "instance");
+		Preconditions.checkArgument(interfaceType.isInterface(),
+				"interfaceType is not an interface");
 
-		if (!interfaceType.isInterface())
-			return null;
 		@SuppressWarnings("unchecked")
 		final T proxy = (T) Proxy.newProxyInstance(this.getClass()
 				.getClassLoader(), new Class[] { interfaceType },

src/main/java/com/l2jserver/service/game/DuelService.java

@@ -16,6 +16,7 @@
  */
 package com.l2jserver.service.game;
 
+import com.l2jserver.model.world.L2Character;
 import com.l2jserver.service.Service;
 
 /**
@@ -24,5 +25,24 @@ import com.l2jserver.service.Service;
  * @author <a href="http://www.rogiel.com">Rogiel</a>
  */
 public interface DuelService extends Service {
+	/**
+	 * Start the duel between the given two characters
+	 * 
+	 * @param character1
+	 *            the first character
+	 * @param character2
+	 *            the second character
+	 */
+	void start(L2Character character1, L2Character character2);
 
+	/**
+	 * Finishes the duel between the given two characters.<br>
+	 * <b>This must be called before the character is revived.</b>
+	 * 
+	 * @param character1
+	 *            the first character
+	 * @param character2
+	 *            the second character
+	 */
+	void stop(L2Character character1, L2Character character2);
 }

src/main/java/com/l2jserver/service/game/DuelServiceImpl.java

@@ -16,6 +16,7 @@
  */
 package com.l2jserver.service.game;
 
+import com.l2jserver.model.world.L2Character;
 import com.l2jserver.service.AbstractService;
 
 /**
@@ -24,5 +25,13 @@ import com.l2jserver.service.AbstractService;
  * @author <a href="http://www.rogiel.com">Rogiel</a>
  */
 public class DuelServiceImpl extends AbstractService implements DuelService {
+	@Override
+	public void start(L2Character character1, L2Character character2) {
+		// TODO Auto-generated method stub
+	}
 
+	@Override
+	public void stop(L2Character character1, L2Character character2) {
+		// TODO Auto-generated method stub
+	}
 }

src/main/java/com/l2jserver/service/game/LotteryService.java

@@ -16,6 +16,7 @@
  */
 package com.l2jserver.service.game;
 
+import com.l2jserver.model.world.Item;
 import com.l2jserver.model.world.L2Character;
 import com.l2jserver.service.Service;
 
@@ -46,4 +47,17 @@ public interface LotteryService extends Service {
 	 *            the fifth number
 	 */
 	void bet(L2Character character, int n1, int n2, int n3, int n4, int n5);
+
+	/**
+	 * @return the winning lottery ticket prize
+	 */
+	int getPrize();
+
+	/**
+	 * Redeem a winning lottery ticket prize
+	 * 
+	 * @param ticket
+	 *            the winning ticket
+	 */
+	void redeemPrize(Item ticket);
 }

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

@@ -22,7 +22,8 @@ import com.l2jserver.model.world.L2Character;
 import com.l2jserver.service.Service;
 
 /**
- * This service chatting in the server
+ * This service chatting in the server. Implementations can be local or can use
+ * another service like an IRC server.
  * 
  * @author <a href="http://www.rogiel.com">Rogiel</a>
  */

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

@@ -16,10 +16,16 @@
  */
 package com.l2jserver.service.game.chat;
 
+import com.l2jserver.model.id.object.CharacterID;
+
 /**
  * An public {@link ChatChannel}. Please note that the concept of "public" does
  * not mean it is available to anyone, but there are more than 2 player chatting
- * (i.e. clan, global, region, etc...)
+ * (i.e. clan, global, region, etc...). That mean that a single message can be
+ * broadcasted to more than a single client. Note that even in a public channel
+ * only a single event
+ * {@link ChatChannelListener#onMessage(ChatChannel, CharacterID, String)} will
+ * be dispatched per listener.
  * 
  * @author <a href="http://www.rogiel.com">Rogiel</a>
  */

src/main/java/com/l2jserver/service/game/effect/EffectService.java

@@ -20,7 +20,8 @@ import com.l2jserver.model.world.L2Character;
 import com.l2jserver.service.Service;
 
 /**
- * The effect service will handle
+ * The effect service will handle. This service will be backed by a thread that
+ * will execute the effect.
  * 
  * @author <a href="http://www.rogiel.com">Rogiel</a>
  */