Unity - Version 1.1.0 Server Documentation By: Derek Clayton derek@moock.org (c) Copyright 2001, 2002 All rights reserved ============================ ======================= ==== RELEASE NOTES ==== ======================= Please take note the method gotoRoom has been removed from this release. To upgrade to this release you will have to change gotoRoom to changeroom in your Room code. ============================= ==== SYSTEM REQUIREMENTS ==== ============================= 1. java version 1.2 or higher 2. a port available higher than 1024 ====================== ==== INSTALLATION ==== ====================== 1. Create a directory to contain the Unity files. (UNITY_HOME) 2. Unpack the files (.tar.gz for unix based systems and .zip for windows/mac) to the directory. 3. Ensure the following files are present: lib/unity_core.jar - server core classes lib/log4j.jar - logging support classes lib/jdom.jar - XML support classes lib/xerces.jar - XML support classes RoomTypes.xml - room defintion config RoomInstances.xml - room instantiation config server.xml - Unity config ss.lcf - log file config startserver.sh - script to start server startserver.bat - script to start server stopserver.sh - script to stop server stopserver.bat - script to stop server 4. Install a java runtime environment (or java development kit if you'll be creating your own rooms). You can download these at http://java.sun.com/products/. 5. Add the java binary (found in the bin directory of your java directory) to your system's path so it can be run from anywhere. 6. If you're itching to start Unity you can skip ahead to STARTING/STOPPING THE SERVER. ======================= ==== SERVER CONFIG ==== ======================= The server config is an XML based file. An example is: /usr/local/unity 9100 9101 password 0 RoomTypes.xml RoomInstances.xml UNITY_HOME (optional): the root directory where you installed Unity. Default: the current directory (.). SERVER_PORT: the port number that Unity will listen to for public connections. ADMIN_PORT: the port number that Unity will listen to for admin connnections. ADMIN_PASSWORD: the password for performing admin functions on Unity. EOM_CHARACTER (optional): the ASCII based character that will terminate communications between Unity and connected clients. Default: 0 or NULL. ROOM_TYPES (optional): path to the XML based file which sets the types of rooms available to Unity. Default: RoomTypes.xml ROOM_INSTANCES (optional): path to the XML based file which sets the instances of rooms deployed on Unity. Default: RoomInstances.xml ===================== ==== ROOM CONFIG ==== ===================== The distinction between a type of room and an instance of a room is subtle but important. A room type defines a room that can be instantiated by Unity. It tells Unity the name of the type of room and the actual java class that represents the room object. A room instance instantiates an actual room in Unity. It references a room type which tells Unity what kind of room it is. Think of rooms in a hotel. A hotel may only have 3 room types...economy, business, and luxury. However, the hotel may actually have 100 instances of rooms...25 economy, 25 business, and 50 luxury. The ROOM_TYPES takes the following form: chatRoom org.moock.unity.rooms.ChatRoom . . . ID: the alias to that room type. This id is used when deploying rooms during startup via ROOM_INSTANCES and also is used when creating rooms dynamically while Unity is running. CLASS: the fully qualified class name of the room which is defined by this type. The ROOM_INSTANCES takes the following form: Dispatcher dispatcherRoom sportsChat chatRoom 100 127.0.0.1chatLoginRoom . . . DEFAULTROOM: One, and only one, room must be declared as DEFAULTROOM instead of ROOM. This is the room that all clients connecting to Unity will be placed in first. It is the job of the room defined as the DEFAULTROOM to move clients to other rooms if necessary. Unity comes bundled with a custom room org.moock.unity.examples.rooms.Dispatcher which does forwarding to other rooms. ID: the alias used to reference the concrete implementation of the room. This id is used by custom rooms for identification when doing things such as moving to a room and broadcasting to other rooms. TYPE_ID: the ID of the type of room to create as referenced in ROOM_TYPES. MAX_CLIENTS (optional): the maximum number of clients allowed to connect to this room specified by an integer value. Once full all requests to access this room will be ignored. AUTHENTICATION.IP (optional): a comma separated string of ip's which are allowed to connect to this room. Clients not connecting from this IP will refused access to the room. AUTHENTICATION.SENTRY_ID: defines the ID of the concrete room defined in ROOM_INSTANCES which is the sentry of the room. If a room has a SENTRY_ID defined than requests to move to that room will only be honored from the Sentry room. If a request is made from a room other than the room defined as the Sentry than the client will be moved to the Sentry room for authentication. NOTE: A client need only satisfy 1 method of authentication to be granted access to the room. For example, if both a IP and SENTRY_ID tag are specified the server will check the ip list first. If the client is a valid ip then access will be granted. If not, then the client will be moved to the sentry room for validation. If the sentry room validates the client then access will be granted. Any tags within a room not recognized are stored as a property for the room. For example, public would create a property for the room of RUNSTATE = "public". Properties are retrieved by getProperty(String name). See roomdeveloper.txt for more info. ====================================== ==== STARTING/STOPPING THE SERVER ==== ====================================== Start Unity from within UNITY_HOME: java -cp CLASSPATH -Dlog4j.configuration=file:PATHTO_LOG_CONFIG org.moock.unity.core.Unity start PATHTO_SERVER_CONFIG (all 1 line) The CLASSPATH must include the files unity_core.jar and log4j.jar. The classpath must also include references to your custom rooms and any other support classes you use in your custom rooms. If the PATHTO_SERVER_CONFIG parameter is missing then the file server.xml in the current directory is assumed. For example, to start using the packaged rooms that come with Unity: Windows (all 1 line): java -cp d:\unity\lib\unity_core.jar;d:\unity\lib\log4j.jar;d:\unity\lib\jdom.jar; d:\unity\lib\xerces.jar;d:\unity\rooms\example_rooms.jar -Dlog4j.configuration= file:d:\unity\ss.lcf org.moock.unity.core.Unity start server.xml Unix (all 1 line): java -cp /usr/local/unity/lib/unity_core.jar:/usr/local/unity/lib/log4j.jar: /usr/local/unity/lib/jdom.jar:/usr/local/unity/lib/xerces.jar: /usr/local/unity/rooms/example_rooms.jar -Dlog4j.configuration= file:/usr/local/unity/ss.lcf org.moock.unity.core.Unity start server.xml Stop Unity with (all 1 line): java -cp CLASSPATH -Dlog4j.configuration=file:PATHTO_LOG_CONFIG org.moock.unity.core.Unity stop APORT PASSWORD The CLASSPATH must be set as for starting Unity. APORT is the port the admin was started on. Password is the admin password. Both APORT and PASSWORD are set in the server config file. Simple scripts have been provided for Windows (.bat) and Unix (.sh) to start and stop Unity named startserver and stopserver. Edit the parameters for your setup and run the scripts to start and stop Unity. ======================= ==== BUNDLED ROOMS ==== ======================= Unity comes with rooms you can deploy immediately without any additional coding. Used alone and/or in conjunction with clients downloaded from moock.org they will allow you to get substantial functionally from the server without writing a line of java code. They also make good templates for those making their first forays into extending the functionality of the basic room. Of particular interest to most developers will be the BroadcastRoom. This room has all of the functionality of most of the free socket servers you'll find out there and some commercial ones. It simply relays communications from one client to all the connected clients including the sender. Chances are if you're using a free server (including CommServer from moock.org) or a light commercial server then you can use BroadcastRoom to immediately port over your client applications. See the documentation within the code of each room in org/moock/unity/examples/rooms/. =========================== ==== USING THE CONSOLE ==== =========================== Use the startconsole.bat or startconsole.sh scripts or from the command line: java -cp lib\unity_core.jar org.moock.unity.core.Console [ip] [port] [password] ip = the ip where Unity is running port = the admin port as defined in server.xml password = the password as defined in server.xml ================= ==== LOGGING ==== ================= The level of logging and format of the log file is set by editting the ss.lcf log config file. For more information about logging see: http://jakarta.apache.org/log4j/docs/index.html ================================ ==== LINKS/ACKNOWLEDGEMENTS ==== ================================ JDOM http://www.jdom.org This product includes software developed by the Apache Software Foundation (http://www.apache.org/). Log4J http://jakarta.apache.org/log4j ======================== ==== CHANGE HISTORY ==== ======================== Version 1.1.1 (Jan. 27, 2003) --------------- - implemented a faster socket reader - fixed a bug which stopped the server from processing new connections - spawnRoom now returns code '2' and does nothing when trying to create a room that already exists - removed gotoRoom from the API...use changeRoom instead Version 1.1.0 (Nov. 21, 2002) --------------- - fixed a bug on dual-cpu machines that caused clients to connect rarely or not at all - the rooms/ directory and any jar files contained inside are automatically added to the classpath...jar files and class files placed in the rooms/ directory do not need to be added to the classpath when starting Unity - added GUI Console - config based authentication and the use of room "sentries" has been deprecated in favor of giving Room's more control over who and what level of access they would like to give...Rooms should now override the onRequestEntry method in the Room superclass to authenticate clients who would like access to the Room. - added getRoom() to the Room API to retrieve an instance of another Room on the server. - added getRoomNames() to the Room API to retrieve ID's for all rooms deployed to the server - getClientList() and getClientListButClient() now return one time copies of the list of clients...the copy is not mutated by the server - fixed a bug where messages placed in a client's queue just before calling gotoRoom() were ignored...see gotoRoom in javadoc - rooms now report their deaths (at warn level) - fixed a problem where all resources weren't being released by Rooms when they were killed with killRoom - fixed a problem with shutdown option sometimes not being received correctly Version 1.0.0 (Mar. 26, 2002) ------------- - released Version 0.9.3 (Mar. 18, 2002 - release internally) ------------- - squashed the Bug From Hell(tm) - added more Room functionality - messages are consumed by clients faster - client objects are processed on connect faster - small cleanup in how rooms are shut down when the server is shut down - fixed an error with ClientProperty Objects not being set correctly - clients are removed from rooms immediately on dying instead of when their resources are cleaned up (which was causing a small delay) - misc. little fixes Version 0.9.2 (Jan. 24, 2002) ------------- - improved thread management - rooms can now spawn other rooms (for example, spawning a private chat room from a public chat room, or spawning a game room from a game lobby) - server properties now retrieved from an xml config file (see CONFIGURING THE SERVER for more details) - added an object store to Client object for storing attributes to a specific client - added password to admin feature - improved server to client messaging - added broadcastRoomButClient, removeClient to Room functionality - added id's to clients...getClientID() from object Client returns an integer - improved object cleanup Version 0.9.1 (Dec. 30, 2001) ------------- - added more verbose and detailed logging in the core server - fixed problems when a room referenced a room alias that did not exist - extended rooms can no longer get a reference to RoomManager directly, use the RoomServices interface instead - renamed and added some methods to RoomServices - added shutdown through admin port (see STOPPING/STARTING THE SERVER) - version now shows in log on startup (at warn level) - fixed some thread liveness issues under certain conditions