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

Fields

Modifier and Type	Field and Description
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

Methods

Modifier and Type	Method and Description
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.
void	suspendConnection(int timeout, java.lang.String connectionToken) 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().

SessionType5250

static final int SessionType5250

Return value from getSessionType().

SessionTypeVT

static final int SessionTypeVT

Return value from getSessionType().

SessionTypeHP

static final int SessionTypeHP

Return value from getSessionType().

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:

• LOG_ERRORS
• LOG_WARNINGS_AND_ERRORS
• LOG_ALL_MESSAGES

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:

• LOG_ERRORS
• LOG_WARNINGS_AND_ERRORS
• LOG_ALL_MESSAGES

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)

suspendConnection

void suspendConnection(int timeout,
                     java.lang.String connectionToken)
                       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.

connectionToken - String - client supplied token 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:

• SessionType3270
• SessionType5250
• SessionTypeHP
• SessionTypeVT
• SessionTypeUnknown This value will be returned if the client is not connected to the server.

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