Olivetti JavaTalk ================= 1996 07 16 JavaTalkClient v. 1.25 JavaTalkServer v. 1.17 (c) 1996 Olivetti Research Limited INDEX: Introduction Licence and copyright What do you need? Connecting as a user Running a JavaTalk server Acknowledgements Packing list Contact information Introduction ------------ JavaTalk is a simple but effective multiuser chat program. Someone somewhere runs the server software and installs a suitable web page, then everyone else can join the chat by simply going to that page with their browser. You go to that page and whatever you type appears on the screen of everybody else who is watching the page at the same time. As simple as that! No messing around, no software installation, no client software to run, no command set to learn. If you want to give it a test drive, come to http://badges.cam-orl.co.uk/~fms/javatalk Writing a chat system in Java has been a popular idea with many developers and if you search the web you'll certainly find many more implementations. I know of at least four more. So what has JavaTalk got for you that makes it better than the others? Well -- that's up to you to decide, but here are three basic reasons to consider. * SIMPLE. No complicated command set to remember. No operators, chat rooms, privileges, private whispers or any of that stuff. Just go to the JavaTalk page and anything you type is seen by everyone else. Zero training needed. * SMALL. The classes for the client software total less than 15K. That means quick loading time, even on slow links. * FREE. Because I've got a smart boss, both the executable and the source are available to you for free, no licence form to fill in, no questions asked. You can use it as you wish on your own web pages, or as an internal communication facility in your intranet. Licence and copyright --------------------- Copyright (c) 1996 Olivetti Research Limited Permission is hereby granted, without written agreement and without licence or royalty fees, to use, copy, modify, and distribute this software and its documentation for any purpose, provided that the above copyright notice and the following three paragraphs appear in all copies of this software, its documentation and any derivative work. In no event shall Olivetti Research Limited be liable to any party for direct, indirect, special, incidental, or consequential damages arising out of the use of this software and its documentation, even if Olivetti Research Limited has been advised of the possibility of such damage. Olivetti Research Limited specifically disclaims any warranties, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. The software provided hereunder is on an "as is" basis, and Olivetti Research Limited has no obligation to provide maintenance, support, updates, enhancements, or modifications. Derived or altered versions must be plainly marked as such, and must not be misrepresented as being the original software. What do you need? ----------------- * To participate as a client: You need a Java-enabled browser. Then simply connect to a page that runs a JavaTalk server (like for example the JavaTalk home page mentioned above) and tell your friends to join you there at the arranged time. You don't need to download anything, neither the executable nor the source release of JavaTalk. Everything you need will be picked up automatically by your browser as and when you visit the web page. * To run your own JavaTalk server: You need the ability to run a Java interpreter on the same machine as your web server. Grab the executable release, unpack it in its own directory, edit the example web page if you want to, and launch the server. * To modify the program: You need a Java compiler and developer's kit. Currently available for free from Sun, as well as for money from commercial vendors. Grab the source release. All of the above, plus info on newer versions if any, can be found on the JavaTalk home page (see "contact info" at the end of this file). Connecting as a user -------------------- Most of what appears in this section should be easy to figure out without instructions, but I'll spell it out in detail just so that you have a reference handy. Go to the page of the JavaTalk server you want to connect to. The fact of going to the page makes your browser download the applet and connects you to the JavaTalk server. When the applet has loaded you'll see two windows: a big one above and a one-line one below. You type, one line at a time, in the one-line window, pressing Enter after each line. What you type is sent to the server which then echoes it back to the upper window of everyone who is connected. The echoed lines are prefixed with the name of the sender. You can set your name to whatever you want by using the command "MYNAME xxx" (commands are all uppercase so that they are unlikely to clash with anything you normally type). Replace xxx with your chosen name, of course. Don't choose a terribly long name or there won't be much room left for your messages and people will have to scroll horizontally, which is a nuisance. Before you use MYNAME for the first time, your default name will be the internet address and port number of the socket you are using to connect to the server. To see who else is connected to the server at the time, type "WHO" (the second and last command understood by the current version of the server). If you don't type anything for a while, the server will suspect that you went away and will warn you. If you want to stay in, type something (and press Enter to send it). Otherwise, after another little while, you'll be disconnected. (Technical note: this reaping process is performed to get rid of those zombie users who used to appear as connected even though they had long since gone away. It turns out that a known bug (SUN bug 1234731, see http://java.sun.com/java.sun.com/products/JDK/1.0.2/KnownBugs.html) in the Windows implementation of the Java socket libraries prevented the JavaTalk server from detecting that they had gone away. So I pre-empted the problem by kicking out inactive users, regardless of whether their socket looked OK or not. If you run your own JavaTalk server, you can customise the timeouts.) When you are disconnected from the server, either because the server kicked you out or because the server couldn't be contacted on the given address and port (maybe because it wasn't running?) then the applet will not display any windows or buttons: it will just say "Not connected to server. Threads stopped." To reconnect (assuming the server is there to connect to), just reload the page. Every time you leave the page, you disconnect from the server (though of course you won't see the above message because the applet won't be visible any more). The other participants to the conference will get the message "User xxx left the conference". Conversely, every time you enter the page, you join the conference and again the others are notified. There are two checkboxes at the bottom of the applet that activate a debugging feature to measure the time it takes for your messages to travel from you to the server and back (the roundtrip delay). This is done by sending a special extra timestamp line every time you send a regular line. The server doesn't do anything special-- it just echoes the timestamp like it does with every other line. Your client, though, recognises it when it gets it and with some advanced mathematics (namely a subtraction) it computes how long the message took to get back. This time is then printed in the prompt that precedes the actual message. All of this stuff is activated and deactivated with the first checkbutton, the one that says "Show round trip time". The other one ("Show timestamp messages") is rather useless unless you are me and are trying to debug the timestamping protocol: it deactivates or reactivates the filtering of the special timestamps. It probably shouldn't even be there in a production release, and may disappear without notice in the future. Running a JavaTalk server ------------------------- Note: throughout this section it is assumed that you have already installed a Java environment on your system, and in particular that the Java interpreter and the applet viewer are available on the path. If this is not the case, do that first. (See http://www.javasoft.com for details and software.) Because of the restrictions imposed by Java's security model, an applet can only make a TCP connection to the machine it was loaded from. This means that the JavaTalk server must necessarily run from the same machine as the web server that is serving the html page in which the JavaTalk client applet is embedded. For a quick start, make a JavaTalk subdirectory in your public html directory and unpack the executable distribution in it. For a test run, start the server with the default parameters (on my systems I type "java JavaTalkServer") and, from another console on the same machine, run the client inside the appletviewer (on my systems I type "appletviewer index.html"). You should be able to type in the bottom window of the client and see your messages echoed (by the server) in the top window. Of course you can start more copies of appletviewer and they will chat to each other. To try out JavaTalk with your web browser instead of the appletviewer, you'll have to edit the index.html page. Change the entry, replacing localhost with the fully qualified Internet name of the machine where the JavaTalk server is running (for example badges.cam-orl.co.uk). Then, ensuring that this page is served by your web server (check the file permissions), you can point your browser at it and you should see the applet embedded in the page. Once you've checked that the supplied page works, you can start modifying its text and layout to suit your purposes. It is appreciated, but not required, that you keep the JavaTalk logo and the link to the JavaTalk home page if you use the unmodified server and client from the executable release. It is required that you do NOT use the JavaTalk logo if you run your own modified versions of the programs. You should instead say something like "derived from Olivetti JavaTalk (hyperlink to the genuine thing) with unapproved modifications". As the server runs, it keeps a transcription of the talk in a log file. Every time the server starts, it opens a new log file, named after the current date and time and so very likely to be unique. Killing and relaunching the server is the approved way to start a new log file. Note: the log will not contain all the messages that the server normally prints on the console. If you want the server to shut up (but still write to the log as usual), redirect its standard output and standard error. You can supply your own log file name if you want with a command line parameter. If you give the name of an existing file, the file will be overwritten, not appended to. You can give /dev/null, or its equivalent on non-unix systems, if you don't want a log file to be produced. While we are on that subject, here are the parameters accepted by the server, with their defaults: they are all optional. Note that the server prints out a help message if you invoke it with "help", "-help", "-h" and so on (actually, anything that's not a valid integer) as the first parameter. USAGE (all arguments optional and positional): java JavaTalkServer warning afterWarning port logFileName warning (default 300) After this many seconds of inactivity, the user gets a warning. afterWarning (default 60) After this many extra seconds of inactivity after the first warning, the user is kicked out. port (default 6764) Port number on which to listen for connections. If you run more than one server on the same machine, each one must listen on a different port. logFileName (default javatalk.YYMMDD-HHMMSS.log, with suitable replacements) A time-stamped transcript of everything the participants say during the lifetime of the server goes here. Because the arguments are positional, you can only omit arguments from the tail end. For example, if you only want to specify a new port number of 7000, you still have to give some value for warning and afterWarning, as in java JavaTalkServer 300 60 7000 It is accepted JavaTalk etiquette to tell your users, on the page with the client, that all the chats are logged. For pre-organised meetings, it is also accepted JavaTalk etiquette to send a copy of the log to all the participants. If you are editing the web page that contains the applet, you'll want to know the parameters that the applet takes: they are listed below, and they are shown in the example page. port (default 6764) Port number to connect to. Please ensure that it matches the port number that the server is listening on. You'll have to change this value if you use many servers to provide several chat rooms. host (default badges.cam-orl.co.uk) Fully qualified name of the host that the server is running on. You'll definitely want to change this one. showRoundTrip (default false) Initial state of the "Show round trip" checkbox. showTimestamps (default false) Initial state of the "Show timestamps" checkbox. maxChars (default 10000) Maximum number of characters that will be accepted in the scrolling window before we start chopping old stuff off the top. Don't set it too high or the widget will fill and lock up. (NB: 32K minus epsilon is still too high. Experimentally, it locks up at about 27000, but I like to err on the side of safety.) JavaTalk doesn't have multiple "rooms" or "subconferences", but you can implement this by dedicating a different web page to each. Of course, behind each page must be a different instance of the JavaTalk server, listening on its own dedicated port. This means that the various pages will have to supply different values for the "port" parameter. The disadvantage of this scheme is that people can't open new conferences dynamically. But the advantage (other than simplicity) is that the conferences are completely decoupled and you can even safely shut down the server for one of the conferences without affecting any of the others that are running. Acknowledgements ---------------- The working core of JavaTalk was written in two days of furious hacking (9 & 10 May 1996). Alessandro Morales gets credit as the first beta-tester: I dragged him in with an international phone call on the evening of the 10th, as soon as I got the prototype to work. Quentin Stafford-Fraser was always available to discuss Java issues and contributed with helpful advice on many occasions. Adriano Vernassa helped with stress-testing of the applet over poor routing conditions (the roundtrip-measuring code went in because of the problems he was experiencing). Hiang-Swee Chiang was kind enough to read through my code before the public release and he came back with some helpful comments. Harold Syfrig helped me track down a scrolling-related bug in the client. My thanks to all these people, though of course any bugs and shortcomings remain my responsibility. Packing list ------------ Note: you'll need an unzip program capable of dealing with long filenames. There are free versions of such a program both for Unix and for Win32. Alternatively you'll need a tar and gunzip pair, again capable of long file names. Again, there are free versions of such programs for both Unix and Win32. I keep wondering why I can't get away with supplying only one flavour, but then I'm a nice guy and I want to make your life easier, so please pick the compression flavour that you're already familiar with. After going to the trouble of providing two sets of distributions, I decided to make the .tar.gz one more unixy (LF) and the .zip one more windowsy (CRLF). This only affects the line terminators in the text files. Everything else is exactly the same. Executable release: JavaTalk-executable.zip or JavaTalk-executable.tar.gz ./readme.txt this file ./client/index.html sample web page containing the applet ./client/javatalk.gif JavaTalk logo appearing on page ./client/*.class classes implementing the client applet ./server/*.class classes implementing the server Source release: JavaTalk-source.zip or JavaTalk-source.tar.gz ./readme.txt this file ./JavaTalkClient.Java source for the client ./JavaTalkServer.Java source for the server In case you're wondering, I developed the software with Symantec Cafe' under Windows 95. I normally run the server on Unix (Solaris). I tend to run the client on Windows via Netscape but I occasionally run it from Unix too (Solaris and OSF, again with Netscape). Contact information ------------------- I welcome your feedback. If you want to be kind, start your subject line with "javatalk" so that the message will go in the right mail folder by itself. Frank Stajano (filologo disneyano) Olivetti Research Limited 24A Trumpington Street Cambridge CB2 1QA UK http://www.cam-orl.co.uk/~fms mailto:fstajano@cam-orl.co.uk The JavaTalk page: http://badges.cam-orl.co.uk/~fms/javatalk --- END of readme.txt ---