Installing the Terminal Components

Lee Painter 3 February, 2022

Introduction

Terminal Components 3 is a redesign of some parts of our Terminal Emulation suite.

One of the enhancements is the addition of Client Side Rendering to the web-based version of Terminal Components, where the interpretation and rendering of the terminal data are performed in the clients' browser, reducing the load on the server. It also introduces the use of Web Sockets as a transport mechanism, providing a much more responsive experience.

We have also added a JavaFX renderer, that provides a similar experience to the Swing renderer but using the latest UI toolkit provided with Java 8 and above.

This version of terminal components makes use of newer Java features, so you will need at least a Java 7 compatible runtime to use this library.

Installing From Source

You will require:

A Java 8 development kit (JDK)
Maven 3.0.0 or higher installed and configured to work from the command line
An SSH server (or Telnet) server to connect to.
A Servlet specification 3 compliant containers such as Tomcat 8+ or Jetty 9+ (if you want to run the web examples or develop your own web-based terminal based on this library)

The following instructions assume you are using Maven in a command shell. If you are using an IDE or some other method of managing Java projects, you will have to adjust the instructions accordingly.

Unzip the terminal-components-x.x.x.zip file somewhere in your workspace.
Open a shell and change directory to the unzipped folder.
```
cd terminal-components-3.0.0
```
Run the command to compile the source and install the resultant Java libraries (.jar files) into your Maven repository.
```
mvn install
```

Maven should now compile Terminal Components and install it to your local repository. Look out for and correct any errors that might occur.

Included In This Distribution

Terminal components is distributed as a set of modules, that may mixed-and-matched according to your needs:

Core Modules (Required)

terminal-group - The parent Maven project
terminal - The core API and utilities.

Optional Modules

You will need at least one renderer module for Terminal Components to be useful:

terminal-awt - AWT renderer
terminal-swing - Swing renderer
terminal-swt - SWT renderer
terminal-javafx - JavaFX renderer
terminal-web - Javascript renderer (contains default servlets and websocket handlers)

You might want one or more of the optional transport modules too (by default terminal components has a Telnet transport and a simple Socket transport).

terminal-ssh - Uses SSHAPI to provide SSH connections via a 3rd party library
terminal-ssh-maverick- Leverages the JADAPTIVE Maverick Legacy API to provide a fully supported SSH transport
terminal-native - Use the terminal with your native shell.

Example modules

terminal-examples - Native toolkit examples and example utilities.
terminal-webapp - Web-based example suite

Running The Examples

Terminal Components come with examples for all types of renderer.

Running native toolkit examples

To run the native toolkit examples (AWT, Swing, SWT and JavaFX) :-

cd terminal-examples
mvn exec:java

The above will run a simple menu application that asks which toolkit you wish to see the example for. If you are running Maven 3.3.1 or above, you can use one of the following instead to run individual examples :-

mvn exec:java@awt        # runs the AWT example
mvn exec:java@swing      # runs the Swing example
mvn exec:java@swt        # runs the SWT example
mvn exec:java@javafx     # runs the JavaFX example

Running web-based examples

The web-based Terminal Components examples are all provided by a single webapp. To run these you either need your own container (such as Tomcat 8 or Jetty 9), or you can use the provided launcher that will down Jetty automatically and run your webapp. This is the preferred method.

Deploying to an existing servlet container

If you wish to run the examples in an existing servlet container you have, simply deploy the WAR file from terminal-webapp/target/terminal-webapp.war, which would have been built when you did the initial 'mvm install' earlier. Once deployed, point your browser to http://your.server.address/terminal-webapp/ and the example home page will be displayed.

Running a local servlet container

To get started, this easier methods starts a local Jetty 9 instance and automatically deploys the web application to it. Simply :-

cd terminal-webapp
mvn jetty:run

Maven will download an appropriate version of Jetty from Maven Central and start it up. Point your browser to http://localhost:8080/ to access the web examples home page.