COM.activesw.api.client
Class BrokerConnectionDescriptor

java.lang.Object
  COM.activesw.api.client.BrokerConnectionDescriptor

public class BrokerConnectionDescriptor
extends java.lang.Object

This class provides a way to configure the connection which a BrokerClient object uses.

Connection Sharing: A BrokerClient object created with connection sharing set to true will allow its connection to the broker to be re-used by other BrokerClient objects in order to increase performance. When set to false, the network connection used by the client will never be shared.

Automatic Reconnect: A BrokerClient object created with automatic reconnect set to true will attempt to reconnect to the broker if at any time it finds that its connection to the broker has been lost. If its client does not exist, then a new one will get created. Explicitly calling disconnect() or destroy() on a client disables this feature.

State Sharing: A BrokerClient object created with state sharing set to true will allow other BrokerClient objects to use reconnect to open sessions with the client's state on the broker. All BrokerClients which are sharing the client's state will affect one another. This feature should be used with care. A value of false, is the default, and causes the Broker to only allow one session to use the client's state at a time. This quality only applies to making a new client. It is completely ignored when reconnecting clients.

Shared Event Ordering: A BrokerClient object created with state sharing set to true and with enforced event order set to SHARED_ORDER_BY_PUBLISHER, will enforce that the events delivered to the clients are ordered so that no event from a publisher is processed until its preceding events are processed. If enforced event order is set to SHARED_ORDER_NONE, then no ordering is imposed on the events delivered to the clients. This feature should be used with care because it can cause a client's events to be processed out of order. A value of SHARED_ORDER_BY_PUBLISHER, is the default. This quality only applies to making a new client. It is completely ignored when reconnecting clients, or when creating clients which do not have state sharing enabled.

Secure Socket Certificate: Secure socket layer (SSL) support requires a certificate file in order to validate the digital certificates. SSL is enabled whenever the certifcate file is not null. In addition, a certificate in the file can be specified using the distinguished name. If the distinguished name is null, then the client connects annonymously. If it is non-null, then the digital certificate for that name is used. If it is USE_DEFAULT_DN, then the default name in the certificate file is used.

Access Label Hint: When using the access label feature, this allows a client to specify a hint string to be used to look up the client's access label. Access labels are only looked up when creating a client, so the hint is ignored when reconnecting.

Forced Reconnect: A BrokerClient object created with forced reconnect set to true can be forcefully reconnected to. This will reconnect to the client and possibly disconnect the existing connected session. Forced reconnect cannot be used in conjunction with shared state. A value of false is the default.

Redelivery Count: A BrokerClient object created with redelivery count set to true will have delivery counts tracked for it by the Broker. Redelivery counts can be incremented automatically or manually. A value of false for redelivery count is the default. If turned on, manual increments are the default.

Keep Alive settings: KeepAlive settings are pertinent to the network connection that is created on behalf of BrokerClient object. In case of State Sharing Clients KeepAlive settings might be different for different sessions of the client. Keep Alive settings are important for network connection sharing, connections with different Keep Alive settings can not be shared. KeepAlive settings are comprised from 3 attributes:
KeepAlivePeriod: Specifies how often the Broker will send Keep Alive messages through the connection. Integer.MAX_VALUE (default) means Broker will not send Keep Alive messages
MaxResponseTime: Specifies how long the Broker will wait for a response from a Client before disconnecting it. Integer.MAX_VALUE(default) means the Broker will not never disconnect the Client. See also KeepAliveRetryCount.
KeepAliveRetryCount: Broker will retry sending KeepAlive messages this many times before actually disconnecting the Client. Default value is 1.

Client Storage: A BrokerClient object may override it's storage type in the Broker by supplying a different storage type, BrokerTypeDef.STORAGE_VOLATILE, BrokerTypeDef.STORAGE_PERSISTENT, or BrokerTypeDef.STORAGE_GUARANTEED. Default is according to Client Group.

Client LifeCycle: A BrokerClient object may override it's lifecycle in the Broker, by supplying a different lifecycle, BrokerAdminClient.LIFECYCLE_DESTROY_ON_DISCONNECT or BrokerAdminClient.LIFECYCLE_EXPLICIT_DESTROY. Default is according to Client Group.

Priority Ordering A BrokerClient may request that events sent to it are received in priority order. The event's priority is set by the BrokerClient sending the events. Default value is false (no priority ordering).

Field Summary

static BrokerConnectionDescriptor	defaultDescriptor
static int	ENCRYPT_LEVEL_NO_ENCRYPTION
static int	ENCRYPT_LEVEL_US_DOMESTIC
static int	ENCRYPT_LEVEL_US_EXPORT
static java.lang.String	SHARED_ORDER_BY_PUBLISHER
static java.lang.String	SHARED_ORDER_NONE
static java.lang.String	USE_DEFAULT_DN

Constructor Summary

BrokerConnectionDescriptor()
Create an empty connection descriptor.

BrokerConnectionDescriptor(BrokerConnectionDescriptor desc)
Copy constructor

Method Summary

boolean	equals(BrokerConnectionDescriptor desc)
java.lang.String	getAccessLabelHint() Get the access label hint.
boolean	getAckVolatile() Internal use only.
boolean	getAutomaticReconnect() Get the automatic reconnect status of the descriptor.
boolean	getAutomaticRedeliveryCount() Get the redelivery_count_auto status of the descriptor.
int	getClientLifeCycle() Internal use only.
int	getClientStorage() Internal use only.
boolean	getConnectionShare() Get the connection share status of the descriptor.
int	getConnectionShareLimit() Get the maximum number of clients that may share the connection.
boolean	getForcedReconnect() Get the forced_reconnect status of the descriptor.
int	getKeepAlivePeriod() Get the Keep Alive Period of the descriptor.
int	getKeepAliveRetryCount() Get the Keep Alive Retry Count of the descriptor.
java.util.Locale	getLocale() Get the locale for this connection.
int	getMaxResponseTime() Get the Max Response Time of the descriptor.
boolean	getPriorityOrdering() Get the event priority ordering status of the descriptor.
boolean	getRedeliveryCountEnabled() Get the redelivery_count status of the descriptor.
java.lang.String	getSharedEventOrdering() Get the shared event ordering status of the descriptor.
static BrokerSSLCertificate	getSSLCertificate(java.lang.String certificate_file, java.lang.String trust_file, COM.activesw.api.client.enums.KeystoreType keystore_type, COM.activesw.api.client.enums.TruststoreType truststore_type, java.lang.String password) Get the SSL certificate for a specific distinguished name from a certificate file.
static BrokerSSLCertificate	getSSLCertificate(java.lang.String certificate_file, java.lang.String password, java.lang.String distinguished_name) Get the SSL certificate for a specific distinguished name from a certificate file.
static java.lang.String[]	getSSLCertificateDns(java.lang.String certificate_file, java.lang.String password) Get the list of distinguished names from a certificate file.
static java.lang.String[]	getSSLCertificateDns(java.lang.String certificate_file, java.lang.String trust_file, COM.activesw.api.client.enums.KeystoreType keystore_type, COM.activesw.api.client.enums.TruststoreType truststore_type, java.lang.String password) Get the list of distinguished names from a certificate file.
java.lang.String	getSSLCertificateFile() Deprecated. Get the secure socket layer (SSL) certificate file.
java.lang.String	getSSLDistinguishedName() Get the secure socket layer (SSL) distinguished name.
boolean	getSSLEncrypted() Get the secure socket layer encryption flag.
static int	getSSLEncryptionLevel() Get the SSL encryption level that this library is capable of.
java.lang.String	getSSLKeystore()
COM.activesw.api.client.enums.KeystoreType	getSSLKeystoreType()
static java.lang.String[]	getSSLRootDns(java.lang.String keystore, java.lang.String truststore, COM.activesw.api.client.enums.KeystoreType keystore_type, COM.activesw.api.client.enums.TruststoreType truststore_type, java.lang.String password) Get the list of trusted root distinguished names from a certificate file.
java.lang.String	getSSLTruststore()
COM.activesw.api.client.enums.TruststoreType	getSSLTruststoreType()
boolean	getStateShare() Get the state share status of the descriptor.
void	setAccessLabelHint(java.lang.String hint) Set the access label hint.
void	setAckVolatile(boolean on) Internal use only.
void	setAutomaticReconnect(boolean reconnect) Set the automatic reconnect status of the descriptor.
void	setAutomaticRedeliveryCount(boolean on) Set the redelivery_count_auto status of the descriptor.
void	setClientLifeCycle(int l) Internal use only.
void	setClientStorage(int s) Internal use only.
void	setConnectionShare(boolean shared) Set the connection share status of the descriptor.
void	setConnectionShareLimit(int limit) Set the maximum number of clients that may share the connection.
void	setForcedReconnect(boolean forced) Set the forced reconnect status of the descriptor.
void	setKeepAlive(int KeepAlivePeriod, int MaxResponseTime, int RetryCount) Set the Keep Alive settings on the descriptor
void	setLocale(java.util.Locale locale) Set the locale for this connection.
void	setPriorityOrdering(boolean new_value) Set the event priority ordering status of the descriptor.
void	setRedeliveryCountEnabled(boolean on) Set the redelivery_count status of the descriptor.
void	setSharedEventOrdering(java.lang.String ordering) Set the shared event ordering status of the descriptor.
void	setSSLCertificate(java.lang.String keystore, java.lang.String truststore, COM.activesw.api.client.enums.KeystoreType keystore_type, COM.activesw.api.client.enums.TruststoreType truststore_type, java.lang.String password)
void	setSSLDistinguishedName(java.lang.String dn)
void	setSSLEncrypted(boolean encrypted) Set the secure socket layer encryption flag.
void	setStateShare(boolean shared) Set the state share status of the descriptor.
java.lang.String	toString() Return a human-readable string with the descriptor's value.

Methods inherited from class java.lang.Object

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

Field Detail

USE_DEFAULT_DN

public static final java.lang.String USE_DEFAULT_DN

See Also:

Constant Field Values

ENCRYPT_LEVEL_NO_ENCRYPTION

public static final int ENCRYPT_LEVEL_NO_ENCRYPTION

See Also:

Constant Field Values

ENCRYPT_LEVEL_US_EXPORT

public static final int ENCRYPT_LEVEL_US_EXPORT

See Also:

Constant Field Values

ENCRYPT_LEVEL_US_DOMESTIC

public static final int ENCRYPT_LEVEL_US_DOMESTIC

See Also:

Constant Field Values

SHARED_ORDER_NONE

public static final java.lang.String SHARED_ORDER_NONE

See Also:

Constant Field Values

SHARED_ORDER_BY_PUBLISHER

public static final java.lang.String SHARED_ORDER_BY_PUBLISHER

See Also:

Constant Field Values

defaultDescriptor

public static final BrokerConnectionDescriptor defaultDescriptor

Constructor Detail

BrokerConnectionDescriptor

public BrokerConnectionDescriptor()

Create an empty connection descriptor. The default state is: connection shared=true, automatic reconnect=false, state shared=false, SSL certificate file=null.

BrokerConnectionDescriptor

public BrokerConnectionDescriptor(BrokerConnectionDescriptor desc)

Copy constructor

Method Detail

equals

public boolean equals(BrokerConnectionDescriptor desc)

getConnectionShare

public boolean getConnectionShare()

Get the connection share status of the descriptor.

setConnectionShare

public void setConnectionShare(boolean shared)

Set the connection share status of the descriptor.

getConnectionShareLimit

public int getConnectionShareLimit()

Get the maximum number of clients that may share the connection. The default value is Integer.MAX_VALUE.

setConnectionShareLimit

public void setConnectionShareLimit(int limit)

Set the maximum number of clients that may share the connection. It must be greater than or equal to 2. The default value is Integer.MAX_VALUE. This parameter is ignored if connection sharing is disabled.

Throws:

java.lang.IllegalArgumentException - if limit < 2

getAutomaticReconnect

public boolean getAutomaticReconnect()

Get the automatic reconnect status of the descriptor.

setAutomaticReconnect

public void setAutomaticReconnect(boolean reconnect)

Set the automatic reconnect status of the descriptor.

getStateShare

public boolean getStateShare()

Get the state share status of the descriptor.

setStateShare

public void setStateShare(boolean shared)

Set the state share status of the descriptor.

getSharedEventOrdering

public java.lang.String getSharedEventOrdering()

Get the shared event ordering status of the descriptor. Valid values are SHARED_ORDER_*.

setSharedEventOrdering

public void setSharedEventOrdering(java.lang.String ordering)
                            throws BrokerException

Set the shared event ordering status of the descriptor. Valid values are SHARED_ORDER_*. Setting an invalid value will cause an error when creating the client.

Throws:

BrokerNullParameterException - If ordering is null.

BrokerOutOfRangeException - If odering contains spaces or unprintable characters.

BrokerException

getSSLCertificateFile

public java.lang.String getSSLCertificateFile()

Deprecated. Get the secure socket layer (SSL) certificate file.

getSSLKeystore

public java.lang.String getSSLKeystore()

getSSLTruststore

public java.lang.String getSSLTruststore()

getSSLTruststoreType

public COM.activesw.api.client.enums.TruststoreType getSSLTruststoreType()

getSSLKeystoreType

public COM.activesw.api.client.enums.KeystoreType getSSLKeystoreType()

getSSLDistinguishedName

public java.lang.String getSSLDistinguishedName()

Get the secure socket layer (SSL) distinguished name.

setSSLDistinguishedName

public void setSSLDistinguishedName(java.lang.String dn)

setSSLCertificate

public void setSSLCertificate(java.lang.String keystore,
                              java.lang.String truststore,
                              COM.activesw.api.client.enums.KeystoreType keystore_type,
                              COM.activesw.api.client.enums.TruststoreType truststore_type,
                              java.lang.String password)
                       throws BrokerException

Parameters:

keystore -

truststore -

keystore_type -

truststore_type -

password -

Throws:

BrokerException

getSSLEncrypted

public boolean getSSLEncrypted()

Get the secure socket layer encryption flag.

setSSLEncrypted

public void setSSLEncrypted(boolean encrypted)

Set the secure socket layer encryption flag. This flag is set by default and indicates that if SSL is used, traffic on the connection should be encrypted. If the flag is set to false, then SSL handshaking for the client/server is used, but after that encryption is disabled. Note that this flag is ignored by non-SSL connections.

getAccessLabelHint

public java.lang.String getAccessLabelHint()

Get the access label hint.

setAccessLabelHint

public void setAccessLabelHint(java.lang.String hint)

Set the access label hint. null is a legal value.

getSSLEncryptionLevel

public static int getSSLEncryptionLevel()

Get the SSL encryption level that this library is capable of. See the ENCRYPT_LEVEL_* constants. Returns ENCRYPT_LEVEL_NO_ENCRYPTION if SSL is not supported.

getSSLCertificateDns

public static java.lang.String[] getSSLCertificateDns(java.lang.String certificate_file,
                                                      java.lang.String password)
                                               throws BrokerException

Get the list of distinguished names from a certificate file. This is for Spyrus cert

Throws:

BrokerFileNotFoundException - If the certificate file is not found or readable.

BrokerNoPermissionException - If the password is not valid or if the file is not a certificate file.

BrokerNullParameterException - If the cetificate_file or password are null.

BrokerSecurityException - If SSL support is not available.

BrokerException

getSSLCertificateDns

public static java.lang.String[] getSSLCertificateDns(java.lang.String certificate_file,
                                                      java.lang.String trust_file,
                                                      COM.activesw.api.client.enums.KeystoreType keystore_type,
                                                      COM.activesw.api.client.enums.TruststoreType truststore_type,
                                                      java.lang.String password)
                                               throws BrokerException

Get the list of distinguished names from a certificate file. This is for Entrust cert

Parameters:

certificate_file -

trust_file -

keystore_type -

truststore_type -

password -

Returns:

Throws:

BrokerException

getSSLRootDns

public static java.lang.String[] getSSLRootDns(java.lang.String keystore,
                                               java.lang.String truststore,
                                               COM.activesw.api.client.enums.KeystoreType keystore_type,
                                               COM.activesw.api.client.enums.TruststoreType truststore_type,
                                               java.lang.String password)
                                        throws BrokerException

Get the list of trusted root distinguished names from a certificate file.

Parameters:

keystore - keystore file

truststore - truststore file

keystore_type - keystore type

truststore_type - truststore type

password - password

Returns:

array of DNs

Throws:

BrokerException

getSSLCertificate

public static BrokerSSLCertificate getSSLCertificate(java.lang.String certificate_file,
                                                     java.lang.String password,
                                                     java.lang.String distinguished_name)
                                              throws BrokerException

Get the SSL certificate for a specific distinguished name from a certificate file. This is to read spyrus cert. If distinguished_name is USE_DEFAULT_DN, it gets the default certificate (if any)

Throws:

BrokerFileNotFoundException - If the certificate file is not found or readable.

BrokerNoPermissionException - If the password is not valid or if the file is not a certificate file.

BrokerNullParameterException - If the cetificate_file, password, or distinguished_name are null.

BrokerSecurityException - If SSL support is not available.

BrokerUnknownNameException - If a distinguished name is specified but does not exist in the certificate file.

BrokerException

getSSLCertificate

public static BrokerSSLCertificate getSSLCertificate(java.lang.String certificate_file,
                                                     java.lang.String trust_file,
                                                     COM.activesw.api.client.enums.KeystoreType keystore_type,
                                                     COM.activesw.api.client.enums.TruststoreType truststore_type,
                                                     java.lang.String password)
                                              throws BrokerException

Get the SSL certificate for a specific distinguished name from a certificate file. This is to read entrust cert.

Throws:

BrokerFileNotFoundException - If the certificate file is not found or readable.

BrokerNoPermissionException - If the password is not valid or if the file is not a certificate file.

BrokerNullParameterException - If the cetificate_file, password, or distinguished_name are null.

BrokerSecurityException - If SSL support is not available.

BrokerUnknownNameException - If a distinguished name is specified but does not exist in the certificate file.

BrokerException

toString

public java.lang.String toString()

Return a human-readable string with the descriptor's value.

Overrides:

toString in class java.lang.Object

getForcedReconnect

public boolean getForcedReconnect()

Get the forced_reconnect status of the descriptor.

setForcedReconnect

public void setForcedReconnect(boolean forced)

Set the forced reconnect status of the descriptor.

getRedeliveryCountEnabled

public boolean getRedeliveryCountEnabled()

Get the redelivery_count status of the descriptor.

setRedeliveryCountEnabled

public void setRedeliveryCountEnabled(boolean on)

Set the redelivery_count status of the descriptor.

getAutomaticRedeliveryCount

public boolean getAutomaticRedeliveryCount()

Get the redelivery_count_auto status of the descriptor.

setAutomaticRedeliveryCount

public void setAutomaticRedeliveryCount(boolean on)

Set the redelivery_count_auto status of the descriptor.

getKeepAlivePeriod

public int getKeepAlivePeriod()

Get the Keep Alive Period of the descriptor.

getMaxResponseTime

public int getMaxResponseTime()

Get the Max Response Time of the descriptor.

getKeepAliveRetryCount

public int getKeepAliveRetryCount()

Get the Keep Alive Retry Count of the descriptor.

getAckVolatile

public boolean getAckVolatile()

Internal use only.

setAckVolatile

public void setAckVolatile(boolean on)

Internal use only.

setKeepAlive

public void setKeepAlive(int KeepAlivePeriod,
                         int MaxResponseTime,
                         int RetryCount)
                  throws BrokerOutOfRangeException

Set the Keep Alive settings on the descriptor

Parameters:

KeepAlivePeriod - - valid range from 1 to Integer.MAX_VALUE

MaxResponseTime - - valid range from 1 to KeepAlivePeriod

RetryCount - - valid range from 1 to Integer.MAX_VALUE

Throws:

BrokerOutOfRangeException - If parameters do not fall within specified range

setLocale

public void setLocale(java.util.Locale locale)

Set the locale for this connection. Setting the locale to null will set the connection's locale to that of the Broker's.

Parameters:

locale - The locale for this connection.

getLocale

public java.util.Locale getLocale()

Get the locale for this connection.

Returns:

The connection's locale.

getClientStorage

public int getClientStorage()

Internal use only.

setClientStorage

public void setClientStorage(int s)

Internal use only.

getClientLifeCycle

public int getClientLifeCycle()

Internal use only.

setClientLifeCycle

public void setClientLifeCycle(int l)

Internal use only.

getPriorityOrdering

public boolean getPriorityOrdering()

Get the event priority ordering status of the descriptor.

setPriorityOrdering

public void setPriorityOrdering(boolean new_value)

Set the event priority ordering status of the descriptor.