com.jagacy
Class AbstractSession

java.lang.Object
  extended bycom.jagacy.AbstractSession
Direct Known Subclasses:
Session3270

public abstract class AbstractSession
extends java.lang.Object

Supports a screen-scraping session.

Author:
Robert M. Preston

Method Summary
 void abort()
          Aborts the session.
 void close()
          Closes the session.
 Location createLocation(int row, int column)
          Creates a Location object.
 Location createLocation(java.lang.String propertyPrefix)
          Creates a location object.
protected abstract  UserInterface createUi()
          Creates a user interface.
protected  void finalize()
           
 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.
 JagacyProperties getProperties()
          Returns the Jagacy properties.
 int getWidth()
          Returns the screen's width.
 boolean isInsertOn()
          Determines if insert is on or not.
protected  void logoff()
          This method is called by close and is meant to be overidden by inheriting classes.
protected  boolean logon()
          This method is called by open and is meant to be overidden by inheriting classes.
 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 Jagacy 3270 1.2 / Jagacy VT 1.0, replaced by readCursorLocation()
 Location readCursorLocation()
          Reads the cursor.
 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 readRow(int row)
          Returns the row.
 java.lang.String[] readScreen()
          Returns the screen.
 char[] readScreenText()
          Returns the screen as character text.
 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 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.
 Key writeKey(Key key)
          Writes the given key.
 Key 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
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

createUi

protected abstract UserInterface createUi()
                                   throws JagacyException
Creates a user interface.

Returns:
The user interface.
Throws:
JagacyException - If an error occurs.
Since:
Jagacy 3270 1.4, Jagacy VT 1.1

open

public void open()
          throws JagacyException
Opens the session.

Throws:
JagacyException - If an error occurs.

logon

protected boolean logon()
                 throws JagacyException
This method is called by open and is meant to be overidden by inheriting classes. The default returns true.

Returns:
true if logon was successful; false otherwise.
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:
Jagacy 3270 1.2, Jagacy VT 1.0

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:
Jagacy 3270 1.2, Jagacy VT 1.0

createLocation

public Location createLocation(java.lang.String propertyPrefix)
                        throws JagacyException
Creates a location object. This method expects the property file to have the following entries:
<propertyPrefix>.row
<propertyPrefix>.column

Parameters:
propertyPrefix - Prefix used to lookup properties.
Returns:
location.
Throws:
JagacyException - If an error occurs.
Since:
Jagacy 3270 1.2, Jagacy VT 1.0

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:
Jagacy 3270 1.2, Jagacy VT 1.0

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.

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.

readRow

public java.lang.String readRow(int row)
                         throws JagacyException
Returns the row.

Parameters:
row - Row to read.
Returns:
Returns the row. Attributes, NULs, and hidden fields are translated into spaces.
Throws:
JagacyException - If an error occurs.
Since:
Jagacy 3270 1.3, Jagacy VT 1.0

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.

readScreenText

public char[] readScreenText()
                      throws JagacyException
Returns the screen as character text.

Returns:
Returns the screen. Attributes, NULs, and hidden fields are translated into spaces.
Throws:
JagacyException - If an error occurs.
Since:
Jagacy 3270 1.3, Jagacy VT 1.0

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:
Jagacy 3270 1.2, Jagacy VT 1.0

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.

writeKey

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

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

writeKey

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

Parameters:
keyProperty - Property to lookup.
Returns:
The key written.
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:
Jagacy 3270 1.2, Jagacy VT 1.0

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:
Jagacy 3270 1.2, Jagacy VT 1.0

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.

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 Jagacy 3270 1.2 / Jagacy VT 1.0, 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:
Jagacy 3270 1.2, Jagacy VT 1.0

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:
Jagacy 3270 1.2, Jagacy VT 1.0

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()

logoff

protected void logoff()
               throws JagacyException
This method is called by close and is meant to be overidden by inheriting classes. The default does nothing.

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:
Jagacy 3270 1.2, Jagacy VT 1.0

finalize

protected void finalize()