com.wrq.vhi.script.api
Interface RemoteHostSession

All Superinterfaces:
HostSession

public interface RemoteHostSession
extends HostSession

A host session connector that can be used to connect to a different model from within an event handler. A connector is created using the Event.createHostSession() method. Once created, a connection must be established to a Host Integrator Server before most of the methods can be used.


Field Summary
 
Fields inherited from interface com.wrq.vhi.script.api.HostSession
ANY_COLUMN, ANY_ROW, CURRENT_COLUMN, CURRENT_ROW, DESIGN_TOOL_AND_SERVER, DESIGN_TOOL_ONLY, DONT_WAIT_FOR_ECHO, LINEAR_REGION, RECTANGULAR_REGION, SCROLL_END, SCROLL_HOME, SCROLL_LINE_DOWN, SCROLL_LINE_UP, SCROLL_PAGE_DOWN, SCROLL_PAGE_UP, SYNC_TO_HOST, WAIT_FOR_CURSOR_AUTOTAB, WAIT_FOR_CURSOR_MOVE, WAIT_FOR_ECHO_BEHIND_CURSOR, WAIT_FOR_ECHO_SAME_NUMBER, WAIT_FOR_ECHO_TAB_OR_BEHIND_CURSOR
 
Method Summary
 void connectToModel(java.lang.String server, java.lang.String modelName, java.lang.String userid, java.lang.String password, java.util.Map modelVariables)
          Establishes a connection to a Host Integrator Server and creates a host session with the specified model.
 void connectToModelViaDomain(java.lang.String directoryServer, java.lang.String domainName, java.lang.String modelName, java.lang.String userid, java.lang.String password, java.util.Map modelVariables)
          Establishes a connection to a Host Integrator Server and creates a host session with the specified model.
 void connectToSession(java.lang.String server, java.lang.String session, java.lang.String userid, java.lang.String password, java.util.Map modelVariables)
          Establishes a connection to a Host Integrator Server and obtains a host session from the specified session pool.
 void connectToSessionViaDomain(java.lang.String directoryServer, java.lang.String domainName, java.lang.String session, java.lang.String userid, java.lang.String password, java.util.Map modelVariables)
          Establishes a connection to a Host Integrator Server and obtains a host session from the specified session pool.
 void disconnect()
          Disconnects from a Host Integrator Server Session.
 int getConnectionTimeout()
          Gets the connection timeout for a Host Integrator Server session.
 int getMethodTimeout()
          Gets the method timeout for a Host Integrator Server session.
 java.lang.String getModelName()
          Gets the name of the Host Integrator model for the current session.
 java.lang.String getServerName()
          Gets the name of the Host Integrator Server for the current session.
 boolean isConnected()
          Determines whether the Host Integrator Server session is connected.
 boolean isConnectionSecure()
          Determines whether the Host Integrator Server session is using a secure connection.
 void requireSecureConnection(boolean require)
          Requires a secure channel on the next connection to a Host Integrator Server.
 void resumeConnection(java.lang.String connectionToken)
          Resumes the execution of a currently suspended Host Integrator server session.
 void setConnectionTimeout(int timeout)
          Sets the connection timeout for a Host Integrator Server session.
 void setMethodTimeout(int timeout)
          Sets the method timeout for a Host Integrator Server session.
 java.lang.String suspendConnection(int timeout)
          Suspends the execution of a currently running Host Integrator Server session.
 
Methods inherited from interface com.wrq.vhi.script.api.HostSession
checkOperationConditions, defaultValue, executeCommandList, executeOperation, executeSQLStatement, executeTableProcedure, fetchRecords, getAttribute, getAttributeAtCursor, getAttributeMetaData, getAttributeRegion, getAttributeRegions, getAttributes, getAttributes, getColumnMetaData, getCurrentEntity, getCurrentRecord, getCurrentRecordIndex, getCurrentRecordSet, getCursorPosition, getEntityAttributes, getEntityDescription, getEntityOperations, getEntityRecordSets, getFieldMetaData, getFieldRegion, getFieldRegions, getHomeEntity, getLinearTerminalRegion, getModelEntities, getModelVariable, getModelVariableNames, getModelVariables, getOperationMetaData, getPatternRegion, getPatternRegions, getProcedureMetaData, getRecordRegion, getRecordSetMetaData, getRecordSetRegion, getRectangularTerminalRegion, getStringAtCursor, getStringAtLocation, getStringAtOffset, getTableColumns, getTableDescription, getTableNames, getTableProcedures, getTerminalScreen, getTerminalScreenSize, getVariableMetaData, insertRecord, insertRecords, moveCurrentRecordIndex, moveCursor, navigate, nextRecord, readFromMappedAttribute, readVariableFromAttribute, readVariableFromField, readVariableFromLocation, readVariableFromTerminal, resetRecordSet, selectCurrentRecord, selectRecordByFilter, selectRecordByIndex, setAttribute, setAttributeDelayed, setAttributes, setAttributesDelayed, setCurrentEntity, setCurrentRecordIndex, setCurrentRecordSet, setModelVariable, setModelVariables, shiftCursor, transmit, transmit, transmitTerminalKey, transmitToAttribute, transmitToField, transmitToLocation, transmitToLocation, transmitToOffset, transmitToOffset, updateAttribute, updateAttributes, updateAttributes, updateCurrentRecord, updateRecordByFilter, updateRecordByIndex, updateRecords, updateRecordSetField, updateRecordSetFields, updateRecordSetFields, wait, waitForCommString, waitForCommString, waitForCondition, waitForCursorAtAttribute, waitForCursorAtLocation, waitForCursorAtRecordSetField, waitForCursorAtTerminalField, waitForCursorNotAtLocation, waitForCursorNotAtTerminalField, waitForDisplayString, waitForEntities, waitForEntity, waitForHostData, waitForHostSilence, waitForKeyboardEnabled, waitForMultipleEvents, waitForNewHostScreen, waitForUpdate, waitMS, writeToMappedAttribute, writeVariableToAttribute, writeVariableToField, writeVariableToLocation, writeVariableToTerminal
 

Method Detail

connectToModel

void connectToModel(java.lang.String server,
                    java.lang.String modelName,
                    java.lang.String userid,
                    java.lang.String password,
                    java.util.Map modelVariables)
                    throws ApptrieveException

Establishes a connection to a Host Integrator Server and creates a host session with the specified model.

Reasons for failure include:

  1. There are no Host Integrator servers running.
  2. Invalid server name or IP address.
  3. Invalid model name.
  4. Invalid userID and/or password.
  5. Already connected to a Host Integrator server.

The parameters userID and password are used by Host Integrator Server if the security option is enabled.

Parameters:
server - name of the Host Integrator Server (DNS Name or IP Address)
modelName - name of a Host Integrator model
userid - user ID for authorization on the Host Integrator Server
password - password for authorization on the Host Integrator Server
modelVariables - model variables to set on connection (can be null)
Throws:
ApptrieveException - if the connection fails

connectToModelViaDomain

void connectToModelViaDomain(java.lang.String directoryServer,
                             java.lang.String domainName,
                             java.lang.String modelName,
                             java.lang.String userid,
                             java.lang.String password,
                             java.util.Map modelVariables)
                             throws ApptrieveException

Establishes a connection to a Host Integrator Server and creates a host session with the specified model. The connection is made using the specified AADS Server and Host Integrator Domain.

Reasons for failure include:

  1. Can't locate the Host Integrator AADS Server.
  2. Canít locate Host Integrator Domain Server.
  3. Invalid model name.
  4. Invalid userID and/or password.
  5. Already connected to a Host Integrator session.

The parameters userID and password are used by Host Integrator Server if the security option is enabled.

Parameters:
directoryServer - name of the Host Integrator authentication and authorization directory server (AADS)
domainName - name of the Host Integrator domain to connect to
modelName - name of a Host Integrator Model
userid - user ID for authorization on the Host Integrator Server
password - password for authorization on the Host Integrator Server
modelVariables - model variables to set on connection (can be null)
Throws:
ApptrieveException - if the connection fails

connectToSession

void connectToSession(java.lang.String server,
                      java.lang.String session,
                      java.lang.String userid,
                      java.lang.String password,
                      java.util.Map modelVariables)
                      throws ApptrieveException

Establishes a connection to a Host Integrator Server and obtains a host session from the specified session pool.

Reasons for failure include:

  1. Host Integrator server is not running.
  2. Invalid server name or IP address.
  3. Invalid session name.
  4. Invalid userID and/or password.

The parameters userID and password are used by Host Integrator Server if the security option is enabled.

Parameters:
server - name of the Host Integrator Server (DNS Name or IP Address)
session - name of Host Integrator session pool
userid - user ID for authorization on the Host Integrator Server
password - password for authorization on the Host Integrator Server
modelVariables - model variables to set on connection (can be null)
Throws:
ApptrieveException - if the connection fails

connectToSessionViaDomain

void connectToSessionViaDomain(java.lang.String directoryServer,
                               java.lang.String domainName,
                               java.lang.String session,
                               java.lang.String userid,
                               java.lang.String password,
                               java.util.Map modelVariables)
                               throws ApptrieveException

Establishes a connection to a Host Integrator Server and obtains a host session from the specified session pool. The connection is made using the specified AADS Server and Host Integrator Domain.

Reasons for failure include:

  1. Can't locate Host Integrator AADS Server.
  2. Canít locate Host Integrator Domain Server.
  3. Invalid session name.
  4. Invalid userID and/or password.

The parameters userID and password are used by Host Integrator Server if the security option is enabled.

Parameters:
directoryServer - name of the Host Integrator authentication and authorization directory server (AADS)
domainName - name of the Host Integrator domain to connect to
session - name of a Host Integrator session pool
userid - user ID for authorization on the Host Integrator Server
password - password for authorization on the Host Integrator Server
modelVariables - model variables to set on connection (can be null)
Throws:
ApptrieveException - if the connection fails

disconnect

void disconnect()
Disconnects from a Host Integrator Server Session.


getMethodTimeout

int getMethodTimeout()
Gets the method timeout for a Host Integrator Server session. The method timeout is the maximum time allowed for a method call. If the timeout expires during the course of a method, an ApptrieveException will be thrown with the message "Timed out waiting for data".

Returns:
the timeout in milliseconds
See Also:
setMethodTimeout(int)

setMethodTimeout

void setMethodTimeout(int timeout)
                      throws ApptrieveException
Sets the method timeout for a Host Integrator Server session. The method timeout is the maximum time allowed for a method call. If the timeout expires during the course of a method, an ApptrieveException will be thrown with the message "Timed out waiting for data".

Parameters:
timeout - the timeout in milliseconds
Throws:
ApptrieveException
See Also:
getMethodTimeout()

getConnectionTimeout

int getConnectionTimeout()
Gets the connection timeout for a Host Integrator Server session.

Returns:
the timeout in seconds
See Also:
setConnectionTimeout(int)

setConnectionTimeout

void setConnectionTimeout(int timeout)
Sets the connection timeout for a Host Integrator Server session.

Parameters:
timeout - the timeout in seconds
See Also:
getConnectionTimeout()

getModelName

java.lang.String getModelName()
Gets the name of the Host Integrator model for the current session.

Returns:
the name of the model or null if no connection has been established

getServerName

java.lang.String getServerName()
Gets the name of the Host Integrator Server for the current session.

Returns:
the name of the server or null if no connection has been established

isConnected

boolean isConnected()
Determines whether the Host Integrator Server session is connected.

The return value is true if AppConnSession believes it is currently connected to a Host Integrator server session. This method does not actually perform a server operation to determine whether connection is present. It is possible for the connection to have been lost without the connector detecting it. In this case isConnected() will return true, even though a connection is not present.

Returns:
true if connected

isConnectionSecure

boolean isConnectionSecure()
Determines whether the Host Integrator Server session is using a secure connection.

Returns:
true if the connection is secure, false otherwise

requireSecureConnection

void requireSecureConnection(boolean require)
Requires a secure channel on the next connection to a Host Integrator Server.

Note: this call affects only subsequent connections to a Host Integrator Server. It has no affect on any already established connection.

Parameters:
require - set to true to require a secure connection, false otherwise

suspendConnection

java.lang.String suspendConnection(int timeout)
                                   throws ApptrieveException
Suspends the execution of a currently running Host Integrator Server session. On successful suspension, the methods returns a token to be used when resuming the session. If the current session is already suspended, this method does nothing. The suspended session automatically terminates if it is not resumed before the specified timeout period elapses.

Reasons for failure include:

  1. Server session has not been established.
  2. Current server session cannot be suspended.

Parameters:
timeout - the timeout value to use for the suspended session in minutes
Returns:
a string that contains the connection token for this session. This is used in resumeSession method to re-establish the connection.
Throws:
ApptrieveException - if the suspension fails
See Also:
resumeConnection(java.lang.String)

resumeConnection

void resumeConnection(java.lang.String connectionToken)
                      throws ApptrieveException
Resumes the execution of a currently suspended Host Integrator server session. If the requested session is already running, this method does nothing.

Reasons for failure include:

  1. Server session has not been established.
  2. Server session is no longer present.

Parameters:
connectionToken - the token received from the suspendConnection method
Throws:
ApptrieveException - if the resume fails
See Also:
suspendConnection(int)