next last content

2. Server

The Matrix server can be employed either as standalone Java program or a servlet contained version with additional HTTP tunneling ( see section 2.1 for more information ). Former versions were JDK 1.0.2 compatible. We switched to pure JDK1.1 so you will need a JDK1.1 or higher run time environment to run the server. It distributes all information between the client applets running on the users machines. The corresponding class file is matrix.server.MatrixD. The packages matrix, matrix.vrml and matix.server are necessary for the server program.

Synopsis :

java matrix.server.MatrixD [-loglevel level] [-port portnumber] [-rcfile name]

The first argument sets the detail level of logging information. This number has to be between 0 and 3 ( see also Loglevel in the description of the configuration file ). The second argument sets the TCP port number the server should listen to. The default value is 6666. The last argument gives the name and path of the configuration file the server should read on start-up. If none is given the default file called matrixrc is read.

If the server starts successfully, it will print some information to the console and then start to log information into the log file. If the standard output ( set below ) is given as the log file, the server will print all information to the console.

The server does not use an UDP port anymore. All communication is now conducted over the TCP stream.


# sample matrixrc file for demonstration

Loglevel 2    # 0 - 3

port  1009

logfile /usr/tmp/matrix.log

serverIP 126.23.46.1

waitingConnections 20



#here we start

start world/Start.wrl

cone world/cone.wrl 4 3

matrix matrix.wrl

The structure of such a file is very simple. Any characters after a # character are comment and ignored.

Loglevel
the server expects an integer between 0 and 3 to follow. This sets the detail of logging information to print to the standard output. 0 suppresses any information. 1 shows only errors, log ins and log outs. 2 adds room and avatar changes and 3 displays all information running over the server. This should be only used for debugging purposes. This setting is overridden by an optional command line argument.
port
an integer number that gives the port number the server listens to. This option can be overridden by a command line option.
logfile
gives the name of the log file the server should write to. If no logfile option is found in the configuration file it writes to the file server.log. The server also tries to append new log messages to an existing file. If the logfiles name is '-' the server writes the log to the standard output. This option is useful for debugging purposes.
serverIP
selects the IP address the server should listen to. Usefull if you have several IP addresses on your machine and want to run several virtual servers on the same port.
waitingConnections
sets the maximal numbers of connection requests to be queued.

Any other line has the syntax name url.name is a name for a certain VRML world and url is its location on the net. The name has to be unique and is important for jumping between different VRML worlds. This will be described in detail in the following chapters. The URL is either absolute or relative to the codebase of the client applet.

Optional there can be one or two numbers following the URL. These control the use of multiple instances of one room. The first number gives the maximal number of users in one room. If there are more users moving or logging in to one room than this number, a new instance of the room is created and any new users get into the new instance. So there are two independent groups of users, who receive no updates from each other, but have the same background VRML. If the second number is used, it gives the maximal number of such instances. If more users try to enter this room, they are denied this service. If it is not present, any number of instances is created.

2.1 HTTP Tunneling via Servlet

DeepMatrix now supports HTTP tunneling to work around problems with firewalls, network address translations etc. The client will transparently switch to HTTP tunneling, if configured ( see section 3. ) but the server has to setup properly. In the following we assume that you are familiar with Java servlets and servlets containers. For more information on these topics go to the Java Servlet page. A suitable servlet container is Tomcat.

The servlet class used to implement HTTP tunneling is matrix.server.MatrixServlet. It starts a normal DeepMatrix server inside the container ( still allowing the usuall TCP connections ), but also handles connections via HTTP. It implements a Cookie based session mechanism, so clients have to have cookies enabled. You will need the following classes in order to run the Servlet properly : matrix.*, matrix.server.*, matrix.vrml.*.

The Servlet itself has the following parameters, which substitute the command line parameters of the standalone server.

rcfile
locates the matrix configuration file. If the file is a relative path description, it is interpreted relative to the web applications directory.
port
The TCP port number to listen at, same as above.
loglevel
The loglevel to use, same as above.

The file web.xml is a sample configuration file for a web application based on the servlet. This is the recommended way to employ the servlet-server variant.

next last content