How To Install, Configure, and Manage the Industrial Telnet Server

Contents

  1. Overview of ITS
  2. Installing ITS
  3. ITS Configuration
  4. Device Configuration
  5. ITS Logging
  6. Packaging, Deploying, and Running an ADFT Application

Overview of ITS

The Industrial Telnet Server (ITS) allows for interaction with Application Development Framework (ADF) Faces applications via telnet emulators. Typically, ITS will be deployed within the supply chain of an enterprise, because a large number of devices running telnet emulators are used in supply chain execution applications today. However, ITS can be deployed in any environment that requires support for telnet emulators, including environments in which the telnet emulators run on desktop computers.

Unlike HTML browsers, telnet emulators have no mechanism for understanding what application pages and form components are. A telnet emulator is only capable of connecting to a server, sending user input to the server, and doing what the server instructs it to do (e.g., moving the cursor around the screen and displaying characters). In essence, a telnet emulator is a dumb terminal. It has a screen for display and can accept user input, but it cannot process the input on its own.

ITS acts as an intermediary between the telnet emulator and an ADF Faces web application, much as an HTML browser can be thought of as an intermediary between a user's display / keyboard and an ADF Faces web application. ITS is able to draw an application page returned from the web application onto a connected telnet emulator's screen. ITS is also able to process input from the user by updating the state of the page, updating the user's screen, and/or sending the user input to the web application, as necessary.

ITS is a standard J2EE 1.4 application, packaged in an EAR file. Once deployed in a J2EE 1.4 container and configured properly, ITS begins accepting connections from telnet emulators on a specified port (by default, 2323). Once a telnet emulator connects to ITS and some low-level telnet negotiation is performed, ITS makes an HTTP request to the URL specified by the initialURI property (see ITS Configuration for information on how to set this). ITS processes the response from that URL and draws the screen as necessary on the telnet device. As the user interacts with the page, ITS updates the state of the page and continues making requests to the web application.

In order to make a web application work with ITS, the web application must include the ADF Telnet (ADFT) libraries. The major component of ADFT is the ADFT RenderKit. The ADFT RenderKit is capable of rendering a significant number of ADF Faces components (as well as some industrial-specific extension components) to a format that ITS is capable of processing. The ADFT RenderKit is also responsible for processing requests made by ITS. Note that, a developer need not know the specifics of the markup generated by ADFT and the requests created by ITS; because of the nature of Java Server Faces (JSF) and ADF Faces, this is abstracted away from the developer. See Packaging, Deploying, and Running an ADFT Application for more information.

It is important to note that, although ITS opens a port and allows telnet emulators to connect to it, it does not in any way provide access to the underlying operating system.

Back to contents

Installing ITS

ITS is packaged in a standard J2EE 1.4 EAR file. Installing ITS is usually as simple as deploying it, as you would any other EAR file, and then performing any configuration necessary. In some containers, you may need to modify the configuration before deploying the ITS.ear file.

The ITS.ear, intended for use with OC4J, is located at <JDEV_HOME>/wireless/j2ee/applications. You can deploy this EAR file on OC4J using the Enterprise Manager deployment tool. This is accessible using the URL http://<oc4jhost>:<oc4jport>/em (for example, http://localhost:8888/em).

Oracle provides separate ITS.ear files for other containers as well. The only difference between these container-specific EAR files is that some EAR files include additional libraries (which the containers do not provide) and container-specific configuration files (which some containers require).

Back to contents

ITS Configuration

ITS splits configuration into two places: a Resource Adapter deployment descriptor ( ITSRA.rar/META-INF/ra.xml), and an application configuration descriptor ( META-INF/appConfig.xml).

How this configuration is modified is container-specific. In all containers, unpackaging the ITS.ear file, modifying the indicated XML files, and then repackaging the ITS.ear file before deploying ITS will work. n some containers, you may be able to modify the configuration after deployment by modifying the configuration files in a deployment directory.

OC4J provides another mechanism for modifying these configuration options, after deployment, using the Enterprise Manager. To find these configuration options, connect to the Enterprise Manager, navigate to the Applications tab, and then perform the following:

  • ra.xml
    1. Click the relevant link in the Name column for your ITS deployment.
    2. In the Modules table, click ITSRA.
    3. Navigate to the Administration tab.
    4. Click the icon in the Go to Task column for Configuration Properties.
  • appConfig.xml
    1. Click the icon in the Application Defined MBeans column in the ITS row.
    2. Expand ITSAppConfigMBean and then click the ITSAppConfigMBean link.
    3. Navigate to the Attributes tab in the resulting frame.

The following tables list each of the configuration properties available to a system administrator. Typically, one configuration parameter that must be changed is the InitialURI parameter in appConfig.xml, which should be modified to point to your web application.

ra.xml has the following properties:

Property Name Description Default Value
characterEncoding Indicates how the bytes coming from the telnet emulator should be decoded and how the bytes being sent to the telnet emulator should be encoded. This should match the telnet emulator's settings. This must conform to an encoding supported by java.nio.charset.Charset in your JVM. UTF-8
disableBusyTicker Indicates whether or not to disable the busy ticker. The busy ticker is a graphical indicator displayed to the user when the server is busy. If disableBusyTicker is true, this indicator will not be shown. false
OC4J Indicates whether ITS is running within an OC4J container. true in OC4J container, false otherwise
requestProcessingTimeout Indicates the length of time, in milliseconds, that the processing of a request to the web application can take before the processing is aborted. 15000
serverPort Indicates the port on which ITS listens for connections from telnet emulators. 2323
sessionTimeout Indicates the length of time, in milliseconds, that a user may remain inactive before that user's connection is terminated. 36000000

appConfig.xml has the following properties:

Property Name Description Default Value
acceptLanguage The acceptLanguage header is sent to the web application; some application servers will use this to determine the language in which a page should be translated; this value is not processed or checked for validity by ITS; see http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html, section 14.4, for details on how this string should be formatted. en-us, en-gb;q=0.8, en;q=0.7
applicationDebugMode When in the application debug mode, ITS will display additional information to the end user when a problem occurs in the web application. false
initialURI When a user connects to the ITS, ITS will make a request to this URL to load the first page. The default URL points to a page included in ITS, but only if ITS is deployed with the name its and is running in a container whose web server listens on port 8888. http://localhost:8888/its/welcome.tml
ITSLocale Indicates the default locale to use for displaying messages or text, or both, to a user in the absence of a locale provided by the application. en_US
multiColumnCharactersSupportMode This is a flag to determine whether ITS should attempt to support multi-column characters. Multi-column characters are those characters that take up more than one column on a display, such as many Chinese, Japanese, and Korean characters. Note that this feature is not supported currently. false
remoteDeviceRepositoryURI This is the URL of a remote device repository that will be used to obtain device information (in addition to device configuration contained within the appConfig.xml). If no URL is specified, then the local device repository will be used instead. The use of a remote device repository is encouraged, however, as it will ensure that the applications and the server refer to the same device characteristics (assuming that the application uses the same remote device repository). N/A

In addition, appConfig.xml provides device-specific configuration, allowing for the definition of several features based on the type of device that is connecting. For example, key mappings are defined within appConfig.xml to map physical keys to ITS function key. Such configuration may vary depending on the type of a device--an administrator may map a commonly needed ITS function key to F1 on one device but Ctrl+A on another device.

For more information about device configuration, see the comments in appConfig.xml. These provide detailed information about the configuration options for each device, as well as the mechanism used for determining which device configuration to use for a particular connecting client.

Back to contents

Device Configuration

In the context of Industrial Telnet Server (ITS), device configuration is split into two parts: the ADF Mobile Device Repository and appConfig.xml. The device repository contains static information about a device--parameters that will not change from installation to installation, such as screen height and width. appConfig.xml, in contrast, will contain device information that administrators may wish to change at their installation, such as key mappings.

The device repository will not be changed directly by the system administrator. It is located in the root of the deployed ITS directory (for OC4J, this is <JDEV_HOME>/j2ee/home/applications/its). Currently, two telnet devices are included in the repository: symbol-pdt6846 and symbol-vrc6946.

appConfig.xml, located in the meta-inf directory of ITS.ear, contains a devices element, which holds device descriptions. Each device description in appConfig.xml contains a few device characteristics that the system administrator may wish to change, such as a mapping between physical keys and function keys. Each of the device descriptions exist in a separate device element, which contains a refDevice and a name. The refDevice must match a device name in the device repository (e.g., symbol-pdt6846), while the name must be unique within appConfig.xml.

appConfig.xml provides two mechanisms for automatically mapping a connecting device to a particular device description:

  • The first and most common approach is the presence of the name attribute. If the connecting device is configured such that its terminal type exactly matches the name in a device element, that device description is used.
  • If no match is found, the deviceIPAddress element in appConfig.xml is examined to determine if the IP address of the connecting client can be mapped to a particular device.

If both of the above fail, and there is more than one device description, then the user will be prompted with a device selection screen, in which the name of each device description (whose hide attribute is not set to true) is displayed to the user. The user can then select which device description to use.

appConfig.xml provides extensive comments describing these configuration options in more detail.

Back to contents

ITS Logging

ITS uses the standard Java logging mechanism, with the log name oracle.wireless.its. You should configure your container so that it will log at the desired level.

To configure the log level in OC4J:

  1. Connect to the Enterprise Manager; the default URL is http://localhost:8888/em. Login with the username oc4jadmin and the password you chose when you started OC4J.
  2. On the first page, click Administration.
  3. Click the icon in the Go to Task column next to Logger Configuration under Administration Tasks | Properties.
  4. Expand Root Logger, then expand oracle.
  5. Locate the line with oracle.wireless.its and change the log level as desired.
  6. When finished, click Apply.

The location of the log file is dependent on the container. In case of OC4J, the messages are logged in the log.xml file (located in <JDEV_HOME>/j2ee/home/log/oc4j) by default.

For OC4J, you may also use Oracle's Java logging extension to log the results to a separate file. You can do this by adding the following code to the <JDEV_HOME>/j2ee/home/config/j2ee-logging.xml file:

  • Under the <log_handlers> element add:

  • <log_handler name="oracle.wireless.logging.ojdlhandler" class="oracle.core.ojdl.logging.ODLHandlerFactory">
    <property name="path" value="../log/its"/>
    <property name='maxFileSize' value='10485760'/>
    <property name='maxLogSize' value='104857600'/>
    </log_handler>

  • Under the <loggers> element add:

  • <logger name="oracle.wireless.its" level="NOTIFICATION:1" useParentHandlers="false">
    <handler name="oracle.wireless.logging.ojdlhandler"/>
    </logger>

If you're using this logging mechanism, the level must be one of the following:

  • ERROR:1
    This level will only log fatal exceptions that occur in ITS.
  • WARNING:1
    In addition to what is logged in the ERROR:1 level, this level also logs warnings or non-fatal exceptions that indicate a problem.
  • NOTIFICATION:1
    In addition to what is logged in the WARNING:1 level, this level also logs very important information (for example, the server start time).
  • NOTIFICATION:16
    In addition to what is logged in the NOTIFICATION:1 level, this level also logs finer grained information from the ITS that shows the high-level process flow of the server.
  • TRACE:1
    In addition to what is logged in the NOTIFICATION:16 level, this level also logs method-level information to show, at a more detailed level, the process flow of the server.
  • TRACE:16
    In addition to what is logged in the TRACE:1 level, this level also logs information from within methods and provides more comprehensive information about the process flow of the server.
  • TRACE:32
    This log level will output the same amount of information as the TRACE:16 level.

Back to the contents

Packaging, Deploying, and Running an ADFT Application

It is possible to create an ADFT application using JDeveloper's wireless extension. In that case, JDeveloper handles creating the necessary configuration files and assembling the appropriate libraries into the application's WAR file.

If you are not using JDeveloper, packaging an ADFT application is very similar to packaging an ADF Faces application, with the following additions:

  1. Ensure that the following files are present in the WEB-INF/lib folder of your WAR file.
    • <JDEV_HOME>/wireless/lib/industrial-adf-faces-api.jar
    • <JDEV_HOME>/wireless/lib/industrial-adf-faces-impl.jar
  3. Modify the WEB-INF/faces-config.xml to refer to the Telnet View Handler. To do this, add the following <application> element under <faces-config> (or modify your <application> element to contain the following):

  4. <application>
    <default-render-kit-id>oracle.adf.core</default-render-kit-id>
    <view-handler>oracle.adf.view.faces.application.industrial.TelnetViewHandlerImpl</view-handler>
    </application>

  5. Modify the WEB-INF/web.xml to set javax.faces.STATE_SAVING_METHOD to server.

  6. <context-param>
    <param-name>javax.faces.STATE_SAVING_METHOD</param-name>
    <param-value>server</param-value>
    </context-param>

You can deploy your ADFT application EAR or WAR file just as you would deploy any other web application.

Once you have deployed your ADFT application, you will need to modify the initialURI property in appConfig.xml to point to the URL of your application.

For information on how to deploy ITS to non-Oracle application servers, please refer to How To Install the Industrial Telnet Server on Third-Party Containers

Back to contents