Updated javadocs to match wiki content

src/main/java/com/l2jserver/service/core/LoggingService.java

@@ -16,12 +16,11 @@
  */
 package com.l2jserver.service.core;
 
-import org.slf4j.Logger;
-
 import com.l2jserver.service.Service;
 
 /**
- * The logging service is used to get instances of the {@link Logger} class.
+ * This service initializes and configures the logging provider. Currently SLF4J
+ * is used and implementations must initialize SLF4J and its respective binding.
  * 
  * @author <a href="http://www.rogiel.com">Rogiel</a>
  */

src/main/java/com/l2jserver/service/core/threading/ThreadPool.java

@@ -68,4 +68,10 @@ public interface ThreadPool {
 	ScheduledAsyncFuture async(long delay, TimeUnit unit, long repeat,
 			Runnable task);
 
+	/**
+	 * Disposes this thread pool. After disposing, it will no longer be able to
+	 * execute tasks.
+	 */
+	void dispose();
+
 }

src/main/java/com/l2jserver/service/core/threading/ThreadServiceImpl.java

@@ -281,5 +281,10 @@ public class ThreadServiceImpl extends AbstractService implements ThreadService
 			return new ScheduledAsyncFutureImpl(executor.scheduleAtFixedRate(
 					task, delay, repeat, unit));
 		}
+
+		@Override
+		public void dispose() {
+			ThreadServiceImpl.this.dispose(this);
+		}
 	}
 }

src/main/java/com/l2jserver/service/core/vfs/VFSService.java

@@ -23,8 +23,8 @@ import org.apache.commons.vfs.FileObject;
 import com.l2jserver.service.Service;
 
 /**
- * The VFS service provides access to files. With this service is possible to
+ * The VFS service is responsible for creating a Virtual File System that is
- * change the location of files.
+ * capable of reading files inside ZIP, TAR, BZIP and GZIP.
  * 
  * @author <a href="http://www.rogiel.com">Rogiel</a>
  */

src/main/java/com/l2jserver/service/database/DatabaseService.java

@@ -21,11 +21,21 @@ import com.l2jserver.model.id.ID;
 import com.l2jserver.service.Service;
 
 /**
- * The database service manages connection between the {@link DataAccessObject}
+ * This service provides access to an database implementation. Each
- * implementation and the database.
+ * implementation had its own {@link DataAccessObject} model, however they do
+ * need to respect {@link DataAccessObject} interfaces located in "
+ * <tt>com.l2jserver.db.dao</tt>". There can be several service implementation,
+ * but only one of them can be active at an given time.
+ * 
+ * The service does not directly provide much functionality most of its
+ * operations are done trough an {@link DataAccessObject}. Each service
+ * implementation provides an custom interface that is used to link
+ * {@link DataAccessObject}-{@link DatabaseService Service}. See implementation specific
+ * documentation for more information.
  * 
  * @author <a href="http://www.rogiel.com">Rogiel</a>
  */
 public interface DatabaseService extends Service {
-	<M extends Model<I>, I extends ID<M>> DataAccessObject<M, I> getDAO(Class<M> model);
+	<M extends Model<I>, I extends ID<M>> DataAccessObject<M, I> getDAO(
+			Class<M> model);
 }

src/main/java/com/l2jserver/service/database/JDBCDatabaseService.java

@@ -68,7 +68,24 @@ import com.l2jserver.util.ClassUtils;
 import com.l2jserver.util.factory.CollectionFactory;
 
 /**
- * The database service implementation for JDBC database
+ * This is an implementation of {@link DatabaseService} that provides an layer
+ * to JDBC.
+ * 
+ * <h1>Internal specification</h1> <h2>The {@link Query} object</h2>
+ * 
+ * If you wish to implement a new {@link DataAccessObject} you should try not
+ * use {@link Query} object directly because it only provides low level access
+ * to the JDBC architecture. Instead, you could use an specialized class, like
+ * {@link InsertUpdateQuery}, {@link SelectListQuery} or
+ * {@link SelectSingleQuery}. If you do need low level access, feel free to use
+ * the {@link Query} class directly.
+ * 
+ * <h2>The {@link Mapper} object</h2>
+ * 
+ * The {@link Mapper} object maps an JDBC {@link ResultSet} into an Java
+ * {@link Object}. All {@link Model} objects support {@link CachedMapper} that
+ * will cache result based on its {@link ID} and always use the same object with
+ * the same {@link ID}.
  * 
  * @author <a href="http://www.rogiel.com">Rogiel</a>
  */
@@ -333,7 +350,8 @@ public class JDBCDatabaseService extends AbstractService implements
 			int rows = 0;
 			while (iterator.hasNext()) {
 				final T object = iterator.next();
-				final PreparedStatement st = conn.prepareStatement(query(), Statement.RETURN_GENERATED_KEYS);
+				final PreparedStatement st = conn.prepareStatement(query(),
+						Statement.RETURN_GENERATED_KEYS);
 				this.parametize(st, object);
 				rows += st.executeUpdate();
 

src/main/java/com/l2jserver/service/game/character/CharacterService.java

@@ -16,7 +16,9 @@
  */
 package com.l2jserver.service.game.character;
 
+import com.l2jserver.model.game.CharacterFriend;
 import com.l2jserver.model.world.Actor;
+import com.l2jserver.model.world.Item;
 import com.l2jserver.model.world.L2Character;
 import com.l2jserver.service.Service;
 import com.l2jserver.service.game.npc.NotAttackableNPCServiceException;
@@ -27,7 +29,13 @@ import com.l2jserver.util.geometry.Coordinate;
 import com.l2jserver.util.geometry.Point3D;
 
 /**
- * This service manages {@link L2Character} instances
+ * This service manages all in-game {@link L2Character characters}. Every move
+ * or attack event must go through it.
+ * <p>
+ * This service is also used to create and delete characters. When deleting,
+ * implementations should make sure they remove all traces (except for logs)
+ * from the character, including {@link Item} and {@link CharacterFriend}
+ * objects.
  * 
  * @author <a href="http://www.rogiel.com">Rogiel</a>
  */

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

@@ -21,8 +21,18 @@ import com.l2jserver.model.server.ChatMessage;
 import com.l2jserver.service.Service;
 
 /**
- * This service logs each message sent in the server. Implementations may choose
+ * This service logs each message sent in the server. There can be several
- * to store in a database, plain text, XML or any other form of logging.
+ * implementations that stores logs in different locations (or don't store at
+ * all!) however only a single implementation can be active at any given time.
+ * <p>
+ * This service is called by contract in {@link ChatChannel} implementations.
+ * The <b>log</b> method creates a new {@link ChatMessage} object, stores it
+ * (optional) and returns the object. The same object will be sent to all
+ * {@link ChatChannelListener} and will contain: message text, sender and date.
+ * Other optional fields might also be available.
+ * <p>
+ * <b>{@link ChatChannelFilter} will be called before logging can occur. If any
+ * filter refuses the message, it will NOT be logged.</b>
  * 
  * @author <a href="http://www.rogiel.com">Rogiel</a>
  */

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

@@ -16,6 +16,8 @@
  */
 package com.l2jserver.service.game.chat;
 
+import com.l2jserver.game.net.packet.client.CM_CHAT;
+import com.l2jserver.game.net.packet.server.SM_CHAT;
 import com.l2jserver.model.id.object.CharacterID;
 import com.l2jserver.model.id.object.ClanID;
 import com.l2jserver.model.server.ChatMessage;
@@ -23,8 +25,37 @@ import com.l2jserver.model.world.L2Character;
 import com.l2jserver.service.Service;
 
 /**
- * This service provides chatting in the server. Implementations can be local or
+ * This service provides chatting in the server. There can be several
- * can use another service like an IRC server.
+ * implementations for this service, however only one of them can be active at a
+ * time. For example, implementations can use an backing IRC-Server that will
+ * provide flood control, channel control, reliability and external
+ * accessibility, people can talk to others even if not logged into the game.
+ * <p>
+ * Chat are divided into {@link ChatChannel channels}, each of those are
+ * respective to an determined section of the game chatting capabilities, i.e.
+ * trade chat (+) will be provided by the TradeChat channel. This is the concept
+ * of {@link PublicChatChannel} because in this type of channels, when one
+ * player writes an message it can possibly, however not forced to, be
+ * broadcasted to several other players, including itself in certain occasions
+ * (i.e. announcement channel).
+ * <p>
+ * There is also {@link PrivateChatChannel} that provide messaging capabilities
+ * among two players only. One will be the sender and one will be the receiver.
+ * In most situations, messages sent will not be sent back to the sender. In
+ * this type of channel, the message is guarantee to be received by the other
+ * player, if he is not available {@link ChatTargetOfflineServiceException} will
+ * be thrown.
+ * <p>
+ * All messages sent in any channel must be logged by {@link ChatLoggingService}
+ * unless it is refused by an {@link ChatChannelFilter}.
+ * 
+ * <h1>Chat ban</h1>
+ * If the sender is chat banned and tries to send a message
+ * {@link ChatBanActiveChatServiceException} will be thrown.
+ * 
+ * <h1>Packets</h1>
+ * Messages are received (from the clients) with {@link CM_CHAT} and sent (to
+ * the clients) with {@link SM_CHAT}.
  * 
  * @author <a href="http://www.rogiel.com">Rogiel</a>
  */

src/main/java/com/l2jserver/service/game/map/pathing/PathingService.java

@@ -18,10 +18,14 @@ package com.l2jserver.service.game.map.pathing;
 
 import com.l2jserver.model.world.PositionableObject;
 import com.l2jserver.service.Service;
+import com.l2jserver.service.game.map.MapService;
 import com.l2jserver.util.geometry.Point3D;
 
 /**
- * This service will try to find the best path to move to an given location.
+ * Service responsible for finding obstacles in the character moving line and
+ * tries to create a new path plan in order to avoid those obstacles. This
+ * service must work in conjunction with {@link MapService} that will map the
+ * entire game world, listing all obstacles and free locations.
  * 
  * @author <a href="http://www.rogiel.com">Rogiel</a>
  */

src/main/java/com/l2jserver/service/game/npc/NPCService.java

@@ -28,7 +28,8 @@ import com.l2jserver.service.game.character.CannotSetTargetServiceException;
 import com.l2jserver.util.geometry.Point3D;
 
 /**
- * This service manages {@link NPC} instances
+ * This service controls {@link NPC} objects. It can execute {@link NPC}
+ * interactions, kill it, move it and make it attack someone or be attacked.
  * 
  * @author <a href="http://www.rogiel.com">Rogiel</a>
  */

src/main/java/com/l2jserver/service/game/scripting/ScriptingService.java

@@ -20,11 +20,13 @@ import java.io.File;
 import java.util.Collection;
 import java.util.List;
 
+import com.l2jserver.game.ai.AI;
 import com.l2jserver.service.Service;
 
 /**
- * This service is capable of loading raw .java files, compile them and add to
+ * The scripting service provides script capabilities to the server. Scripts can
- * runtime.
+ * be used in events (in-game), Quests and {@link AI}. Implementations are free
+ * to use any language to implement scripts.
  * 
  * @author <a href="http://www.rogiel.com">Rogiel</a>
  */

src/main/java/com/l2jserver/service/game/spawn/SpawnService.java

@@ -18,8 +18,11 @@ package com.l2jserver.service.game.spawn;
 
 import java.util.concurrent.TimeUnit;
 
+import com.l2jserver.model.world.Actor;
 import com.l2jserver.model.world.Actor.ActorState;
+import com.l2jserver.model.world.Item;
 import com.l2jserver.model.world.L2Character;
+import com.l2jserver.model.world.NPC;
 import com.l2jserver.model.world.Player;
 import com.l2jserver.model.world.PositionableObject;
 import com.l2jserver.model.world.event.SpawnEvent;
@@ -27,11 +30,29 @@ import com.l2jserver.model.world.player.event.PlayerTeleportedEvent;
 import com.l2jserver.model.world.player.event.PlayerTeleportingEvent;
 import com.l2jserver.service.Service;
 import com.l2jserver.service.core.threading.AsyncFuture;
+import com.l2jserver.service.core.threading.ThreadService;
+import com.l2jserver.service.game.npc.NPCService;
 import com.l2jserver.util.geometry.Coordinate;
 import com.l2jserver.util.geometry.Point3D;
 
 /**
- * This service is responsible for spawning monsters, npcs and players.
+ * This service is responsible for spawning, unspawning and teleporting
+ * {@link Actor} and Item objects. If you spawn an {@link Item} object it will
+ * be the same as dropping it on the ground.
+ * <p>
+ * This service allows to be used synchronously or asynchronously if you wish to
+ * schedule an spawn/unspawn to happen at another time. However, teleporting
+ * must be done synchronously. Asynchronous usage is assisted by
+ * {@link ThreadService}.
+ * <p>
+ * Although the service supports teleporting Item objects, it has the same
+ * effect of an unspawn and spawn.
+ * 
+ * <h1>Usage of SpawnService with NPC/Monsters</h1> Although is possible to use
+ * this service to unspawn {@link NPC} objects, it is not recommended. If you
+ * do, the {@link NPC} will not be respawned. The only possible way to respawn
+ * it is through an forced spawn (manual) or server restart. See
+ * {@link NPCService} if you wish to correctly unspawn an {@link NPC}.
  * 
  * @author <a href="http://www.rogiel.com">Rogiel</a>
  */
@@ -72,8 +93,8 @@ public interface SpawnService extends Service {
 	 *            the unit of <tt>time</tt>
 	 * @return an future that can be used to obtain spawn exceptions
 	 */
-	<T extends PositionableObject> AsyncFuture<T> spawn(T object, Point3D point, long time,
+	<T extends PositionableObject> AsyncFuture<T> spawn(T object,
-			TimeUnit unit);
+			Point3D point, long time, TimeUnit unit);
 
 	/**
 	 * Unspawns an {@link PositionableObject} object from the world
@@ -97,7 +118,8 @@ public interface SpawnService extends Service {
 	 *            the unit of <tt>time</tt>
 	 * @return an future that can be used to obtain spawn exceptions
 	 */
-	<T extends PositionableObject> AsyncFuture<T> unspawn(T object, long time, TimeUnit unit);
+	<T extends PositionableObject> AsyncFuture<T> unspawn(T object, long time,
+			TimeUnit unit);
 
 	/**
 	 * Teleports the object to the given <tt>point</tt>.
@@ -129,8 +151,7 @@ public interface SpawnService extends Service {
 	 * @param character
 	 *            the character object
 	 * @throws CharacterNotTeleportingServiceException
-	 *             if the character state is not
+	 *             if the character state is not {@link ActorState#TELEPORTING}
-	 *             {@link ActorState#TELEPORTING}
 	 */
 	void finishTeleport(L2Character character)
 			throws CharacterNotTeleportingServiceException;

src/main/java/com/l2jserver/service/game/template/TemplateService.java

@@ -16,10 +16,24 @@
  */
 package com.l2jserver.service.game.template;
 
+import com.l2jserver.model.game.Skill;
 import com.l2jserver.model.id.TemplateID;
+import com.l2jserver.model.id.template.provider.TemplateIDProvider;
 import com.l2jserver.model.template.Template;
+import com.l2jserver.model.world.Item;
+import com.l2jserver.model.world.L2Character;
+import com.l2jserver.model.world.NPC;
 import com.l2jserver.service.Service;
 
+/**
+ * Service that loads {@link L2Character}, {@link NPC}, {@link Item} and
+ * {@link Skill} {@link Template templates}. The service on startup, loads from files or from the
+ * database the data and parses them into <tt>com.l2jserver.model.template</tt>
+ * classes. Once they are loaded, templates can be retrieved using any
+ * {@link TemplateID} object created from a {@link TemplateIDProvider}.
+ * 
+ * @author <a href="http://www.rogiel.com">Rogiel</a>
+ */
 public interface TemplateService extends Service {
 	/**
 	 * Get the template assigned with <tt>id</tt>

src/main/java/com/l2jserver/service/game/world/WorldService.java

@@ -19,15 +19,29 @@ package com.l2jserver.service.game.world;
 import java.util.Iterator;
 import java.util.List;
 
+import com.l2jserver.game.net.Lineage2Client;
 import com.l2jserver.model.id.ObjectID;
+import com.l2jserver.model.world.NPC;
 import com.l2jserver.model.world.PositionableObject;
 import com.l2jserver.model.world.WorldObject;
 import com.l2jserver.service.Service;
 import com.l2jserver.service.game.world.event.WorldEventDispatcher;
 import com.l2jserver.service.game.world.filter.WorldObjectFilter;
+import com.l2jserver.service.network.broadcast.BroadcastService;
 
 /**
- * Service responsible for managing {@link WorldObject} and dispatch events.
+ * One of the most important services in the whole server. It is responsible for
+ * keeping track of all {@link WorldObject WorldObjects} in the game virtual
+ * world: positioning, status, life and attributes.
+ * <p>
+ * As an example, once a new {@link NPC} is spawned, it is registered within
+ * this service and it can be broadcasted (using {@link BroadcastService}) to
+ * all nearby clients (see {@link Lineage2Client}).
+ * <h1>Other tasks</h1> World event dispatching is handled by
+ * {@link WorldEventDispatcher}.
+ * <p>
+ * {@link ObjectID} object management is done through {@link WorldIDService}
+ * that can be used to cache those IDs.
  * 
  * @author <a href="http://www.rogiel.com">Rogiel</a>
  */

src/main/java/com/l2jserver/service/network/NetworkService.java

@@ -17,13 +17,45 @@
 package com.l2jserver.service.network;
 
 import com.l2jserver.game.net.Lineage2Client;
+import com.l2jserver.game.net.Lineage2Session;
+import com.l2jserver.game.net.packet.ClientPacket;
 import com.l2jserver.game.net.packet.ServerPacket;
 import com.l2jserver.model.id.object.CharacterID;
+import com.l2jserver.model.world.L2Character;
 import com.l2jserver.service.Service;
 
 /**
- * The network service is responsible for communicating the server and the game
+ * The network service is responsible for communicating the server with the game
- * client. You can see more details in each implementation.
+ * client. The service can have several different implementations, however only
+ * a single one can be active at any given time.
+ * <p>
+ * This service is implementation of the Lineage II protocol and will do the
+ * following:
+ * 
+ * <ul>
+ * <li>Listen in the network port (default is 7777 for game server);</li>
+ * <li>Process incoming connections and filter them for blocked IPs (not yet
+ * implemented);</li>
+ * <li>Handshake with the client and enable Cryptography;</li>
+ * <li>Read incoming packets, decrypt and parse them into a ClientPacket;</li>
+ * <li>Write outgoing packets ServerPacket and encrypt them;</li>
+ * <li>(optional) Validate GameGuard responses (see GameGuardService);</li>
+ * </ul>
+ * 
+ * Each connection is represented by {@link Lineage2Client} and will be attached
+ * with {@link CharacterID} of the active character (if any),
+ * {@link Lineage2Session} with authorization keys from LoginServer and the raw
+ * connection socket (see implementations for more details).
+ * <p>
+ * It is also important to note that each {@link ClientPacket} have its own
+ * instruction set hard coded in it and they can be injected with any service
+ * using Guice framework.
+ * <p>
+ * The service can also be used to resolve {@link CharacterID} or
+ * {@link L2Character} to a {@link Lineage2Client} object in order to establish
+ * connection between the client connection and a game character.
+ * <p>
+ * Packet opcode resolver is implementation specific.
  * 
  * @author <a href="http://www.rogiel.com">Rogiel</a>
  */