j-Chat v1.0 User's Guide

The following topics are discussed in this User's Guide:

If you do not find the answers to your questions here, visit the J&J Computer Consulting j-Chat Home Page for more information.

j-Chat, like many other Java programs, does not come with an installation program. You should receive j-Chat in a compressed, zip file. Create a directory for j-Chat and unzip the file using the appropriate options to maintain the directory structure. For Pkunzip, the appropriate command would be:

For OS/2 users, the command would be:

Important:The unzip utility used must support long file names.

j-Chat creates the following files and directories from from the zip file.

• jChatServer - j-Chat Server directory for program and configuration files.
• jChatClient - j-Chat Client directory for program files.
• Docs - The Docs directory contains this User's Guide and the Program License Agreement.

If you plan to run j-Chat as a Java application without using a web page, you can either transfer the jChatClient.jar file to each system you want to use the j-Chat Client on or transfer all of the files from the jChatClient/class directory to the target system. If you use the JAR file, you will need to add the JAR file to your classpath. Using the class files does not require modification of your classpath.

If you plan to run j-Chat in conjunction with a web server, you will need to move the files from the j-Chat Server directory onto the web server. Due to the security restrictions put on Java applets, the j-Chat Server must run on the same machine that is used to serve the j-Chat Client. You will also need to transfer the jChatClient.jar file to an accessible location within your web server directory and embed the included applet in a web page. A sample HTML page is included in the jChatClient directory that can be used as a starting point in setting up access to the j-Chat Client through a web page.

j-Chat's configuration is stored in several, simple text files. The hosts.dat file lists each of the host names to which the chat system should respond. Host names can be aliased all to the same IP address, assigned to different IP addresses, or can use a combination of both aliases and IP address assignments. j-Chat's underlying protocol, however, relies on the host name as opposed to the IP address to serve its list of rooms, so multiple IP addresses on a single system are not necessary.

For each host listed in the hosts.dat file, j-Chat expects to find a file with the same name as the host. A list of rooms should be stored in that file along with a flag identifying the room as password protected or not password protected.

If a room is password protected, j-Chat expects to find a file named roomname.pwl with roomname replaced by the name given to the room. Inside that file should be a list of nicknames and passwords for users that should have access to the chat room.

All of the configuration files must be located in the same directory as the j-Chat Server class files. Some sample configuration files have been included that set up the following chat system:

• Host - chathost1.yourdomain.com
  • Sample Room 1 - Private
    • User: user1 Password: abcdefg
    • User: user2 Password: jchat123
  • Sample Room 2 - Public
• Host - chathost2.yourdomain.com
  • MyChatRoom - Public

To activate any configuration changes, you must shut down and restart the j-Chat Server.

Once you have the j-Chat Server configured, you are ready to start it up. The procedure for starting the j-Chat Server depends on your particular platform, JVM, and/or JRE. Change to the directory where the j-Chat Server files are located. For OS/2 users, the following command will start the server:

The parameter passed to the system is the port number on which the j-Chat Server should run. If you do not pass this parameter, j-Chat will default to port 5050.

Other systems should use a variant of the above command. If you do not have a full JDK installed, you will most likely have to use a command like:

OS/2 users can create an object to start the j-Chat Server by completing the following procedure:

1. Drag a Program template to your desktop.
2. In the Properties, make the following changes:
   • Path and file name should be "java.exe".
   • Parameters should be "jChatServer 5050"
   • Working directory should be the location of the j-Chat Server class files. (Important)
3. Change the name of the Program to j-Chat Server, and you should be ready to go.

Command and batch files can be used to automate the startup process on other systems.

While the j-Chat Server is running, it generates a log file of logons, messages sent in rooms, and logoffs. Using this log, you should be able to reconstruct chats that took place in any room. The log is located in the same directory as the server and is named jchat.log. There is also a jchaterror.log file that logs errors displayed on the server console, but as of this release, very few errors are actually printed to the error log.

j-Chat Client Configuration depends on the use of the j-Chat Client. The j-Chat Client can be used from a browser through a web page or as a regular application without a browser.

1. j-Chat Client Configuration for the Web

   The file jChatClient.jar can be found in the jChatClient subdirectory of where you unzipped j-Chat. Move this file to a location on your website. The location does not necessarily have to be the same as where the page you use to start j-Chat exists. Now move the jChatPage.html file from the jChatClient subdirectory to the appropriate location on your web site. Inside jChatPage.html is the appropriate HTML code to start the j-Chat Client on a server called chathost1.yourdomain.com.

   Both the j-Chat Client and the applet used to start the j-Chat Client take two parameters. The first parameter is the host name of the j-Chat Server. The second parameter is the port number on which the j-Chat Server is running. jChatPage.html includes PARAM tags inside the APPLET tag to pass the appropriate parameters to the j-Chat Client Applet.

   The source code for the j-Chat Client Applet has been included so you can customize its appearance or function in any way you see fit. The source file can be found in the jChatClient/AppletSource directory. If you decide to customize this file, you will need to either create your own JAR file including the class file for the applet and all of the class files from the jChatClient/class directory, or you will need to use the class files to load the j-Chat Client as opposed to the JAR file.

   To use the class files, you should copy all of the class files from jChatClient/AppletSource and jChatClient/class to your web site. You must also modify the contents of the APPLET tag in jChatPage.html to use a CODEBASE attribute instead of the archive attribute. The CODEBASE attribute is used to point the web browser to the appropriate location on the server to find all of the class files needed to run the j-Chat Client.
   
   

2. Use as an Application

   There are two options for using the j-Chat Client as an application. The recommended method is to copy the files from the jChatClient/class directory onto the target machine and start the client with the following command:

   java jChat chathost1.yourdomain.com 5050

   On systems that only have a JRE, the command would be:

   jre jChat chathost1.yourdomain.com 5050

   This command starts the j-Chat Client and connects it to chathost1.yourdomain.com on port 5050. The j-Chat Client will not start without the host name and port parameters.

   The second method is to copy the jChatClient.jar file to the target system and use it to start the j-Chat Client. In this case, though, you must add the jChatClient.jar file to the classpath of your system. On OS/2, the following command should work if you are already in the directory that contains jChatClient.jar:

   java -classpath jChatClient.jar;%classpath% jChat chathost1.yourdomain.com 5050

   You could also modify your config.sys and permanently add the jChatClient.jar file to your classpath.

   Using the j-Chat Client as an application means you can run the j-Chat Server on any machine you want, and you can move to other servers without shutting down and restarting the client.

The j-Chat Client is fairly straightforward and easy to use. When you first start the client, it will load a list of rooms available on the site you connect to in the main window. After the list of rooms loads, your only option will be to logon.

Logon requires a nickname, real name, and password. The nickname is used to identify you to others inside the chat room while the real name is used in the list of people in the chat room. The password is only used if you attempt to go into a password protected chat room.

Once you press OK, the system will attempt to log you on. If the nickname you have chosen is already in use on the chat server, you will need to logon again with another nickname. A status box in the lower left of the main window will notify you if logon fails.

Once you are logged on, the list of rooms will be enabled as will the Enter Room button. To go into a room, click on the room in the list to highlight it, then click Enter Room.

Inside a room, you should see two buttons and 3 small boxes. At the upper left is the message area that displays messages anyone sends in the room. To the right is a list of people that are already in the room. This changes dynamically as people enter and leave the room. To the lower left is the area where you can type a message. To send a message, type your message in the space provided and click the Send button. The nickname of the person sending the message will be displayed next to each line of the message typed when it is displayed in the chat room.

Once you are ready to leave a room, click the Leave button.