com.jagacy
Class Session3270

java.lang.Object
  extended bycom.jagacy.Session3270

public class Session3270
extends java.lang.Object

Supports a TN3270 screen-scraping session.

Author:
Robert M. Preston

Constructor Summary
Session3270(java.lang.String name)
          Creates a new session.
 
Method Summary
 void abort()
          Aborts the session.
 void close()
          Closes the session.
 Location createLocation(int row, int column)
          Creates a Location object.
 int getAttributeForPosition(int row, int column)
          Used internally.
 int getHeight()
          Returns the screen's height.
 Logger getLogger()
          Returns the logger.
 java.lang.String getName()
          Returns the session name.
 int getPositionField(int position, int[] offset, int[] length)
          Used internally.
 JagacyProperties getProperties()
          Returns the Jagacy properties.
 int getWidth()
          Returns the screen's width.
 boolean isInsertOn()
          Determines if insert is on or not.
 void open()
          Opens the session.
 java.lang.String read(int length)
          Reads a string at the current cursor position.
 java.lang.String read(java.lang.String lengthProperty)
          Reads a string at the current cursor position.
 long readAlarmCount()
          Returns the number of times the alarm has sounded.
 int[] readCursor()
          Deprecated. As of release 1.2, replaced by readCursorLocation()
 Location readCursorLocation()
          Reads the cursor.
 java.lang.String readField(int field, int offset, int length)
          Reads a string at the given field and offset.
 java.lang.String readField(java.lang.String propertyPrefix)
          Reads a string at the given field and offset.
 int readFieldLength(int field)
          Returns the length of a field.
 int readFieldLength(java.lang.String fieldProperty)
          Returns the length of a field.
 Field[] readFields()
          Returns an array of all the fields on the screen.
 java.lang.String readPosition(int row, int column, int length)
          Reads a string at the given coordinates.
 java.lang.String readPosition(Location location, int length)
          Reads a string at the given location.
 java.lang.String readPosition(java.lang.String propertyPrefix)
          Reads a string at the given coordinates.
 java.lang.String[] readScreen()
          Returns the screen.
 boolean waitForChange(int timeout)
          Waits for the screen to change and the keyboard to unlock.
 boolean waitForChange(java.lang.String timeoutProperty)
          Waits for the screen to change and the keyboard to unlock.
 boolean waitForField(int field, int offset, java.lang.String value, int timeout)
          Waits (in 100 millisecond intervals) for the value to appear at the given field and offset.
 boolean waitForField(java.lang.String propertyPrefix, int timeout)
          Waits (in 100 millisecond intervals) for the value to appear at the given field and offset.
 boolean waitForField(java.lang.String propertyPrefix, java.lang.String timeoutProperty)
          Waits (in 100 millisecond intervals) for the value to appear at the given field and offset.
 boolean waitForField(java.lang.String propertyPrefix, java.lang.String value, int timeout)
          Waits (in 100 millisecond intervals) for the value to appear at the given field and offset.
 boolean waitForField(java.lang.String propertyPrefix, java.lang.String value, java.lang.String timeoutProperty)
          Waits (in 100 millisecond intervals) for the value to appear at the given field and offset.
 boolean waitForPosition(int row, int column, java.lang.String value, int timeout)
          Waits (in 100 millisecond intervals) for the value to appear at the given coordinates.
 boolean waitForPosition(Location location, java.lang.String value, int timeout)
          Waits (in 100 millisecond intervals) for the value to appear at the given location.
 boolean waitForPosition(java.lang.String propertyPrefix, int timeout)
          Waits (in 100 millisecond intervals) for the value to appear at the given coordinates.
 boolean waitForPosition(java.lang.String propertyPrefix, java.lang.String timeoutProperty)
          Waits (in 100 millisecond intervals) for the value to appear at the given coordinates.
 boolean waitForPosition(java.lang.String propertyPrefix, java.lang.String value, int timeout)
          Waits (in 100 millisecond intervals) for the value to appear at the given coordinates.
 boolean waitForPosition(java.lang.String propertyPrefix, java.lang.String value, java.lang.String timeoutProperty)
          Waits (in 100 millisecond intervals) for the value to appear at the given coordinates.
 boolean waitForUnlock(int timeout)
          Waits for the keyboard to unlock.
 boolean waitForUnlock(java.lang.String timeoutProperty)
          Waits for the keyboard to unlock.
 void writeAfterLabel(java.lang.String propertyPrefix)
          Writes a string in the next unprotected field after a protected label.
 void writeAfterLabel(java.lang.String label, java.lang.String value)
          Writes a string in the next unprotected field after a protected label.
 void writeAfterLabelProperty(java.lang.String labelProperty, java.lang.String value)
          Writes a string in the next unprotected field after a protected label.
 void writeCursor(int row, int column)
          Writes the cursor at the given coordinates.
 void writeCursor(Location location)
          Writes the cursor at the given location.
 void writeCursor(java.lang.String propertyPrefix)
          Writes the cursor at the given coordinates.
 void writeField(int field, int offset, java.lang.String value)
          Writes a string at the given field and offset.
 void writeField(java.lang.String propertyPrefix)
          Writes a string at the field and offset given by the properties.
 void writeField(java.lang.String propertyPrefix, java.lang.String value)
          Writes a string at the field and offset given by the properties.
 void writeKey(Key key)
          Writes the given key.
 void writeKey(java.lang.String keyProperty)
          Writes the given key.
 void writePosition(int row, int column, java.lang.String value)
          Writes a string at the given coordinates.
 void writePosition(Location location, java.lang.String value)
          Writes a string at the given location.
 void writePosition(java.lang.String propertyPrefix)
          Writes a string at the coordinates given by the properties.
 void writePosition(java.lang.String propertyPrefix, java.lang.String value)
          Writes a string at the coordinates given by the properties.
 void writeProperty(java.lang.String valueProperty)
          Writes the contents of valueProperty at the current cursor position.
 void writeString(java.lang.String value)
          Writes a string at the current cursor position.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Session3270

public Session3270(java.lang.String name)
            throws JagacyException
Creates a new session.

Parameters:
name - The session name (also the name of the .properties file).
Throws:
JagacyException - If an error occurs.
Method Detail

open

public void open()
          throws JagacyException
Opens the session.

Throws:
JagacyException - If an error occurs.

getName

public java.lang.String getName()
Returns the session name.

Returns:
The name.

getProperties

public JagacyProperties getProperties()
Returns the Jagacy properties.

Returns:
The properties used by Jagacy. Useful for storing userids, passwords, etc. as long as the proper security permissions are set.

getLogger

public Logger getLogger()
Returns the logger.

Returns:
The logger used by Jagacy. Note that trace and info modes are used internally.

isInsertOn

public boolean isInsertOn()
Determines if insert is on or not.

Returns:
true if insert is on; false otherwise.
Since:
1.2

createLocation

public Location createLocation(int row,
                               int column)
                        throws JagacyException
Creates a Location object.

Parameters:
row - Row of location.
column - Column of location.
Returns:
location.
Throws:
JagacyException - If an error occurs.
Since:
1.2

writeString

public void writeString(java.lang.String value)
                 throws JagacyException
Writes a string at the current cursor position. Afterwards, the cursor is placed at the end of the newly written string.

Parameters:
value - String to write.
Throws:
JagacyException - If an error occurs.

writeProperty

public void writeProperty(java.lang.String valueProperty)
                   throws JagacyException
Writes the contents of valueProperty at the current cursor position. Afterwards, the cursor is placed at the end of the newly written string.

Parameters:
valueProperty - Property to lookup.
Throws:
JagacyException - If an error occurs.

writePosition

public void writePosition(int row,
                          int column,
                          java.lang.String value)
                   throws JagacyException
Writes a string at the given coordinates. Afterwards, the cursor is placed at the end of the newly written string.

Parameters:
row - Row (indexed from 0).
column - Column (indexed from 0).
value - Value to write.
Throws:
JagacyException - If an error occurs.

writePosition

public void writePosition(Location location,
                          java.lang.String value)
                   throws JagacyException
Writes a string at the given location. Afterwards, the cursor is placed at the end of the newly written string.

Parameters:
location - Location.
value - Value to write.
Throws:
JagacyException - If an error occurs.
Since:
1.2

writePosition

public void writePosition(java.lang.String propertyPrefix)
                   throws JagacyException
Writes a string at the coordinates given by the properties. Afterwards, the cursor is placed at the end of the newly written string. This method expects the property file to have the following entries:
<propertyPrefix>.row
<propertyPrefix>.column
<propertyPrefix>.value

Parameters:
propertyPrefix - Prefix used to lookup properties.
Throws:
JagacyException - If an error occurs.

writePosition

public void writePosition(java.lang.String propertyPrefix,
                          java.lang.String value)
                   throws JagacyException
Writes a string at the coordinates given by the properties. Afterwards, the cursor is placed at the end of the newly written string. This method expects the property file to have the following entries:
<propertyPrefix>.row
<propertyPrefix>.column

Parameters:
propertyPrefix - Prefix used to lookup properties.
value - String to write.
Throws:
JagacyException - If an error occurs.

writeField

public void writeField(int field,
                       int offset,
                       java.lang.String value)
                throws JagacyException
Writes a string at the given field and offset. Afterwards, the cursor is placed at the end of the newly written string.

Parameters:
field - Field (indexed from 1).
offset - Offset in the field (indexed from 1).
value - String to write.
Throws:
JagacyException - If an error occurs.

writeField

public void writeField(java.lang.String propertyPrefix)
                throws JagacyException
Writes a string at the field and offset given by the properties. Afterwards, the cursor is placed at the end of the newly written string. This method expects the property file to have the following entries:
<propertyPrefix>.field
<propertyPrefix>.offset
<propertyPrefix>.value

Parameters:
propertyPrefix - Prefix used to lookup properties.
Throws:
JagacyException - If an error occurs.

writeField

public void writeField(java.lang.String propertyPrefix,
                       java.lang.String value)
                throws JagacyException
Writes a string at the field and offset given by the properties. Afterwards, the cursor is placed at the end of the newly written string. This method expects the property file to have the following entries:
<propertyPrefix>.field
<propertyPrefix>.offset

Parameters:
propertyPrefix - Prefix used to lookup properties.
value - String to write.
Throws:
JagacyException - If an error occurs.

writeAfterLabel

public void writeAfterLabel(java.lang.String label,
                            java.lang.String value)
                     throws JagacyException
Writes a string in the next unprotected field after a protected label. Afterwards, the cursor is placed at the end of the newly written string.

Parameters:
label - Label to find.
value - String to write after label.
Throws:
JagacyException - If an error occurs.

writeAfterLabel

public void writeAfterLabel(java.lang.String propertyPrefix)
                     throws JagacyException
Writes a string in the next unprotected field after a protected label. Afterwards, the cursor is placed at the end of the newly written string. This method expects the property file to have the following entries:
<propertyPrefix>.label
<propertyPrefix>.value

Parameters:
propertyPrefix - Prefix used to lookup properties.
Throws:
JagacyException - If an error occurs.

writeAfterLabelProperty

public void writeAfterLabelProperty(java.lang.String labelProperty,
                                    java.lang.String value)
                             throws JagacyException
Writes a string in the next unprotected field after a protected label. Afterwards, the cursor is placed at the end of the newly written string.

Parameters:
labelProperty - Property to lookup.
value - String to write after label.
Throws:
JagacyException - If an error occurs.

readScreen

public java.lang.String[] readScreen()
                              throws JagacyException
Returns the screen.

Returns:
Returns the screen row by row. Attributes, NULs, and hidden fields are translated into spaces.
Throws:
JagacyException - If an error occurs.

read

public java.lang.String read(int length)
                      throws JagacyException
Reads a string at the current cursor position.

Parameters:
length - Length of string to read.
Returns:
String read.
Throws:
JagacyException - If an error occurs.

read

public java.lang.String read(java.lang.String lengthProperty)
                      throws JagacyException
Reads a string at the current cursor position.

Parameters:
lengthProperty - Property to lookup.
Returns:
String read.
Throws:
JagacyException - If an error occurs.

readPosition

public java.lang.String readPosition(int row,
                                     int column,
                                     int length)
                              throws JagacyException
Reads a string at the given coordinates.

Parameters:
row - Row (indexed from 0).
column - Column (indexed from 0).
length - Length of string to read.
Returns:
String read.
Throws:
JagacyException - If an error occurs.

readPosition

public java.lang.String readPosition(Location location,
                                     int length)
                              throws JagacyException
Reads a string at the given location.

Parameters:
location - Location of string to read.
length - Length of string to read.
Returns:
String read.
Throws:
JagacyException - If an error occurs.
Since:
1.2

readPosition

public java.lang.String readPosition(java.lang.String propertyPrefix)
                              throws JagacyException
Reads a string at the given coordinates. This method expects the property file to have the following entries:
<propertyPrefix>.row
<propertyPrefix>.column
<propertyPrefix>.length

Parameters:
propertyPrefix - Prefix used to lookup properties.
Returns:
String read.
Throws:
JagacyException - If an error occurs.

readFields

public Field[] readFields()
                   throws JagacyException
Returns an array of all the fields on the screen. If the screen is unformatted, one field is returned (field number = 0).

Returns:
An array of Fields.
Throws:
JagacyException - If an error occurs.
See Also:
Field

readField

public java.lang.String readField(int field,
                                  int offset,
                                  int length)
                           throws JagacyException
Reads a string at the given field and offset.

Parameters:
field - Field (indexed from 1).
offset - Offset (indexed from 1).
length - Length of string to read.
Returns:
String read.
Throws:
JagacyException - If an error occurs.

readField

public java.lang.String readField(java.lang.String propertyPrefix)
                           throws JagacyException
Reads a string at the given field and offset. This method expects the property file to have the following entries:
<propertyPrefix>.field
<propertyPrefix>.offset
<propertyPrefix>.length

Parameters:
propertyPrefix - Prefix used to lookup properties.
Returns:
String read.
Throws:
JagacyException - If an error occurs.

readFieldLength

public int readFieldLength(int field)
                    throws JagacyException
Returns the length of a field.

Parameters:
field - Field (indexed from 1).
Returns:
Length of field.
Throws:
JagacyException - If an error occurs.

readFieldLength

public int readFieldLength(java.lang.String fieldProperty)
                    throws JagacyException
Returns the length of a field.

Parameters:
fieldProperty - Property to lookup.
Returns:
Length of field.
Throws:
JagacyException - If an error occurs.

writeKey

public void writeKey(Key key)
              throws JagacyException
Writes the given key.

Parameters:
key - Key to write.
Throws:
JagacyException - If an error occurs.

writeKey

public void writeKey(java.lang.String keyProperty)
              throws JagacyException
Writes the given key.

Parameters:
keyProperty - Property to lookup.
Throws:
JagacyException - If an error occurs.

waitForChange

public boolean waitForChange(int timeout)
                      throws JagacyException
Waits for the screen to change and the keyboard to unlock.

Parameters:
timeout - Amount of time to wait (in milliseconds).
Returns:
true if screen changed and keyboard unlocked; false otherwise.
Throws:
JagacyException - If an error occurs.

waitForChange

public boolean waitForChange(java.lang.String timeoutProperty)
                      throws JagacyException
Waits for the screen to change and the keyboard to unlock.

Parameters:
timeoutProperty - Property to lookup (if property ends with '.seconds', value will be converted to milliseconds).
Returns:
true if screen changed and keyboard unlocked; false otherwise.
Throws:
JagacyException - If an error occurs.

waitForUnlock

public boolean waitForUnlock(int timeout)
                      throws JagacyException
Waits for the keyboard to unlock.

Parameters:
timeout - Amount of time to wait (in milliseconds).
Returns:
true if keyboard unlocked; false otherwise.
Throws:
JagacyException - If an error occurs.

waitForUnlock

public boolean waitForUnlock(java.lang.String timeoutProperty)
                      throws JagacyException
Waits for the keyboard to unlock.

Parameters:
timeoutProperty - Property to lookup (if property ends with '.seconds', value will be converted to milliseconds).
Returns:
true if keyboard unlocked; false otherwise.
Throws:
JagacyException - If an error occurs.

readAlarmCount

public long readAlarmCount()
                    throws JagacyException
Returns the number of times the alarm has sounded.

Returns:
The alarm count.
Throws:
JagacyException - If an error occurs.
Since:
1.2

waitForPosition

public boolean waitForPosition(int row,
                               int column,
                               java.lang.String value,
                               int timeout)
                        throws JagacyException
Waits (in 100 millisecond intervals) for the value to appear at the given coordinates.

Parameters:
row - Row (indexed from 0).
column - Column (indexed from 0).
value - Value to appear.
timeout - Amount of time to wait (in milliseconds).
Returns:
true if the value appeared; false otherwise.
Throws:
JagacyException - If an error occurs.

waitForPosition

public boolean waitForPosition(Location location,
                               java.lang.String value,
                               int timeout)
                        throws JagacyException
Waits (in 100 millisecond intervals) for the value to appear at the given location.

Parameters:
location - The location of the value.
value - Value to appear.
timeout - Amount of time to wait (in milliseconds).
Returns:
true if the value appeared; false otherwise.
Throws:
JagacyException - If an error occurs.
Since:
1.2

waitForPosition

public boolean waitForPosition(java.lang.String propertyPrefix,
                               java.lang.String timeoutProperty)
                        throws JagacyException
Waits (in 100 millisecond intervals) for the value to appear at the given coordinates. This method expects the property file to have the following entries:
<propertyPrefix>.row
<propertyPrefix>.column
<propertyPrefix>.value

Parameters:
propertyPrefix - Prefix used to lookup properties.
timeoutProperty - Property to lookup (if property ends with '.seconds', value will be converted to milliseconds).
Returns:
true if the value appeared; false otherwise.
Throws:
JagacyException - If an error occurs.

waitForPosition

public boolean waitForPosition(java.lang.String propertyPrefix,
                               int timeout)
                        throws JagacyException
Waits (in 100 millisecond intervals) for the value to appear at the given coordinates. This method expects the property file to have the following entries:
<propertyPrefix>.row
<propertyPrefix>.column
<propertyPrefix>.value

Parameters:
propertyPrefix - Prefix used to lookup properties.
timeout - Amount of time to wait (in milliseconds).
Returns:
true if the value appeared; false otherwise.
Throws:
JagacyException - If an error occurs.

waitForPosition

public boolean waitForPosition(java.lang.String propertyPrefix,
                               java.lang.String value,
                               java.lang.String timeoutProperty)
                        throws JagacyException
Waits (in 100 millisecond intervals) for the value to appear at the given coordinates. This method expects the property file to have the following entries:
<propertyPrefix>.row
<propertyPrefix>.column

Parameters:
propertyPrefix - Prefix used to lookup properties.
value - Value to appear.
timeoutProperty - Property to lookup (if property ends with '.seconds', value will be converted to milliseconds).
Returns:
true if the value appeared; false otherwise.
Throws:
JagacyException - If an error occurs.

waitForPosition

public boolean waitForPosition(java.lang.String propertyPrefix,
                               java.lang.String value,
                               int timeout)
                        throws JagacyException
Waits (in 100 millisecond intervals) for the value to appear at the given coordinates. This method expects the property file to have the following entries:
<propertyPrefix>.row
<propertyPrefix>.column

Parameters:
propertyPrefix - Prefix used to lookup properties.
value - Value to appear.
timeout - Amount of time to wait (in milliseconds).
Returns:
true if the value appeared; false otherwise.
Throws:
JagacyException - If an error occurs.

waitForField

public boolean waitForField(int field,
                            int offset,
                            java.lang.String value,
                            int timeout)
                     throws JagacyException
Waits (in 100 millisecond intervals) for the value to appear at the given field and offset.

Parameters:
field - Field (indexed from 1).
offset - Offset (indexed from 1).
value - Value to appear.
timeout - Amount of time to wait (in milliseconds).
Returns:
true if the value appeared; false otherwise.
Throws:
JagacyException - If an error occurs.

waitForField

public boolean waitForField(java.lang.String propertyPrefix,
                            java.lang.String timeoutProperty)
                     throws JagacyException
Waits (in 100 millisecond intervals) for the value to appear at the given field and offset. This method expects the property file to have the following entries:
<propertyPrefix>.field
<propertyPrefix>.offset
<propertyPrefix>.value

Parameters:
propertyPrefix - Prefix used to lookup properties.
timeoutProperty - Property to lookup (if property ends with '.seconds', value will be converted to milliseconds).
Returns:
true if the value appeared; false otherwise.
Throws:
JagacyException - If an error occurs.

waitForField

public boolean waitForField(java.lang.String propertyPrefix,
                            int timeout)
                     throws JagacyException
Waits (in 100 millisecond intervals) for the value to appear at the given field and offset. This method expects the property file to have the following entries:
<propertyPrefix>.field
<propertyPrefix>.offset
<propertyPrefix>.value

Parameters:
propertyPrefix - Prefix used to lookup properties.
timeout - Amount of time to wait (in milliseconds).
Returns:
true if the value appeared; false otherwise.
Throws:
JagacyException - If an error occurs.

waitForField

public boolean waitForField(java.lang.String propertyPrefix,
                            java.lang.String value,
                            java.lang.String timeoutProperty)
                     throws JagacyException
Waits (in 100 millisecond intervals) for the value to appear at the given field and offset. This method expects the property file to have the following entries:
<propertyPrefix>.field
<propertyPrefix>.offset

Parameters:
propertyPrefix - Prefix used to lookup properties.
value - Value to appear.
timeoutProperty - Property to lookup (if property ends with '.seconds', value will be converted to milliseconds).
Returns:
true if the value appeared; false otherwise.
Throws:
JagacyException - If an error occurs.

waitForField

public boolean waitForField(java.lang.String propertyPrefix,
                            java.lang.String value,
                            int timeout)
                     throws JagacyException
Waits (in 100 millisecond intervals) for the value to appear at the given field and offset. This method expects the property file to have the following entries:
<propertyPrefix>.field
<propertyPrefix>.offset

Parameters:
propertyPrefix - Prefix used to lookup properties.
value - Value to appear.
timeout - Amount of time to wait (in milliseconds).
Returns:
true if the value appeared; false otherwise.
Throws:
JagacyException - If an error occurs.

getWidth

public int getWidth()
Returns the screen's width.

Returns:
The screen's width.

getHeight

public int getHeight()
Returns the screen's height.

Returns:
The screen's height.

readCursor

public int[] readCursor()
                 throws JagacyException
Deprecated. As of release 1.2, replaced by readCursorLocation()

Reads the cursor.

Returns:
int[0] is the cursor's row, and int[1] is the cursor's column.
Throws:
JagacyException - If an error occurs.

readCursorLocation

public Location readCursorLocation()
                            throws JagacyException
Reads the cursor.

Returns:
The cursor location.
Throws:
JagacyException - If an error occurs.
Since:
1.2

writeCursor

public void writeCursor(int row,
                        int column)
                 throws JagacyException
Writes the cursor at the given coordinates.

Parameters:
row - Row (indexed from 0).
column - Column (indexed from 0).
Throws:
JagacyException - If an error occurs.

writeCursor

public void writeCursor(Location location)
                 throws JagacyException
Writes the cursor at the given location.

Parameters:
location - The location at which to write the cursor.
Throws:
JagacyException - If an error occurs.
Since:
1.2

writeCursor

public void writeCursor(java.lang.String propertyPrefix)
                 throws JagacyException
Writes the cursor at the given coordinates. This method expects the property file to have the following entries:
<propertyPrefix>.row
<propertyPrefix>.column

Parameters:
propertyPrefix - Prefix used to lookup properties.
Throws:
JagacyException - If an error occurs.

getAttributeForPosition

public int getAttributeForPosition(int row,
                                   int column)
                            throws JagacyException
Used internally. Returns the raw attribute associated with the given coordinates.

Parameters:
row - Row (indexed from 0).
column - Column (indexed from 0).
Returns:
The attribute or -1 if the screen is unformatted.
Throws:
JagacyException - If an error occurs.
See Also:
Field.getAttribute()

getPositionField

public int getPositionField(int position,
                            int[] offset,
                            int[] length)
                     throws JagacyException
Used internally. Returns the field information for the given coordinates.

Parameters:
position - Position to find.
offset - Offset within field.
length - Length of field.
Returns:
Field (indexed from 1)
Throws:
JagacyException - If an error occurs.

close

public void close()
           throws JagacyException
Closes the session.

Throws:
JagacyException - If an error occurs.

abort

public void abort()
Aborts the session.

Since:
1.2