From 129b527a0849030aab2d76d298224d4f8e31ed1c Mon Sep 17 00:00:00 2001 From: Rogiel Date: Tue, 2 Aug 2011 16:35:08 -0300 Subject: [PATCH] Updated javadocs to match wiki content --- .../service/core/LoggingService.java | 5 ++- .../service/core/threading/ThreadPool.java | 6 ++++ .../core/threading/ThreadServiceImpl.java | 5 +++ .../service/core/vfs/VFSService.java | 4 +-- .../service/database/DatabaseService.java | 16 +++++++-- .../service/database/JDBCDatabaseService.java | 22 ++++++++++-- .../game/character/CharacterService.java | 10 +++++- .../service/game/chat/ChatLoggingService.java | 14 ++++++-- .../service/game/chat/ChatService.java | 35 ++++++++++++++++-- .../game/map/pathing/PathingService.java | 6 +++- .../service/game/npc/NPCService.java | 3 +- .../game/scripting/ScriptingService.java | 6 ++-- .../service/game/spawn/SpawnService.java | 33 +++++++++++++---- .../game/template/TemplateService.java | 14 ++++++++ .../service/game/world/WorldService.java | 16 ++++++++- .../service/network/NetworkService.java | 36 +++++++++++++++++-- 16 files changed, 203 insertions(+), 28 deletions(-) diff --git a/src/main/java/com/l2jserver/service/core/LoggingService.java b/src/main/java/com/l2jserver/service/core/LoggingService.java index ab5e111b3..809fd3fd3 100644 --- a/src/main/java/com/l2jserver/service/core/LoggingService.java +++ b/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 Rogiel */ diff --git a/src/main/java/com/l2jserver/service/core/threading/ThreadPool.java b/src/main/java/com/l2jserver/service/core/threading/ThreadPool.java index 2b84a5266..beaf17ab6 100644 --- a/src/main/java/com/l2jserver/service/core/threading/ThreadPool.java +++ b/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(); + } diff --git a/src/main/java/com/l2jserver/service/core/threading/ThreadServiceImpl.java b/src/main/java/com/l2jserver/service/core/threading/ThreadServiceImpl.java index de6be69a2..43b11abd4 100644 --- a/src/main/java/com/l2jserver/service/core/threading/ThreadServiceImpl.java +++ b/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); + } } } diff --git a/src/main/java/com/l2jserver/service/core/vfs/VFSService.java b/src/main/java/com/l2jserver/service/core/vfs/VFSService.java index 9d05dc3e2..5cd28558e 100644 --- a/src/main/java/com/l2jserver/service/core/vfs/VFSService.java +++ b/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 - * change the location of files. + * The VFS service is responsible for creating a Virtual File System that is + * capable of reading files inside ZIP, TAR, BZIP and GZIP. * * @author Rogiel */ diff --git a/src/main/java/com/l2jserver/service/database/DatabaseService.java b/src/main/java/com/l2jserver/service/database/DatabaseService.java index a02d41acf..568638786 100644 --- a/src/main/java/com/l2jserver/service/database/DatabaseService.java +++ b/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} - * implementation and the database. + * This service provides access to an database implementation. Each + * implementation had its own {@link DataAccessObject} model, however they do + * need to respect {@link DataAccessObject} interfaces located in " + * com.l2jserver.db.dao". 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 Rogiel */ public interface DatabaseService extends Service { - , I extends ID> DataAccessObject getDAO(Class model); + , I extends ID> DataAccessObject getDAO( + Class model); } diff --git a/src/main/java/com/l2jserver/service/database/JDBCDatabaseService.java b/src/main/java/com/l2jserver/service/database/JDBCDatabaseService.java index b7fec04d8..0b12e7821 100644 --- a/src/main/java/com/l2jserver/service/database/JDBCDatabaseService.java +++ b/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. + * + *

Internal specification

The {@link Query} object

+ * + * 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. + * + *

The {@link Mapper} object

+ * + * 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 Rogiel */ @@ -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(); diff --git a/src/main/java/com/l2jserver/service/game/character/CharacterService.java b/src/main/java/com/l2jserver/service/game/character/CharacterService.java index 4dcd92359..677e5f743 100644 --- a/src/main/java/com/l2jserver/service/game/character/CharacterService.java +++ b/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. + *

+ * 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 Rogiel */ diff --git a/src/main/java/com/l2jserver/service/game/chat/ChatLoggingService.java b/src/main/java/com/l2jserver/service/game/chat/ChatLoggingService.java index 5d877c97f..0a2475349 100644 --- a/src/main/java/com/l2jserver/service/game/chat/ChatLoggingService.java +++ b/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 - * to store in a database, plain text, XML or any other form of logging. + * This service logs each message sent in the server. There can be several + * 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. + *

+ * This service is called by contract in {@link ChatChannel} implementations. + * The log 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. + *

+ * {@link ChatChannelFilter} will be called before logging can occur. If any + * filter refuses the message, it will NOT be logged. * * @author Rogiel */ diff --git a/src/main/java/com/l2jserver/service/game/chat/ChatService.java b/src/main/java/com/l2jserver/service/game/chat/ChatService.java index df21f6587..84291a64b 100644 --- a/src/main/java/com/l2jserver/service/game/chat/ChatService.java +++ b/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 - * can use another service like an IRC server. + * This service provides chatting in the server. There can be several + * 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. + *

+ * 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). + *

+ * 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. + *

+ * All messages sent in any channel must be logged by {@link ChatLoggingService} + * unless it is refused by an {@link ChatChannelFilter}. + * + *

Chat ban

+ * If the sender is chat banned and tries to send a message + * {@link ChatBanActiveChatServiceException} will be thrown. + * + *

Packets

+ * Messages are received (from the clients) with {@link CM_CHAT} and sent (to + * the clients) with {@link SM_CHAT}. * * @author Rogiel */ diff --git a/src/main/java/com/l2jserver/service/game/map/pathing/PathingService.java b/src/main/java/com/l2jserver/service/game/map/pathing/PathingService.java index d7df5303a..de8e3ae7b 100644 --- a/src/main/java/com/l2jserver/service/game/map/pathing/PathingService.java +++ b/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 Rogiel */ diff --git a/src/main/java/com/l2jserver/service/game/npc/NPCService.java b/src/main/java/com/l2jserver/service/game/npc/NPCService.java index 97ebcbe4d..154d9f45b 100644 --- a/src/main/java/com/l2jserver/service/game/npc/NPCService.java +++ b/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 Rogiel */ diff --git a/src/main/java/com/l2jserver/service/game/scripting/ScriptingService.java b/src/main/java/com/l2jserver/service/game/scripting/ScriptingService.java index e2125f5f1..768912e4e 100644 --- a/src/main/java/com/l2jserver/service/game/scripting/ScriptingService.java +++ b/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 - * runtime. + * The scripting service provides script capabilities to the server. Scripts can + * be used in events (in-game), Quests and {@link AI}. Implementations are free + * to use any language to implement scripts. * * @author Rogiel */ diff --git a/src/main/java/com/l2jserver/service/game/spawn/SpawnService.java b/src/main/java/com/l2jserver/service/game/spawn/SpawnService.java index 1dbc1d36b..ac77af1d9 100644 --- a/src/main/java/com/l2jserver/service/game/spawn/SpawnService.java +++ b/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. + *

+ * 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}. + *

+ * Although the service supports teleporting Item objects, it has the same + * effect of an unspawn and spawn. + * + *

Usage of SpawnService with NPC/Monsters

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 Rogiel */ @@ -72,8 +93,8 @@ public interface SpawnService extends Service { * the unit of time * @return an future that can be used to obtain spawn exceptions */ - AsyncFuture spawn(T object, Point3D point, long time, - TimeUnit unit); + AsyncFuture spawn(T object, + 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 time * @return an future that can be used to obtain spawn exceptions */ - AsyncFuture unspawn(T object, long time, TimeUnit unit); + AsyncFuture unspawn(T object, long time, + TimeUnit unit); /** * Teleports the object to the given point. @@ -129,8 +151,7 @@ public interface SpawnService extends Service { * @param character * the character object * @throws CharacterNotTeleportingServiceException - * if the character state is not - * {@link ActorState#TELEPORTING} + * if the character state is not {@link ActorState#TELEPORTING} */ void finishTeleport(L2Character character) throws CharacterNotTeleportingServiceException; diff --git a/src/main/java/com/l2jserver/service/game/template/TemplateService.java b/src/main/java/com/l2jserver/service/game/template/TemplateService.java index 1f09642f2..cdf0daffb 100644 --- a/src/main/java/com/l2jserver/service/game/template/TemplateService.java +++ b/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 com.l2jserver.model.template + * classes. Once they are loaded, templates can be retrieved using any + * {@link TemplateID} object created from a {@link TemplateIDProvider}. + * + * @author Rogiel + */ public interface TemplateService extends Service { /** * Get the template assigned with id diff --git a/src/main/java/com/l2jserver/service/game/world/WorldService.java b/src/main/java/com/l2jserver/service/game/world/WorldService.java index 81ef7f56c..324dac9a3 100644 --- a/src/main/java/com/l2jserver/service/game/world/WorldService.java +++ b/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. + *

+ * 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}). + *

Other tasks

World event dispatching is handled by + * {@link WorldEventDispatcher}. + *

+ * {@link ObjectID} object management is done through {@link WorldIDService} + * that can be used to cache those IDs. * * @author Rogiel */ diff --git a/src/main/java/com/l2jserver/service/network/NetworkService.java b/src/main/java/com/l2jserver/service/network/NetworkService.java index 27da53931..f461de0d4 100644 --- a/src/main/java/com/l2jserver/service/network/NetworkService.java +++ b/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 - * client. You can see more details in each implementation. + * The network service is responsible for communicating the server with the game + * client. The service can have several different implementations, however only + * a single one can be active at any given time. + *

+ * This service is implementation of the Lineage II protocol and will do the + * following: + * + *

    + *
  • Listen in the network port (default is 7777 for game server);
    • + *
  • Process incoming connections and filter them for blocked IPs (not yet + * implemented);
    • + *
  • Handshake with the client and enable Cryptography;
    • + *
  • Read incoming packets, decrypt and parse them into a ClientPacket;
    • + *
  • Write outgoing packets ServerPacket and encrypt them;
    • + *
  • (optional) Validate GameGuard responses (see GameGuardService);
    • + *
+ * + * 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). + *

+ * 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. + *

+ * 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. + *

+ * Packet opcode resolver is implementation specific. * * @author Rogiel */