com.softwareag.entirex.aci
Class Broker

java.lang.Object
  com.softwareag.entirex.aci.Broker

public final class Broker
extends java.lang.Object

Represents a session instance of an EntireX Broker and handles the connection to an EntireX Broker.
This version supports TCP/IP and SSL connections to EntireX Broker. HTTP and HTTPS connections to EntireX Broker via the EntireX TunnelServlet are also supported.
Connection-related information include:

• the Broker address ("BrokerID") (for a definition see getBrokerID());
• the user ID;
• the token (optional for conversational communication, mandatory for UnitofWork communication).

User ID and token can be changed after instantiating an object of this class with the reconnect() method.
This class also handles security for user authentication and encryption of messages.
Instances of this class can be used safely in multi-threaded applications. However, all Broker calls going through the same instance of a Broker object will be serialized. Parallel Broker calls are supported when using multiple Broker objects.

Field Summary

static int	ENCRYPTION_LEVEL_BROKER Specifies that the message data for send and receive calls will be encrypted.
static int	ENCRYPTION_LEVEL_NONE Specifies that the message data will not be encrypted.
static int	ENCRYPTION_LEVEL_TARGET Specifies that the message data for send and receive calls will be encrypted.

Constructor Summary

Broker(java.lang.String brokerID, java.lang.String userID)
Creates a Broker object for the specified Broker address and user ID.

Broker(java.lang.String brokerID, java.lang.String userID, java.lang.String token)
Creates a Broker object for the specified Broker address, user ID and token.

Method Summary

void	autoLogon(java.lang.String password) Provides a password to this instance of the Broker object to be used in subsequent calls.
void	disconnect() Disconnects this Broker instance from the EntireX Broker.
java.lang.String	getApplicationName() Gets the name of the application.
java.lang.String	getBrokerID() Returns the Broker ID which was specified in the constructor of this class.
int	getCompressionLevel() Returns the compression level.
java.lang.String	getConnInfo() Returns connection information.
byte[]	getIAFToken() Get the IAF Security Token.
java.lang.String	getPartnerBrokerId() Gets the partner Broker id.
byte[]	getSecurityToken() Returns the current value of the security token.
static ThreadRunner	getThreadRunner() Gets the ThreadRunner object.
java.lang.String	getToken() Returns the token specified in the constructor of this class.
static int	getTrace() Returns the current trace level.
static int	getTransportTimeout() Gets the socket timeout value in seconds.
java.lang.String	getUniqueID() Returns a String object, which is unique for this instance of the Broker object.
java.lang.String	getUserID() Returns the current value of the user ID.
static java.lang.String	getVersion() Returns version information of the EntireX Java ACI package.
boolean	isCommandLogging() Gets the state of the command logging.
java.lang.String	kernelversion() Retrieves the version of the EntireX Broker.
void	logoff() Logs off the application from EntireX Broker.
void	logon() Logs the application on to EntireX Broker, either as client or server.
void	logon(java.lang.String password) Logs the application on to EntireX Broker with a password, either as client or server.
void	logon(java.lang.String password, java.lang.String newpassword) Logs the application on to EntireX Broker with a password and new password, either as client or server.
void	reconnect(java.lang.String userID) Reconnects this Broker object to the Broker address specified in the constructor and set the user ID.
void	reconnect(java.lang.String userID, java.lang.String token) Reconnects this Broker object to the Broker address specified in the constructor and set user ID and token.
void	setApplicationName(java.lang.String name) Sets the name of the application.
void	setCommandLogging(boolean value) Switch command logging on and off.
void	setCompressionLevel(int level) Sets the compression level.
void	setCompressionLevel(java.lang.String level) Sets the compression level.
void	setIAFToken(byte[] iafToken) Sets the IAF Security Token.
void	setSecurity(BrokerSecurity securityObject, boolean doEncrypt) Specifies a security object, enables BrokerSecurity and permits encryption/decryption of message data.
void	setSecurity(BrokerSecurity securityObject, int encryptionLevel) Specifies a security object, enables BrokerSecurity and permits encryption/decryption of message data.
void	setSecurity(BrokerSecurity securityObject, int encryptionLevel, boolean autoMode) Specifies a security object, enables BrokerSecurity and permits encryption/decryption of message data.
void	setSecurityToken(byte[] s) Sets the security token to the argument.
static void	setThreadRunner(ThreadRunner t) Sets the ThreadRunner object, which wraps the method to start a new thread.
static void	setTrace(int level) Sets the trace level.
static void	setTrace(int level, java.io.PrintWriter pw) Sets the trace level.
static void	setTransportTimeout(int timeout) Sets the socket timeout value in seconds.
java.lang.String	toString() Overrides the toString() method of the class Object.
void	useEntireXSecurity() Enables EntireX Security for this Broker instance.
void	useEntireXSecurity(boolean autoMode) Enables EntireX Security for this Broker instance.
void	useEntireXSecurity(int encryptionLevel) Enables EntireX Security for this Broker instance.
void	useEntireXSecurity(int encryptionLevel, boolean autoMode) Enables EntireX Security for this Broker instance.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

ENCRYPTION_LEVEL_NONE

public static final int ENCRYPTION_LEVEL_NONE

Specifies that the message data will not be encrypted.

Since:

EntireX 6.1.1

See Also:

Constant Field Values

ENCRYPTION_LEVEL_BROKER

public static final int ENCRYPTION_LEVEL_BROKER

Specifies that the message data for send and receive calls will be encrypted. Message data will be encrypted between the current application and the Broker. Encryption from the Broker to the partner application depends on the settings of the Broker and the partner application.

Since:

EntireX 6.1.1

See Also:

Constant Field Values

ENCRYPTION_LEVEL_TARGET

public static final int ENCRYPTION_LEVEL_TARGET

Specifies that the message data for send and receive calls will be encrypted. Data will be encrypted between the current application and the Broker, as well as between the Broker and the partner application of this communication. It is guaranteed that the message is encrypted from the client to the server and vice versa.

Since:

EntireX 6.1.1

See Also:

Constant Field Values

Constructor Detail

Broker

public Broker(java.lang.String brokerID,
              java.lang.String userID)

Creates a Broker object for the specified Broker address and user ID.

Parameters:

brokerID - The BrokerID, for a definition see getBrokerID()

userID - Authentication for the Broker instance.

Throws:

java.lang.IllegalArgumentException - if the broker ID or user ID is invalid.

Broker

public Broker(java.lang.String brokerID,
              java.lang.String userID,
              java.lang.String token)

Creates a Broker object for the specified Broker address, user ID and token.

Parameters:

brokerID - The BrokerID, for a definition see getBrokerID()

userID - Authentication for the Broker instance.

token - Token for the Broker instance. Mandatory when using units of work.

Throws:

java.lang.IllegalArgumentException - if the broker ID or user ID is invalid.

See Also:

getToken()

Method Detail

getVersion

public static java.lang.String getVersion()

Returns version information of the EntireX Java ACI package.

Returns:

Version information of Java ACI package as string.

getConnInfo

public java.lang.String getConnInfo()

Returns connection information. For TCP/IP or SSL connections the information contains host and port of the socket in use and details on the pool of sockets. This includes the pool size (as configured with the parameter 'poolsize=' in the Broker ID), 'Waits', the number of events waiting for a free socket, and 'MaxSockets', the accumulated number of sockets used during the lifetime of the application. For HTTP and HTTPS connections, this information is not available. This is for information purposes only.

Returns:

Connection information for this Broker object as string.

getBrokerID

public java.lang.String getBrokerID()

Returns the Broker ID which was specified in the constructor of this class.

The Broker ID may have the following syntax depending on the used transport method:

If the Broker ID starts with http:// or https:// HTTP/HTTPS tunneling via the EntireX TunnelServlet will be used. The Broker ID has the format http://urlOfTunnelServlet?tunnelParams or https://urlOfTunnelServlet?tunnelParams. Note that the ?tunnelParams part is optional. The TunnelServlet accepts the parameters broker and log which overwrite the corresponding values in the servlet configuration. If the parameter checkheaders=no is specified, the HTTP headers returned by the web server are not checked. This might be necessary when using the Netscape Navigator with Sun's Java Plug-in and HTTPS.

If the Broker ID starts with tcpip:// or if no protocol is specified TCP/IP will be used as the transport method. The Broker ID has the format HostnamePortnumber or tcpip://HostnamePortnumber.
HostnamePortnumber can be either hostname, hostname:portnumber or :portnumber. The hostname is either an IP hostname or a numeric IP address, the default is localhost. The port number must be numeric, default for TCP/IP is 1971, default for SSL is 1958.

If the Broker ID starts with ssl://, SSL will be used. The Broker ID has the format ssl://HostnamePortnumber?sslParams. sslParams need to specify trust_store=file, where file is the path name of a Java Keystore file which contains the list of trusted certificate authorities. Specify verify_server=no, if you do not want to check that the certificate of the SSL server is issued for the specified hostname.
If the SSL server requests a client certificate, key_store=file and key_passwd=pwd have to be specified. Again file is the path name of a Java Keystore file which contains the private key and pwd is the password which is needed to access the private key entry in the Keystore. Note that the & character must not appear in the password.

For TCP/IP and SSL there are two parameters to control the socket pooling. They are specified as part of the Broker ID. The parameter poolsize specifies the maximum number of socket connections which are kept in the socket pool. The default value for the poolsize parameter is 32. Set the poolsize parameter to 0 to disable the socket pooling. Automatic closing of socket connections is controlled by the parameter pooltimeout. If a socket connection has not been used for the specified the number of seconds, it will be closed automatically. The default for this parameter is 300 seconds.

The compression level can be set within the broker id. Add the parameter compresslevel=<value> to the broker id. Allowed values are

• 0 or NO_COMPRESSION or N
• 1 or BEST_SPEED
• 2
• 3
• 4
• 5
• 6 or DEFAULT_COMPRESSION or Y
• 7
• 8 or DEFLATED
• 9 or BEST_COMPRESSION

Returns:

Broker ID as string.

toString

public java.lang.String toString()

Overrides the toString() method of the class Object.

Overrides:

toString in class java.lang.Object

Returns:

BrokerID as a String.

getUserID

public java.lang.String getUserID()

Returns the current value of the user ID.

Returns:

user ID as String.

getSecurityToken

public byte[] getSecurityToken()

Returns the current value of the security token.
Note that the logoff() method resets the security token to null after the call has been made.

Returns:

Security Token as byte array or null.

setSecurityToken

public void setSecurityToken(byte[] s)

Sets the security token to the argument.
Note that the logon() methods reset the security token to null before the call is done and the logoff() method resets the security token after the call has been made.

Parameters:

s - new Security Token as byte array.

getToken

public java.lang.String getToken()

Returns the token specified in the constructor of this class.
Working with UnitofWorks requires a token. Using a token an application can reconnect to a Conversation or UnitofWork which was created by a different process.
When working without a token, the EntireX Broker identifies an (client or server) application by the user ID and an internal unique identifier. This internal identifier is unique to each object instance of this Broker class.
When a token is specified, the EntireX Broker identifies an application by the user ID and token. When working with tokens, ensure that all applications which communicate with the same EntireX Broker in parallel either use different user IDs or different tokens.

Returns:

Token as String or null.

setSecurity

public void setSecurity(BrokerSecurity securityObject,
                        boolean doEncrypt)

Specifies a security object, enables BrokerSecurity and permits encryption/decryption of message data.
The security object is used by the autoLogon() and logon() methods and when sending/receiving message data.
To use the security implementation of EntireX, call the method useEntireXSecurity.

Parameters:

securityObject - object which implements the BrokerSecurity interface.

doEncrypt - if true then message data will be encrypted/decrypted.

Throws:

java.lang.IllegalStateException - if security object is already set.

See Also:

logon(java.lang.String), autoLogon(java.lang.String), BrokerSecurity, useEntireXSecurity(), useEntireXSecurity(int)

setSecurity

public void setSecurity(BrokerSecurity securityObject,
                        int encryptionLevel)

Specifies a security object, enables BrokerSecurity and permits encryption/decryption of message data.
The security object is used by the autoLogon() and logon() methods and when sending/receiving message data.
To use the security implementation of EntireX, call the method useEntireXSecurity.

Parameters:

securityObject - object which implements the BrokerSecurity interface.

encryptionLevel - one of the values ENCRYPTION_LEVEL_NONE, ENCRYPTION_LEVEL_BROKER, or ENCRYPTION_LEVEL_TARGET.

Throws:

java.lang.IllegalArgumentException - if encryptionLevel is invalid.

java.lang.IllegalStateException - if security object is already set.

Since:

6.1.1

See Also:

logon(java.lang.String), autoLogon(java.lang.String), BrokerSecurity, useEntireXSecurity(), useEntireXSecurity(int), ENCRYPTION_LEVEL_NONE, ENCRYPTION_LEVEL_BROKER, ENCRYPTION_LEVEL_TARGET

setSecurity

public void setSecurity(BrokerSecurity securityObject,
                        int encryptionLevel,
                        boolean autoMode)

Specifies a security object, enables BrokerSecurity and permits encryption/decryption of message data.
The security object is used by the autoLogon() and logon() methods and when sending/receiving message data.
To use the security implementation of EntireX, call the method useEntireXSecurity.

Parameters:

securityObject - object which implements the BrokerSecurity interface.

encryptionLevel - one of the values ENCRYPTION_LEVEL_NONE, ENCRYPTION_LEVEL_BROKER, or ENCRYPTION_LEVEL_TARGET.

autoMode - if true, let the Broker object figure out whether the Broker uses security. If the Broker uses security, set the specified securityObject.

Throws:

java.lang.IllegalArgumentException - if encryptionLevel is invalid.

java.lang.IllegalStateException - if security object is already set.

Since:

7.2.1

See Also:

logon(java.lang.String), autoLogon(java.lang.String), BrokerSecurity, useEntireXSecurity(), useEntireXSecurity(int), ENCRYPTION_LEVEL_NONE, ENCRYPTION_LEVEL_BROKER, ENCRYPTION_LEVEL_TARGET

useEntireXSecurity

public void useEntireXSecurity()

Enables EntireX Security for this Broker instance.
Message data will not be encrypted.

Throws:

java.lang.IllegalStateException - if EntireX Security is already set.

Since:

6.1.1

See Also:

logon(java.lang.String), autoLogon(java.lang.String), useEntireXSecurity(int)

useEntireXSecurity

public void useEntireXSecurity(int encryptionLevel)

Enables EntireX Security for this Broker instance.
Message data will be encrypted according to the encryptionLevel parameter.

Parameters:

encryptionLevel - one of the values ENCRYPTION_LEVEL_NONE, ENCRYPTION_LEVEL_BROKER, or ENCRYPTION_LEVEL_TARGET.

Throws:

java.lang.IllegalArgumentException - if encryptionLevel is invalid.

java.lang.IllegalStateException - if EntireX Security is already set.

Since:

6.1.1

See Also:

logon(java.lang.String), autoLogon(java.lang.String), ENCRYPTION_LEVEL_NONE, ENCRYPTION_LEVEL_BROKER, ENCRYPTION_LEVEL_TARGET

useEntireXSecurity

public void useEntireXSecurity(boolean autoMode)

Enables EntireX Security for this Broker instance.

Parameters:

autoMode - if true, let the Broker object figure out whether the Broker uses security. If the Broker uses security, set the EntireXSecurity object.

Throws:

java.lang.IllegalStateException - if EntireX Security is already set.

Since:

7.2.1

See Also:

logon(java.lang.String), autoLogon(java.lang.String)

useEntireXSecurity

public void useEntireXSecurity(int encryptionLevel,
                               boolean autoMode)

Enables EntireX Security for this Broker instance.
Message data will be encrypted according to the encryptionLevel parameter.

Parameters:

encryptionLevel - one of the values ENCRYPTION_LEVEL_NONE, ENCRYPTION_LEVEL_BROKER, or ENCRYPTION_LEVEL_TARGET.

autoMode - if true, let the Broker object figure out whether the Broker uses security. If the Broker uses security, set the EntireXSecurity object.

Throws:

java.lang.IllegalArgumentException - if encryptionLevel is invalid.

java.lang.IllegalStateException - if EntireX Security is already set.

Since:

7.2.1

See Also:

logon(java.lang.String), autoLogon(java.lang.String), ENCRYPTION_LEVEL_NONE, ENCRYPTION_LEVEL_BROKER, ENCRYPTION_LEVEL_TARGET

kernelversion

public java.lang.String kernelversion()
                               throws BrokerException

Retrieves the version of the EntireX Broker.

Returns:

the Broker version and platform (if supported by Broker)

Throws:

BrokerException - if the Broker call fails.

logon

public void logon()
           throws BrokerException

Logs the application on to EntireX Broker, either as client or server.

Throws:

BrokerException - if the Broker call fails.

logon

public void logon(java.lang.String password)
           throws BrokerException

Logs the application on to EntireX Broker with a password, either as client or server.
If EntireX Broker is running in a secured environment and a security object has been set, the logon() method performs the authentication process.

Parameters:

password - Password used for authentication together with the user ID.

Throws:

BrokerException - if the Broker call fails.

logon

public void logon(java.lang.String password,
                  java.lang.String newpassword)
           throws BrokerException

Logs the application on to EntireX Broker with a password and new password, either as client or server.
If EntireX Broker is running in a secured environment and a security object has been set, the logon() method performs the authentication process.

Parameters:

password - Password used for authentication together with the user ID.

newpassword - The new password is transmitted to the Broker security exit to allow a password change.

Throws:

BrokerException - if the Broker call fails.

autoLogon

public void autoLogon(java.lang.String password)

Provides a password to this instance of the Broker object to be used in subsequent calls. Use this method only when EntireXSecurity is enabled. If autoLogon is used, no logon to the Broker will be done and the password will be sent with every subsequent Broker call. If logon is used, a logon to the Broker will be done and the password will be sent only with the logon call.
You should use autoLogon whenever there is a high probability that a sequence of Broker calls is interrupted by a client non-activity timeout. In the case of a client timeout the 0008 0146 or 0002 0134 is avoided when autoLogon has been called.

Parameters:

password - Password used for authentication together with the user ID.

Since:

5.3.1.2

logoff

public void logoff()
            throws BrokerException

Logs off the application from EntireX Broker. The logoff() method should be called after the last interaction with the Broker. EntireX Broker will release all resources used by the application.

Throws:

BrokerException - a Broker Exception

setTrace

public static void setTrace(int level)

Sets the trace level. If set to 0, then no trace output will be produced. Trace level 1 will trace all Broker calls and other major actions. Trace level 2 will dump the send and receive buffer. Trace level 3 will dump the buffers sent to the Broker and received from the Broker. Can be initialized using the entirex.trace system property. Trace output will be written to standard output (java.lang.System.out) or the specified PrintWriter object.

Parameters:

level - Trace level.

See Also:

setTrace(int, java.io.PrintWriter)

setTrace

public static void setTrace(int level,
                            java.io.PrintWriter pw)

Sets the trace level. If set to 0, then no trace output will be produced. Trace level 1 will trace all Broker calls and other major actions. Trace level 2 will dump the send and receive buffer. Trace level 3 will dump the buffers sent to the Broker and received from the Broker. Trace output will be written to the specified PrintWriter object.

Parameters:

level - Trace level.

pw - instance of PrintWriter object which will receive the trace output.

Since:

EntireX 5.2.1

getTrace

public static int getTrace()

Returns the current trace level.

Returns:

Trace level as Int.

reconnect

public void reconnect(java.lang.String userID)

Reconnects this Broker object to the Broker address specified in the constructor and set the user ID. If this changes the user ID, call logon afterwards.

Parameters:

userID - Authentication for the Broker instance.

Throws:

java.lang.IllegalArgumentException - if the user ID is invalid.

Since:

EntireX 5.2.1

reconnect

public void reconnect(java.lang.String userID,
                      java.lang.String token)

Reconnects this Broker object to the Broker address specified in the constructor and set user ID and token. If this changes the user ID, call logon afterwards.

Parameters:

userID - Authentication for the Broker instance.

token - Token for the Broker instance.

Throws:

java.lang.IllegalArgumentException - if the user ID is invalid.

Since:

EntireX 5.2.1

disconnect

public void disconnect()

Disconnects this Broker instance from the EntireX Broker. This method allows the EntireX Java runtime to close or reuse the network resources allocated for this Broker instance. You can use this method after logoff. If disconnect is not used, the network resources are freed if the Broker object is destroyed or the socket pooling frees the unused sockets.
You should call this method whenever your Java application continues to run after communication with this Broker instance has been terminated (i.e. in a multi-threading application).
Reusing this Broker object will establish a new connection to the EntireX Broker.

Since:

EntireX 5.2.1

getUniqueID

public java.lang.String getUniqueID()
                             throws java.lang.IllegalStateException

Returns a String object, which is unique for this instance of the Broker object. A value can be returned only when at least one Broker call has been made using this Broker instance. Otherwise an IllegalStateException is thrown. Calling this method for the same Broker instance always returns the same value.

Returns:

uniqueID the unique string

Throws:

java.lang.IllegalStateException - if uniqueID cannot be obtained.

Since:

EntireX 7.1.1.0

getCompressionLevel

public int getCompressionLevel()

Returns the compression level.

Returns:

the compression level.

Since:

EntireX 7.1.1.0

setCompressionLevel

public void setCompressionLevel(int level)

Sets the compression level. Valid compression levels are -1 (default compression), 0 (no compression), 1 (best speed) up to 9 (best compression).

Parameters:

level - the compression level.

Since:

EntireX 7.1.1.0

setCompressionLevel

public void setCompressionLevel(java.lang.String level)

Sets the compression level. If the string starts with 'Y', compression is turned on with level 6. If the string starts with 'N', compression is turned off (Level 0). If the string denotes an integer between 0 and 9, compression is set to this level. In addition, you may use the strings 'BEST_COMPRESSION' (level 9), 'BEST_SPEED' (1), 'DEFAULT_COMPRESSION' (6), 'DEFLATED' (8), 'NO_COMPRESSION' (0). You may use the constants defined in class java.util.zip.Deflater.

Parameters:

level - the compression level.

Since:

EntireX 7.1.1.0

setThreadRunner

public static void setThreadRunner(ThreadRunner t)

Sets the ThreadRunner object, which wraps the method to start a new thread.

Parameters:

t - the ThreadRunner object.

getThreadRunner

public static ThreadRunner getThreadRunner()

Gets the ThreadRunner object. The ThreadRunner object wraps the start method of the thread. This is used in application server to use the method of the application server to start a new thread.

Returns:

the ThreadRunner object

setTransportTimeout

public static void setTransportTimeout(int timeout)
                                throws BrokerException

Sets the socket timeout value in seconds. Used for the transport of messages over TCP/IP. Not used with HTTP. This timeout value is used for new sockets. It does not change the timeout for sockets in use. The system property entirex.timeout may be used to configure the timeout value.

Parameters:

timeout - the socket timeout value in seconds.

Throws:

BrokerException - if the timeout value is negative.

Since:

7.2.1.1

See Also:

getTransportTimeout()

getTransportTimeout

public static int getTransportTimeout()
                               throws BrokerException

Gets the socket timeout value in seconds. Reads the system property entirex.timeout. The system property is read once. The system property wins over use of setTransportTimeout.

Returns:

the socket timeout value in seconds.

Throws:

BrokerException - if the property entirex.timeout is not a number or negative.

Since:

7.2.1.1

See Also:

setTransportTimeout(int)

getApplicationName

public java.lang.String getApplicationName()

Gets the name of the application.

Returns:

the name of the application.

setApplicationName

public void setApplicationName(java.lang.String name)

Sets the name of the application. If the name is longer than 64 characters, the name is truncated to 64 characters.

Parameters:

name - the name of the application.

Throws:

java.lang.IllegalArgumentException - if the name is null or empty.

getPartnerBrokerId

public java.lang.String getPartnerBrokerId()

Gets the partner Broker id.

Returns:

the partner Broker id.

isCommandLogging

public boolean isCommandLogging()

Gets the state of the command logging.

Returns:

true if command logging is on. false otherwise.

setCommandLogging

public void setCommandLogging(boolean value)

Switch command logging on and off. The value is used for all following calls of this Broker object.

Parameters:

value - true to turn command logging on, false to turn it off.

getIAFToken

public byte[] getIAFToken()

Get the IAF Security Token. The IAF token is generated by the Broker if the Broker is set-up with IAF.

Returns:

the IAF Security Token.

setIAFToken

public void setIAFToken(byte[] iafToken)

Sets the IAF Security Token. If an IAF token is set, this is used to identify the user. The next Broker.logon call uses the IAF token, not the user id / password if the token is not null.

Parameters:

iafToken - the IAF Security Token or null.