                          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 <param name=host
value=localhost> 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 ---
