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/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

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.

Example:

    <APPLET CODE="appWrapper.class" WIDTH=600 HEIGHT=480>
    <PARAM NAME=applet      VALUE="telnet">

    <!-- applet initialization: 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 -->
    <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">

    <!-- modules: #1 is a buttonbar -->
    <PARAM NAME=module#1    VALUE="ButtonBar">
    <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">
    <!-- modules: #2 is a scripting module -->
    <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 but at the moment it looks rather chaotic. This is due to a font problem we have not solved yet. Graphical characters have twice the width of other characters in the font set. If you have documentation on other character sets or how to solve the mentioned problem, please let us know!

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.

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">

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.

At the moment the package features two 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.

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.

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. 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.

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

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.

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.

Get the latest version here!
Last modified: Tue Mar 18 12:16:51 1997 by Matthias L. Jugel

The Java(tm) Telnet Applet: Documentation