com.wrq.apptrieve.appconn
Interface AppConnChannel

All Known Implementing Classes:
AppConnRejuvenationSession, AppConnSession

public interface AppConnChannel

AppConnChannel is an interface defining the Host Integrator server channel layer methods. These methods are all related to establishing, monitoring, or terminating a connection with the Host Integrator server.


Field Summary
static int LOG_ALL_MESSAGES
          Used by getLoggingLevel() and setLoggingLevel(int).
static int LOG_ERRORS
          Used by getLoggingLevel() and setLoggingLevel(int).
static int LOG_WARNINGS_AND_ERRORS
          Used by getLoggingLevel() and setLoggingLevel(int).
static int SessionType3270
          Return value from getSessionType().
static int SessionType5250
          Return value from getSessionType().
static int SessionTypeHP
          Return value from getSessionType().
static int SessionTypeUnknown
          Return value from getSessionType().
static int SessionTypeVT
          Return value from getSessionType().
 
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 or allocates 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 or allocates 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 creates or allocates a host session with 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 creates or allocates a host session with the specified session pool.
 void disconnect()
          Disconnects from a Host Integrator Server Session.
 void disconnect(int reserved)
          Disconnects from a Host Integrator Server Session.
 int getConnectionTimeout()
          Gets the connection timeout for a Host Integrator Server session.
 int getLastRequestID()
          Gets an integer identifier for the most recent request performed against the current Host Integrator Server session.
 java.util.Locale getLocale()
          Gets the locale for an AppConn session.
 int getLoggingLevel()
          Gets the logging level for the current session of the Host Integrator server.
 int getMajorVersion()
          Gets major version number for the AppConn connector.
 int getMethodTimeout()
          Gets the method timeout for a Host Integrator Server session.
 int getMinorVersion()
          Gets minor version number for the AppConn connector.
 java.lang.String getModelName()
          Gets the name of the Host Integrator model for the current session.
 java.lang.String getModelVersionString()
          Gets the version of the model.
 java.lang.String getServerName()
          Gets the name of the Host Integrator Server for the current session.
 int getSessionID()
          Returns an integer representing the session ID returned during the last connection attempt to the Verastream server.
 int getSessionType()
          Gets the terminal emulation type of the host session that is supported by the model specified in the connect call for this session.
 java.lang.String getVersionString()
          Gets version string for the AppConn connector.
 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.
 boolean isMetaDataOnly()
          Determines whether the Host Integrator Server session is configured to only return model meta-data for this 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 setLocale(java.util.Locale locale)
          Sets the locale for an AppConn session.
 void setLoggingLevel(int level)
          Sets the logging level for the current session of the Host Integrator server.
 void setMetaDataOnly(boolean enable)
          Elect to make a metadata-only connection.
 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.
 

Field Detail

LOG_ERRORS

static final int LOG_ERRORS
Used by getLoggingLevel() and setLoggingLevel(int).

See Also:
Constant Field Values

LOG_WARNINGS_AND_ERRORS

static final int LOG_WARNINGS_AND_ERRORS
Used by getLoggingLevel() and setLoggingLevel(int).

See Also:
Constant Field Values

LOG_ALL_MESSAGES

static final int LOG_ALL_MESSAGES
Used by getLoggingLevel() and setLoggingLevel(int).

See Also:
Constant Field Values

SessionType3270

static final int SessionType3270
Return value from getSessionType().

See Also:
Constant Field Values

SessionType5250

static final int SessionType5250
Return value from getSessionType().

See Also:
Constant Field Values

SessionTypeVT

static final int SessionTypeVT
Return value from getSessionType().

See Also:
Constant Field Values

SessionTypeHP

static final int SessionTypeHP
Return value from getSessionType().

See Also:
Constant Field Values

SessionTypeUnknown

static final int SessionTypeUnknown
Return value from getSessionType().

See Also:
Constant Field Values
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 AppConnException,
                           ApptrieveException

Establishes a connection to a Host Integrator Server and creates or allocates 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 ON.

Parameters:
server - java.lang.String - Name of the Host Integrator Server (DNS Name or IP Address)
modelName - java.lang.String - Name of a Host Integrator model
userid - java.lang.String - User ID for authorization on the Host Integrator Server
password - java.lang.String - Password for authorization on the Host Integrator Server
modelVariables - java.util.Map - Model variables to set on connection (can be null)
Throws:
AppConnException - if there is a parameter error
ApptrieveException - if a Host Integrator server error occurs
See Also:
connectToSession(java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.util.Map), connectToModelViaDomain(java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.util.Map), connectToSessionViaDomain(java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.util.Map), suspendConnection(int), resumeConnection(java.lang.String), disconnect()

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 AppConnException,
                                    ApptrieveException

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

Reasons for failure include:

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

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

Parameters:
directoryServer - java.lang.String - Name of the Host Integrator authentication and authorization directory server (AADS)
domainName - java.lang.String - Name of the Host Integrator domain to connect to
modelName - java.lang.String - Name of a Host Integrator Model
userid - java.lang.String - User ID for authorization on the Host Integrator Server
password - java.lang.String - Password for authorization on the Host Integrator Server
modelVariables - java.util.Map - model variables to set on connection (can be null)
Throws:
AppConnException - if there is a parameter error
ApptrieveException - if a Host Integrator server error occurs
See Also:
connectToModel(java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.util.Map), connectToSession(java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.util.Map), connectToSessionViaDomain(java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.util.Map), suspendConnection(int), resumeConnection(java.lang.String), disconnect()

connectToSession

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

Establishes a connection to a Host Integrator Server and creates or allocates a host session with 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 - java.lang.String - Name of the Host Integrator Server (DNS Name or IP Address)
session - java.lang.String - Name of Host Integrator session pool
userid - java.lang.String - User ID for authorization on the Host Integrator Server
password - java.lang.String - Password for authorization on the Host Integrator Server
modelVariables - java.util.Map - model variables to set on connection (can be null)
Throws:
AppConnException - if there is a parameter error
ApptrieveException - if a Host Integrator server error occurs
See Also:
connectToModel(java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.util.Map), connectToModelViaDomain(java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.util.Map), connectToSessionViaDomain(java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.util.Map), suspendConnection(int), resumeConnection(java.lang.String), disconnect()

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 AppConnException,
                                      ApptrieveException

Establishes a connection to a Host Integrator Server and creates or allocates a host session with 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 on.

Parameters:
directoryServer - java.lang.String - Name of the Host Integrator authentication and authorization directory server (AADS)
domainName - java.lang.String - Name of the Host Integrator domain to connect to
session - java.lang.String - Name of a Host Integrator session pool
userid - java.lang.String - User ID for authorization on the Host Integrator Server
password - java.lang.String - Password for authorization on the Host Integrator Server
modelVariables - java.util.Map - Model variables to set on connection (can be null)
Throws:
AppConnException - if there is a parameter error
ApptrieveException - if a Host Integrator server error occurs
See Also:
connectToModel(java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.util.Map), connectToModelViaDomain(java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.util.Map), connectToSession(java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.util.Map), suspendConnection(int), resumeConnection(java.lang.String), disconnect()

disconnect

void disconnect()

Disconnects from a Host Integrator Server Session.

Reasons for failure include:

  1. Server session has not been established.

See Also:
connectToModel(java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.util.Map), connectToModelViaDomain(java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.util.Map), connectToSession(java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.util.Map), connectToSessionViaDomain(java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.util.Map), suspendConnection(int), resumeConnection(java.lang.String)

disconnect

void disconnect(int reserved)

Disconnects from a Host Integrator Server Session.

Reasons for failure include:

  1. Server session has not been established.

Parameters:
reserved - int - reserved parameter, should always be set to zero
See Also:
connectToModel(java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.util.Map), connectToModelViaDomain(java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.util.Map), connectToSession(java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.util.Map), connectToSessionViaDomain(java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.util.Map), suspendConnection(int), resumeConnection(java.lang.String)

getLastRequestID

int getLastRequestID()

Gets an integer identifier for the most recent request performed against the current Host Integrator Server session.

If a server request has not yet been performed in the current session, this method returns 0.

Returns:
int - the ID of the most recent request to the Host Integrator server
Throws:
MetaDataOnlyException - if this is a metadata-only connection

getLocale

java.util.Locale getLocale()
Gets the locale for an AppConn session.

Returns:
Locale - the current local for the AppConn session.
See Also:
setLocale(java.util.Locale)

getLoggingLevel

int getLoggingLevel()
                    throws ApptrieveException

Gets the logging level for the current session of the Host Integrator server.

Valid logging levels are:

Returns:
int - the current logging level
Throws:
ApptrieveException - if a Host Integrator server error occurs
See Also:
setLoggingLevel(int)

getMajorVersion

int getMajorVersion()

Gets major version number for the AppConn connector.

Returns:
int - the major version number

getMethodTimeout

int getMethodTimeout()

Gets the method timeout for a Host Integrator Server session.

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

getConnectionTimeout

int getConnectionTimeout()

Gets the connection timeout for a Host Integrator Server session.

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

getMinorVersion

int getMinorVersion()

Gets minor version number for the AppConn connector.

Returns:
int - the minor version number

getModelName

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

If a session is not active, this method returns null.

Returns:
java.lang.String - the name of the current Host Integrator model

getServerName

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

If a session is not active, this method returns null.

Returns:
java.lang.String - the name if the Host Integrator server

getSessionID

int getSessionID()
Returns an integer representing the session ID returned during the last connection attempt to the Verastream server.

Returns:
session ID or -1 if no connection has been made.
Throws:
MetaDataOnlyException - if this is a metadata-only connection

getVersionString

java.lang.String getVersionString()
Gets version string for the AppConn connector. This string is of the form "majorVersion.minorVersion".

Returns:
String - the version string

getModelVersionString

java.lang.String getModelVersionString()
Gets the version of the model. The string returned uniquely identifies the version of the model deployed to the VHI server.

Returns:
String - the version string

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:
boolean - true if connected
See Also:
connectToModel(java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.util.Map), connectToModelViaDomain(java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.util.Map), connectToSession(java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.util.Map), connectToSessionViaDomain(java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.lang.String, java.util.Map), suspendConnection(int), resumeConnection(java.lang.String), disconnect()

isConnectionSecure

boolean isConnectionSecure()

Determines whether the Host Integrator Server session is using a secure connection.

Returns:
boolean - 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. This method has no effect on the current Host Integrator session if one is already established. If the setting is false, then AppConnChannel does not require a secure connection. In this case, the server security setting takes precedence. If the setting is true, AppConnChannel will force a secure connection, even though the server setting is not set to require a secure channel.

Note: this call affects only subsequent connections to a Host Integrator Server.

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

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 - String - the token received from the suspendConnection method
Throws:
ApptrieveException - if a Host Integrator server error occurs
MetaDataOnlyException - if this is a metadata-only connection
See Also:
suspendConnection(int)

setLocale

void setLocale(java.util.Locale locale)
               throws ApptrieveException,
                      java.util.MissingResourceException

Sets the locale for an AppConn session.

Parameters:
locale - Locale - the Locale to use for the AppConn session.
Throws:
ApptrieveException - if there is a parameter error
java.util.MissingResourceException - if the resource file for the locale cannot be found
See Also:
getLocale()

setLoggingLevel

void setLoggingLevel(int level)
                     throws ApptrieveException

Sets the logging level for the current session of the Host Integrator server.

This overrides the global logging level for that server and lasts until changed or until disconnection. This is intended primarily for debugging, allowing a larger class of messages to be logged by a single session without required the global logging level to be changed for the Host Integrator server. This method cannot set the logging level to one that is lower than the server's logging level configuration.

Valid logging levels are:

Parameters:
level - - the logging level to use for the AppConn session.
Throws:
AppConnException - if there is a parameter error
ApptrieveException - if a Host Integrator server error occurs
MetaDataOnlyException - if this is a metadata-only connection
See Also:
getLoggingLevel()

setMethodTimeout

void setMethodTimeout(int timeout)
                      throws ApptrieveException

Sets the method timeout for a Host Integrator Server session.

Reasons for failure include:

  1. Negative timeout value.

Parameters:
timeout - int - The timeout period in milliseconds
Throws:
ApptrieveException - if a Host Integrator server error occurs
See Also:
getMethodTimeout()

setConnectionTimeout

void setConnectionTimeout(int timeout)

Sets the connection timeout for a Host Integrator Server session.

This method is useful, for example, if the server is temporarily unable to allow any more sessions, or if the domain load has been reached. Connection attempt information, including the number of connection attempts and the time of those attempts, is written to the log.

The default value is 30 seconds.

Parameters:
timeout - int - The timeout period in seconds
See Also:
getConnectionTimeout()

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 - int - the timeout value to use for the suspended session in minutes. This value must greater than zero.
Returns:
String - the String that contains the connection token for this session. This is used in resumeSession method to re-establish the connection.
Throws:
ApptrieveException - if a Host Integrator server error occurs
MetaDataOnlyException - if this is a metadata-only connection
See Also:
resumeConnection(java.lang.String)

getSessionType

int getSessionType()
Gets the terminal emulation type of the host session that is supported by the model specified in the connect call for this session.

Return values are:

Returns:
A constant representing the terminal type of the host session.

setMetaDataOnly

void setMetaDataOnly(boolean enable)
                     throws ChannelException
Elect to make a metadata-only connection. The connection can be used to obtain information about the model, such as the names of entities and procedures, but it cannot be used to make a connection to the host. A connection made after setting this value to true will not be counted against session or session pool limits on the session server.

This method can only be invoked while not connected.

Parameters:
enable - indicating that this will be as a meta-data only session.
Throws:
ChannelException - If the session is already connected.
See Also:
isMetaDataOnly(), MetaDataOnlyException

isMetaDataOnly

boolean isMetaDataOnly()
Determines whether the Host Integrator Server session is configured to only return model meta-data for this connection.

Returns:
true if this is a meta-data only connection.
See Also:
setMetaDataOnly(boolean), MetaDataOnlyException