Background

Motivation

Many applications (especially servers) require an administration console, which usually leads developpers to add a web-based user interface or a dedicated client to it when one would not otherwise be necessary. The claim of the Telnet Service is to provide the needed functionality to add telnet capabilities to an application, with minimal development for integration and maximal control over that functionality.

Application developers and integrators will be able to avoid the costs assiciated with the implementation of the telnet service's internal functionality; while focusing on its aspect and business functionality.

Users will benefit from a universal and simple user interface with little integration requirements, with functionality and appearance customized to their needs.

Goals

The guiding principles governing the design of this service are:

It should provide the telnet connectivity functionality, without restricting it content

The main functionality of this service is to provide telnet connectivity. An additional requirement is that it does not limit the integrating application's freedom of controlling its content. For example, the service will ask the integrating environment for the prompt it must display at the beginning of each new line, but does not impose that one be there (the prompt can be an empty string).

It should be easy to use from the programmer's point of view

The service customization is provided through simple and straightforward APIs and the service core is implemented to give the flexibility of reflecting the application's business logic. For example, the integrating environment is provided a callback instance that will allow it to print to the console, the printed text may be editable or read-only, etc.

It should provide flexibility for security mechanism integration

The service authorization and authentication mechanism is Java Authentication and Authorization Service (JAAS) version 1.0 compliant which allows it to be integrated with a wide variety of JAAS compliant LoginModule s available; A few implementations are providers by vendors that are easy to find.

Core Architecture

The following diagram shows the core architecture components. Those components are described in the sub-sections that follow.

Component Relationship Diagram

Overall Component Relationship Diagram

Telnet Service

The service's main daemon component is the Telnet Service. It is configured by the integrating environment at setup/ initialization phase.

Integrating environments will either customize the different parts of this structure by adding extensions that are provided and configure them according to the application's needs; or, for those whose needs are not completely met by the available extensions, write a new extension and register it.
The extension mechanism is done through the registration of a TelnetServiceExtension implementation.

Session

When the Telnet Service accepts an incoming connection, it constructs a Session instance that will have the same lifespan as the incoming connection. The Session provides the integrating application access to API from the core bundle that may be required to it, namely an instance of a 'main' OutputFormat .

Session State

A SessionState instance is initialized at the creation of a Session and remains the same throughout its lifespan. The session state is passed to almost all calls between the service and integrating parties; it is used to hold both the service state as well as any additional state required by the integrating party.

Telnet Service Extension

The bare telnet service takes care of the underlying connectivity, TELNET negociations, and prompt display. It also provides feedback on what's going on to registered listeners.
To customize the service's behaviour, TelnetServiceExtensions provide implementations of control APIs that the service uses to achieve the required outcome.
Please refer to available tutorials on how to use existing extensions or write your own.

Session Listener

Extensions are notified of session connection and disconnection through SessionListener s that are optionally registered at initialize time.

Action Listener

Extensions are notified of user interaction with the TELNET console through the ActionListener that is optionally provided by each extension. We will go over the order in which different action listener receive notifications later.

Prompt Decorator

A PromptDecorator implementation may be provided by an extension to contribute to the construction of the prompt to be displayed next to the user. Those are also governed by an ordering schema to be covered later.

Console Delegate

Accessible through the session state's session instance, the ConsoleDelegate provides direct access to console information (such as current screen width) and methods to output to it.

Output Format

Although direct access to the console is provided through the Console Delegate and can be used to output to the console. A separation between the control and view parts of the application is recommended.

The display management layer may either be implemented by extending the provided utilities, or be completly implemented by the integration layer.

The Output Format mechanism is based on a subject to be represented, this subject would be the result of an action triggered operation, and then displayed by one of the output format instances competing for it. More on this below.

Session Life-cycle

The typical connection life cycle is as follows:

  1. The Telnet Service is configured as needed, and started
  2. On each new incoming connection to the port it is listening to, the Telnet Service creates a Session, providing it with a dedicated Session State, an Output Format delegate, a Prompt Decorator delegate, and an Action Listener delegate.
  3. The Telnet Session speaks TELNET, and interacts with the Action Listener delegate to notify it of user action. It interacts with the Prompt Decorator to display the next line prompt.
    The Action Listener is notified of new lines, arrow keys, ctrl-chars, and Tab characters. The Action Listener implementation reacts to those by performing application side processing and optionally displaying results through the provided means.
  4. Furthermore, after initialization, the application side may spontaneously send output to the console by using a stored reference to the Session State.
  5. One of the available operations on a Session State is a request for the disactivation of the session, which will cause it to stop after all notifications and cleanup is done.

Note that the core classes of this service library do not separate between login, password, and different state-based prompts; it is up to the features provided by the Telnet Service Extension to know what to display based on its Telnet Session State properties. It will also need to instruct the Telnet Session to suppress echo when it is expecting the user to type a password if it needs the password to be hidden (this is done through the setSuppressOutput method of the Console Delegate).
The telnetservice-jaas extension provides an implementation that is JAAS compliant and that takes care of the login procedure by interacting with the platform LoginModule , displaying the provided authentication questions. More can be found in the extension documentation and integrator guides.

Telnet Service Extensions

The telnet service functionality is mainly governed by its extensions. Those can also each extend the functionality of another extension.
The possible extension points are:

  • Action Listener: which is registered in the session's action listener list along with its priority. The Session will notify the integrating application of user activity using this interface.
  • Prompt Decoration: that contributes to the construction of the line prompt on the user console.
  • Output Format Spi: which allows the extension to contribute to the pool of available output formats. The position of each output format in the priority list, and its answer to the formats subject question are taken into account when selecting the instance to format the subject.
Note that none of the extension points is mandatory.

Available Extensions

The following extensions are available as separate bundles:

  • telnetservice-jaas: provides integration to the containing platform's JAAS framework, more on this bundle here .
  • telnetservice-linehistory: provides a historical of entered commands accessible through up/down arrows, more on this bundle here .
  • telnetservice-syntaxtree: provides an API to describe a command syntax that hooks to operation execution stubs, more on this bundle here .
  • telnetservice-syntaxtree-autocomplete: extends the syntaxtree functionality by reacting to Tab characters and providing (when available) syntax autocompletion. More on this bundle here .

Custom Extensions

Please go through the 'Integration Step-by-Step' guide to learn more on how to write a custom core extension. Writing extensions that build on an existing extension is covered in the other guides.

Action Listener and Prompt Decorator Priority

Each registered extension may provide an Action Listener to capture activity and react to it. Furthermore, each action listener has the option to prevent the listeners with lower priority from receiving an event that it has consumed, or allow them to receive it. For example, the authentication extension would be registered with highest priority and would block other listeners from receiving any events until the user is properly authenticated; another example would be a macro recording extension that would have a higher priority than a command execution extension to capture start/end record commands which would only be understood by that extension.

Action Listeners are therefore each assigned an event distribution priority which is set at configuration time. The listeners are ordered by priority. When a listener receives an event, it will respond true if it wants the later listeners to receive it, or false otherwise.

A similar situation applies to Prompt Decorators. When a new prompt needs to be displayed, the registered prompt decorators are requested to contribute, in order, to the construction of the prompt -- by either appending and/or prepending text to it.

The order of construction blocks is obviously important. Each decorator also has the possibility to block lesser priority decorators -- we wouldn't want "username: " to be appended with "> " :-)

Output Formats

The Output Format mechanism aims to separate the business logic processing (mainly housed in action listeners) and the display of the results of this processing.
It is based on a subject that is to be represented. The registered Output Formats would show interest in displaying the subject, the assigned priority determines the instance that takes it.

OutputFormatVT100Impl

An Output Format implementation is provided with VT100 coloring utilities. More on this implementation can be found in the javadocs. (developer guide writing in progress.)

OutputFormatVelocityImpl

A useful extension of OutputFormatVT100Impl provides a template based representation of a subject based on its class or interface. It allows an easy extension of the output formatting by inclusion of templates as described in its javadocs. (developer guide writing in progress.)

Other Impl

The integrating application may also provide its own custom implementations of the OutputFormat interface.