The Java^(tm) Telnet Applet: Documentation

The package contains several parts of which the most important one is the Telnet Applet/Application. Select from the list below what you are interested in. If you only want to use the applet choose Telnet from Setup and if you want to use the packages in your own programming, select the appropriate from Source Code.

Setup

[ Telnet | Terminal Emulation | Modules ]
[ Applet Wrapper | Proxy Server ]

Source Code

Get the latest version here!

Setup Documentation

How to setup the Telnet Applet

Make sure, you got the latest version of the Java^(tm) Telnet Applet. Refer to the download page on how to get it and how to extract the files from the archive. After successfully extracting the complete package you should have a directory Telnet/ containing *.html, *.java and *.class files as well as the directores Documentation/, display/, modules/, socket/ and tools.

To install the applet on your web page you need as least the following files and directories. Make sure that all files and directories are readable by other users!

  index.test.html
  telnet.class
  appWrapper.class
  display/
  display/SoftFont.class
  display/CharDisplay.class
  display/Terminal.class
  display/TerminalHost.class
  display/vt320.class
  socket/
  socket/TelnetIO.class
  socket/StatusPeer.class
  modules/
  modules/Module.class
  modules/Script.class
  modules/ButtonBar.class
  modules/MudConnector.class

Now edit index.test.html to adapt it to your needs or look at the example below! The file is documented and if you have questions about the Modules refer to the Module Documentation or look at the Source Code. You will find, that not telnet.class is loaded as applet, but appWrapper.class instead. This is necessary to enable the detach feature!

Important Note:: We would appreciate to see credits on a page using the applet which includes a link to the applets home page and names of the authors as mentioned on top of this page. You may simply use our test page and edit it to your needs.
In response we will include a link to your page on our user page, if you like.

The telnet applet can be customized using the following parameters:

    <PARAM NAME=address    VALUE="tanis.first.gmd.de">
    <PARAM NAME=port       VALUE="23">
    <PARAM NAME=emulation  VALUE="vt320">

    <PARAM NAME=proxy      VALUE="www.first.gmd.de">
    <PARAM NAME=proxyport  VALUE="31415">

The proxy and proxyport parameters may be left out. They are needed if your target host is NOT the same as your web server and you are using the relay daemon.

Example:

(all possible parameters)

    <APPLET CODE="appWrapper.class" WIDTH=600 HEIGHT=480>

    <!-- appWrapper parameters -->
    <PARAM NAME="applet"      VALUE="telnet">

    <!-- optional (WIDTH and HEIGHT should be changed!) -->
    <PARAM NAME="startButton" VALUE="Connect to www.first.gmd.de!">
    <PARAM NAME="stopButton" VALUE="Shutdown telnet!">
    <PARAM NAME="frameTitle" VALUE="The Java Telnet Applet: WWW">

    <!-- applet parameters: address and port and emulation -->
    <PARAM NAME="address"     VALUE="www.first.gmd.de">
    <PARAM NAME="port"        VALUE="23">
    <PARAM NAME="emulation"   VALUE="vt320">

    <!-- terminal emulation parameters (optional)-->
    <PARAM NAME="VTscrollbar" VALUE="true">
    <PARAM NAME="VTresize"    VALUE="font">
    <PARAM NAME="VTfont"      VALUE="Courier">
    <PARAM NAME="VTfontsize"  VALUE="13">
    <PARAM NAME="VTid"        VALUE="vt220">
    <PARAM NAME="VTcharset"   VALUE="ibm">

    <!-- module parameters: #1 is a buttonbar (optional) -->
    <PARAM NAME="module#1"    VALUE="ButtonBar@North">
    <PARAM NAME="1#Button"    VALUE="connect|\$connect()">
    <PARAM NAME="2#Button"    VALUE="disconnect|\$disconnect()">
    <PARAM NAME="3#Button"    VALUE="Detach/Delete Window|\$detach()">
    <PARAM NAME="4#Button"    VALUE="Send:|\@send@\r\n">
    <PARAM NAME="5#Input"     VALUE="send#10|who">

    <!-- module parameter: #2 is a scripting module (optional) -->
    <PARAM NAME="module#2"    VALUE="Script">
    <PARAM NAME="script"      VALUE="login:|leo">

    <!-- make sure, non-java-capable browser get a message: -->
    <B>
    Your Browser seems to have no Java
    support. Please get a new browser or enable Java to see this applet!
    </B>
    </APPLET>

Setting up the Terminal Emulation

The Terminal Emulation is a very important part of the Telnet Applet, because it enables you to use programs that make use of certain features of hardware terminals like VT100 or ANSI. Supplied with the package is an almost VT320 compliant terminal emulation, that should include the two mentioned earlier. This means that the applet can do colors, even if the original VT320 terminal cannot!

The applet supports the special graphical character set of VT terminals. The new implementation supports all graphical characters with a small drawback. The more graphical characters on the screen the slower is the display. We will remove the current implementation when full UNICODE support is available from all browsers (full JDK 1.2 compatibility).

To configure the terminal emulation look at the list of parameters below:
Note: Default values are typeset in italics and other possible values in bold.

<PARAM NAME="VTcolumns" VALUE="80">: Sets the columns of the terminal initially. If the parameter VTresize is set to screen this may change, else it is fixed.
<PARAM NAME="VTrows" VALUE="24">: Sets the rows of the terminal initially. If the parameter value of VTresize screen this may change!
<PARAM NAME="VTfont" VALUE="Courier">: Sets the font to be used for the terminal. It is recommended to use Courier or at least a fixed width font.
<PARAM NAME="VTfontsize" VALUE="14">: Sets the font size for the terminal. If the parameter value of VTresize is set to font this may change!
<PARAM NAME="VTresize" VALUE="font">: This parameter determines what the terminal should do if the window is resized. The default setting font will result in resizing the font until is matches the window best. Other possible values are none or screen. none will let nothing happen and screen will let the display try to change the amount of rows and columns to match the window best.
<PARAM NAME="VTscrollbar" VALUE="false">: Setting this parameter to true will add a scrollbar west to the terminal. Other possible values include left to put the scrollbar on the left side of the terminal and right to put it explicitely to the right side.
<PARAM NAME="VTid" VALUE="vt320">: This parameter will override the terminal id vt320. It may be used to determine special terminal abilities of VT Terminals.
<PARAM NAME="VTbuffer" VALUE="xx">: Initially this parameter is the same as the VTrows parameter. It cannot be less than the amount of rows on the display. It determines the available scrollback buffer.
<PARAM NAME="VTcharset" VALUE="none">: Setting this parameter to ibm will enable mapping of ibm characters (as used in PC BBS systems) to UNICODE characters. Note that those special characters probably won't show on UNIX systems due to lack in X11 UNICODE support.

Please look at the example above.

Setting up Modules

Another feature of the Java^(tm) Telnet Applet is the ability to dynamically load modules. A module is a java class that is loaded after the applet has been initialized and may be used to enhance the user interface or to background work in some way.

To load a module a special parameter has to be added to the applet PARAM tags:

<PARAM NAME=module#number VALUE="modulename@direction">

number is a sequence number, used by the applet to determine the modules. Numbers must be adjacent or modules may not be loaded.
modulename is the name of the modules to be loaded. Modules already in the package are described below.
@direction is the position of the applet in relation to the window. Possible values are: North, South, East, West. The module will then be placed accordingly. It is not possible to place two modules at the same position! The positional parameter may be left out and the module will then be placed North.

At the moment the package features three modules:

ButtonBar: The ButtonBar is a modules to enhance the user interface. Using PARAM tags buttons and input fields can be added to send text to the remote host or to detach the applet.
Script: Sometimes it is useful to have simple script abilities. This module executes a script based on text received from the remote host.
MudConnector: This module is a special program for the Mud Connector by Andrew Cowan. It loads a list of muds and displays information like host and port.

The ButtonBar

The ButtonBar may be used to add buttons to the applet that execute functions or simply send a specified text to the remote host. In addition it is possible to specify input fields as external input means.

To load the module include the following tag into the .html file (example):

<PARAM NAME=module#1 VALUE="ButtonBar">

Below is a description of possible PARAM tags and a description of supported functions:

Buttons:

<PARAM NAME=number#Button VALUE="buttontext|buttonaction">

number is the sequence number and determines the place of the button on the row.

buttontext is a string displayed on the button.

buttonaction may be one of the following functions or strings
(Note: the backslash character in front of the dollar sign is mandatory!)

```
simple text
```
to be sent to the remote host. Newline and/or carriage return characters may be added in C syntax \n and \r. To support unimplemented function keys the \e escape character may be useful. The \b backspace character is also supported. The text may contain field reference(s).
```
\$connect(host[,port])
```
tries to initiate a connection to the host at the port, if given. The standard port is 23. host and port may be hostname and number or field reference(s). If a connection already exists nothing will happen.
(Note: It is not allowed to have spaces anywhere inside the parenthesis!)
```
\$disconnect()
```
terminates the current connection, but if there was no connection nothing will happen.
```
\$detach()
```
detaches the applet from the web browser window and creates a new frame externally. This may be used to allow users to use the applet while browsing the web with the same browser window.
(Note: You need to load the applet via the Applet Wrapper or it will not work properly!)

Examples:
(Note: It makes sense if you look at the examples for input fields below.)

       <PARAM NAME=1#Button VALUE="HELP!|help\r\n">
       <PARAM NAME=2#Button VALUE="HELP:|help \@help@\r\n">
       <PARAM NAME=4#Button VALUE="simple|\$connect(localhost)">
       <PARAM NAME=5#Button VALUE="complete|\$connect(www,4711)">
       <PARAM NAME=6#Button VALUE="connect|\$connect(\@address@)">
       <PARAM NAME=8#Button VALUE="connect to port|\$connect(\@address@,\@port@)">
       <PARAM NAME=10#Button VALUE="window|\$detach()">

Input fields

<PARAM NAME=number#Input VALUE="fieldname[#length]|initial text">

number is the sequence number and determines the place of the field on the row.

fieldname is a symbolic name to reference the input field. A reference may be used in button actions and is constructed as follows:

\@fieldname@

The \@fieldname@ macro will be replaced by the string entered in the text field.

length is the length of the input field in numbers of characters.

initial text is the text to be placed into the input field on startup

Examples:
(Note: It makes sense if you look at the examples for buttons before.)

       <PARAM NAME=3#Input VALUE="help#10|">
       <PARAM NAME=7#Input VALUE="address|www.first.gmd.de">
       <PARAM NAME=9#Input VALUE="port#5|4711">

The Script Module

The script module gives a very simple implementation of an input triggered script executor. This means it sends text to the remote host when the received text matches a pattern that can be programmed. It executes each pair of pattern and text only once and stops working after all patterns have been matched. It will start working again upon a new connection.

To load the module include the following tag into the .html file (example):

<PARAM NAME=module#1 VALUE="Script">

Below is a description of possible PARAM tags and a description of script:

Scripts:

<PARAM NAME=script VALUE="pattern|text|...">

A script contains of pairs of pattern and text strings. If the pattern is matched against the output from the remote host, the corresponding text will be sent. Each pattern will match only once per connected session. Thus it is possible to program an autologin as follows:

"login:|leo|Password:|mypassword|leo@www|ls"

Newlines will be added automatically to the string sent! At the moment the order of the pattern and text pairs is not relevant.

MudConnector

This module is a special edition for the Mud Connector. It features a list of MUDs and a few buttons to connect, disconnect and get infos about the MUDs. A very nice example for a specialized module. To load the module include the following tag into the .html file (example):

<PARAM NAME=module#1 VALUE="MudConnector">

The MudConnector expects the following PARAM tags:

Mudlist URL:

<PARAM NAME=mudlist VALUE="URL">

The URL should be a file containing line by line the MUD name, the Mud address and the MUD port, separated by tabulators. The first line in the file should be the number of MUDs in the file.

Example:

<PARAM NAME=mudlist VALUE="http://www.mud.de/~leo/mudlist.data">

The Applet Wrapper Setup

The applet wrapper is an applet that does nothing else than loading the, for example, telnet applet. To understand why this is necessary you have to look at the experiences we have made.

Simply using the telnet applet in the following manner:

<APPLET CODE="telnet.class" WIDTH=600 HEIGHT=480>

and using the detach function stops the applet after you have detached the applet and want to browse the web again. It seems that the Web browser stops all threads connected to the applet if you leave the page where the applet is located and thus it doesn't even update its display anymore.

We have found out that this is not true for applets loaded within the applet on the page (e.g. the appWrapper). Look at the following description on how to setup the appWrapper. It will probably work with any given applet out on the web!

    <APPLET CODE="appWrapper.class" WIDTH=600 HEIGHT=480>
    <PARAM NAME=applet VALUE="telnet>
    <!-- all other telnet applet parameters go here -->
    </APPLET>

The appWrapper knows only about the PARAM tag applet, which is the applet to be loaded. In this case it must be in the same directory as the appWrapper.class. Refer to the telnet example above for the telnet parameters.

Setting up the proxy server

There are two proxy servers provided with the telnet applet. The first one is written in java and does support connections to one target host only and the second one is written in C and supports different targets (called relay daemon).

[Java Proxy | Simple Relay Daemon | Relay Daemon]

The Java Proxy Server

The proxy server is a small java program to overcome the security restrictions of java capable web browsers.

The proxy is used to redirect a connection to a given host. Usually an applet can only connect to the web server it has been loaded from. Installing the proxy on your web server allows the applet to connect to a host you would like to connect to.

How to run the proxy application?

To run the proxy you require the following:

A java interpreter (usually included in the JDK)
A compiled version of the proxy (proxy.class)

On the WWW-Server command line run the proxy server as follows:

java proxy 9999 remotehostname 23

This lets the proxy listen on port 9999 and it redirects all connections to the host "remotehostname" at port 23. You can leave the port parameter out if it is 23 (telnet port).

The proxy should start with something like the output below:

proxy: destination host is remotehostname at port 23
proxy: listening on port 9999

Upon successful connection the output should produce something like this:

proxy: accepted connection from augra.first.gmd.de
proxy: connecting www.first.gmd.de <-> remotehostname

How to shut down the proxy?

To shut down the proxy press ^C (Ctrl+C or Strg+C on a german keyboard) if you have startet it normally. More advanced users will run the proxy like

java proxy 9999 remotehost 23 >& errorlog &

to put it into the background. The "errorlog" file should then contain any messages. You can kill that process by looking for the process id (ps | grep proxy) and issuing the kill <processid> command (this applies to UNIX only).

I get an error message like "class proxy not found"!

You may have to set the CLASSPATH environment variable to point to the current directory or to the directory where proxy.class is located.

The Simple Relay Daemon

The simple relay daemon works just like the proxy above, but is a C version. It allows connections only to a specified host and port which is preferrable for security reasons. You can run the program (after compiling it) with the following command line:

				relayd serverport targethost targetport
or just
				relayd serverport targethost

It will then listen on the serverport of the machine you started it and connect to the targethost. The standard targetport is 23.

The Relay Daemon

The relay daemon is a program written by Marcus Meißner to support different target hosts. It relays the connections from the applet to a host that must be given to the relay daemon after connecting.

The daemon expects a string

relay address port

It must be run on the web server of the applet. The relay daemon is not included in compiled form, because we would have to support a number of platforms. However, you can write to us if you need a special compiled version for your hardware platform.

You should include the following tags to tell telnet that it is supposed to use the prox server

    <PARAM NAME=proxy      VALUE="www.first.gmd.de">
    <PARAM NAME=proxyport  VALUE="31415">

Source Code Documentation

The Source Code of The Java^(tm) Telnet Applet is available under the terms of the GNU General Public License as documented in the file COPYING. In case you would like to use the packages as libraries please apply the GNU Library General Public License as documented in the file COPYING.LIB.

Select from the structure below, what you would like to see. Each file contains a Version: field determining its current status and version. If you are not sure to have the most current version, please look here.

If you are unsure, whether you've got the newest version, compare your copy of the file REVISION and this REVISION, which is a direct link to the home page. The latest changes are documented in the file CHANGES.

appWrapper.java
telnet.java
IOtest.java
CharDisplayTest.html
Tools
- tools/proxy
- tools/redirector (proxy.java)
- tools/relayd.c (simple proxy)
- tools/mrelayd.c (enhanced proxy)

Get the latest version here!
Last modified: Mon Jun 30 11:22:06 1997 by Matthias L. Jugel

The Java(tm) Telnet Applet: Documentation