| Sun 3270 Pathway User's Guide |    
|
| Sun 3270 Pathway User's Guide |
|
| C H A P T E R 6 |
|
Sun 3270 Pathway Bean Programmable Interface |
The Sun 3270 Pathway Bean supports a programmable interface that enables developers to have direct access to manipulate and customize the 3270 emulator for their programs.
This chapter contains the following topics:
Within the com.sun.emp.pathway.bean package there are three classes:
There are two Java interfaces:
|
An interface that classes should implement when listening for TerminalEvent events. |
|
|
An exception thrown as a result of a runtime exception being thrown by a TerminalCondition. |
Most programming is done directly to the Terminal class. For a complete description of the available classes and methods, refer to the HTML API documentation that is located at:
The Java Bean specification states that all beans should have a zero parameter constructor. The primary method of constructing a Terminal object uses the zero parameter constructor.
The Terminal class has two constructors, as shown in the following table:
When you create an instance of a Terminal, it is not connected to any host system. You use the connect() method with a valid set of values assigned to the following properties to connect a Terminal to a TN3270 host.
The connect() method is an asynchronous call. Attempting to call it when the connection state is anything other than disconnected results in the generation of an IllegalStateException.
The following properties also affect the connection process:
The following example shows an easy way to create and start a 3270 emulator:
Terminal term = new Terminal(); term.setTN3270Host("www.myhost.com"); term.setTN3270Port(9993); term.connect(); |
There are special considerations when connecting in an applet environment. Normally, the TN3270 host must be the same as that from which the HTML of the containing web page was served. To obtain this information, you can use the getDocumentBase() method in the java.awt.Applet; for example:
This technique is illustrated in the Sample1Applet.java program.
A Terminal has four connection states:
You can think of it as a single property that has one of four values, or you can view it as four separate boolean properties:
Both views are supported by the properties of Terminal:
The getConnectionState() method returns an int representing one of the four connection states.
The isConnected(), isConnecting(), isDisconnected(), and isDisconnecting() methods return a boolean equal to true or false depending on the connection state of the 3270 emulator.
These five methods correspond to five of the Java Bean properties of the Terminal class. For a complete list of all the Terminal class properties, refer to the Javadoc
supplied with the Sun 3270 Pathway product.
The five connection-related properties are bound properties, which means that the Terminal class raises java.beans.PropertyChangeEvent events when any of these properties change. For additional information about property change events and how to listen for them, refer to your JDK API documentation. Also examine the source code of the Sample2.java program.
The keyboardLockState property determines if the keyboard is locked. You can use this property to determine when the host system has finished processing the last instruction and has returned control back to the user. Use the isKeyboardLocked() method to determine the keyboard lock state. The Sample3.java program illustrates the use of this property.
keyboardLockState is also a bound property; therefore, java.beans.PropertyChangeEvent events are raised whenever the keyboard lock state changes.
A Terminal can become disconnected in one of the following ways:
When you are finished with a Terminal, you should disconnect it from the host system either by issuing a disconnect() call or by logging off the host system. This minimizes resource usage on the host system.
When a Terminal is connected, a number of Java threads are active, raising events and maintaining the network connection. This means that a connected Terminal is not eligible for garbage collection by the Java runtime environment. Therefore, you must ensure that a Terminal is disconnected before it is dereferenced, to enable the cleanup of the resources associated with the Terminal. Perform a call to the dispose() method of the Terminal when the program has finished using it to ensure an efficient cleanup of its resource.
The Terminal has several methods that enable the application to wait until something significant has happened:
waitCondition(TerminalCondition terminalCondition)
waitForReadableString(String readableString, int offset)
In NVT mode, the keyboard is always unlocked. Therefore, the waitUntilKeyboardUnlocked() method always returns immediately.
A 3270 terminal can have two types of display: formatted (the screen consists of 3270 fields) and unformatted. This enables you to obtain information from a Terminal on a field basis or a screen buffer basis.
You can interrogate a Terminal object using the isFormatted() method to determine if the current screen is formatted or unformatted. When the terminal is in NVT mode, there are never any fields; therefore, the isFormatted() method returns false.
For a formatted display, each 3270 field is represented by a TerminalField object. You can obtain a field from a Terminal by calling one of the following methods:
After a TerminalField is obtained, you can interrogate it using one of the methods described in the Javadoc API of TerminalField. For example, you can obtain the text from a TerminalField using the getText() method.
You can programmatically modify an unprotected TerminalField using the setText() and setData() methods. These methods alter the contents of the field the same way a terminal user can alter it. An attempt to modify a protected field results in an IllegalStateException.
There are three buffers that describe the screen contents:
Performing the appropriate get method for each returns an array of characters. Because they are copies of the buffers, modifications have no effect on the 3270 terminal.
You can enter data on a formatted or unformatted screen using the typeChar() method of the Terminal class. You can obtain buffers from both formatted and unformatted screens.
You can also obtain an area of the screen using the getReadableString() method. This method returns an area of the screen as it appears to the user, that is, with attribute bytes and nulls returned as spaces.
When the terminal is in NVT mode, the color and extended attribute buffers have no meaning and are filled with default values.
When the host sends a data stream to a Terminal, it can cause the display to change in a manner asynchronous to an application program using that Terminal.
To tell an application program about an occurrence, the Terminal class raises com.sun.emp.pathway.bean.TerminalEvent events. An application program listening for these events must implement the com.sun.emp.pathway.bean.TerminalListener interface. These events are generated regardless of the terminal mode.
The TerminalListener interface currently has a single method, hostChangedScreen(), which is called when the screen is changed by a data stream from the host system, indicating that new data was received from the system.
You can register and deregister listeners of this type using the Terminal methods addTerminalListener() and removeTerminalListener().
This event is not implemented as a java.beans.PropertyChangeEvent because it does not have an associated value that changes.
A user can manipulate a visible Terminal by clicking it to give it focus, then using the keyboard to enter data.
There is also a set of Terminal methods to perform the following functions:
When a terminal is in NVT mode, a restricted set of methods are available. Calling methods that have a pure 3270 meaning when in NVT mode generates an IllegalStateException. Refer to the Javadoc supplied with Sun 3270 Pathway for a list of Terminal methods.
When the Terminal is made visible, you can see that it is made up of two areas: the emulator area and the status bar at the bottom. The status bar can be hidden by calling the method setStatusBarShowing(false).
The status bar displays information about the Terminal and is divided into sections.
The labels in FIGURE 6-1 indicate each section of the status bar and are described in the following table:
The Terminal provides a default mapping of keystrokes to functionality within the Terminal.
By default, the Terminal is set to automatically attempt to set the font size of the emulator so the whole of the emulator fills the container it is placed on. If the container changes size, the font size might increase or decrease accordingly. To turn off this behavior, call the method setAutoFontResizingEnabled(false).
Terminal has the following properties in the property list:
Model 3, 4, and 5 terminals allow the host system application to set the display size of the data on the screen when it sends a datastream to the Terminal. If the host system sends data instructions to use the alternate screen size, the current values equal the respective maximum values. If using the non-alternate screen size, the current values are set to the default values of a 3270 model 2 terminal, 80 rows, 24 columns, 1920 characters for the displaySize.
The following table defines the maximum values for each terminal model.
| Sun 3270 Pathway User's Guide | 816-5340-11 |
|
Copyright © 2003, Sun Microsystems, Inc. All rights reserved.