Package COM.activesw.api.client

Class 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).

    • 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.

    • Method Detail

      • 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 TruststoreType getSSLTruststoreType()
        Returns the truststore type set on the connection descriptor.
        Returns:
        TruststoreType The Truststore type. The possible value is JKS.

      • getSSLKeystoreType

        public KeystoreType getSSLKeystoreType()
        Returns the keystore type set on the connection descriptor.
        Returns:
        KeystoreType The Keystore type. The possible value is PKCS12.

      • 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,
                              KeystoreType keystore_type,
                              TruststoreType truststore_type,
                              java.lang.String password)
                       throws BrokerException
        Parameters:
        keystore -
        truststore -
        keystore_type - KeystoreType. The possible value is PKCS12.
        truststore_type - TruststoreType. The possible value is JKS.
        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 trust_file,
                                                      KeystoreType keystore_type,
                                                      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 - KeystoreType. The possible value is PKCS12.
        truststore_type - TruststoreType. The possible value is JKS.
        password -
        Throws:
        BrokerException

      • getSSLRootDns

        public static java.lang.String[] getSSLRootDns​(java.lang.String keystore,
                                               java.lang.String truststore,
                                               KeystoreType keystore_type,
                                               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 - KeystoreType. The possible value is PKCS12.
        truststore_type - TruststoreType. The possible value is JKS.
        password - password
        Returns:
        array of DNs
        Throws:
        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.

      • setAuthInfo

        public void setAuthInfo​(java.lang.String username,
                        java.lang.String password)
        Set the authentication user name and password of the descriptor
        Parameters:
        username - Specifies the basic authentication user name
        password - Specifies the basic authentication password

      • getAuthUserName

        public java.lang.String getAuthUserName()
        Get the authentication user name of the descriptor

      • getSocketTcpNoDelay

        public boolean getSocketTcpNoDelay()
        Get the socket setting of Nagle's algorithm.
        Returns:
        true if Nagle's algorithm is disabled
        See Also:
        setSocketTcpNoDelay(boolean)

      • setSocketTcpNoDelay

        public void setSocketTcpNoDelay​(boolean socketTcpNoDelay)
        Enable or disable the Nagle's algorithm on the socket.
        Parameters:
        socketTcpNoDelay - true to disable Nagle's algorithm
        See Also:
        getSocketTcpNoDelay()

      • getSSLCipherSuites

        public java.lang.String getSSLCipherSuites()

      • setSSLCipherSuites

        public void setSSLCipherSuites​(java.lang.String ssl_cipher_suites)

      • getSSLProvider

        public java.lang.String getSSLProvider()

      • setSSLProvider

        public void setSSLProvider​(java.lang.String ssl_provider)

      • setSocketConnectTimeout

        public void setSocketConnectTimeout​(int socketConnectTimeout)
        Set the socket connect timeout.
        Parameters:
        socketConnectTimeout - the socket connect timeout in seconds
        See Also:
        SOCKET_CONNECT_TIMEOUT, getSocketConnectTimeout()

      • setSocketLinger

        public void setSocketLinger​(boolean socketLinger)
        Set the socket linger state.
        Parameters:
        socketLinger - true to enable socket linger
        See Also:
        SOCKET_LINGER, getSocketLinger()

      • setSocketLingerTimeout

        public void setSocketLingerTimeout​(int socketLingerTimeout)
        Set the socket linger timeout.
        Parameters:
        socketLingerTimeout - the socket linger timeout
        See Also:
        SOCKET_LINGER_TIMEOUT, getSocketLingerTimeout()

      • setSocketSendBufferSize

        public void setSocketSendBufferSize​(int socketSendBufferSize)
        Set the outbound socket buffer size.
        Parameters:
        socketSendBufferSize - the outbound socket buffer size
        See Also:
        SOCKET_SEND_BUFFER_SIZE, getSocketSendBufferSize()

      • setSocketRecvBufferSize

        public void setSocketRecvBufferSize​(int socketRecvBufferSize)
        Set the inbound socket buffer size.
        Parameters:
        socketRecvBufferSize - the inbound socket buffer size
        See Also:
        SOCKET_RECV_BUFFER_SIZE, getSocketRecvBufferSize()

      • getSocketKeepAliveEnabled

        public boolean getSocketKeepAliveEnabled()

      • setSocketKeepAliveEnabled

        public void setSocketKeepAliveEnabled​(boolean enabled)