Package COM.activesw.api.client

Class BrokerTransactionalClient

  • public class BrokerTransactionalClient
extends BrokerClient

    • Method Detail

      • reconnectTransactionalClient

        public static BrokerTransactionalClient reconnectTransactionalClient​(java.lang.String broker_host,
                                                                     java.lang.String broker_name,
                                                                     java.lang.String client_id,
                                                                     BrokerConnectionDescriptor desc)
                                                              throws BrokerException
        Reconnects a transactional client. 'broker_name' can be null to request the default broker. 'desc' can be null to request a default connection. The state sharing flag in the descriptor is ignored by this call. Whether or not the client shares state can only be set when making a new client. For normal clients, only one active connection can be made to the broker for a given client_id, so an error can be returned on reconnect if the client_id is already in use. For clients with shared state, multiple reconnects to the client_id can be made, but an error can be returned if the share limit is exceeded.
        Returns:
        a BrokerTransactionalClient
        Throws:
        BrokerClientContentionException - If the client ID is already in use by another client. For shared state clients, this means the maximum number of reconnects has been exceeded.
        BrokerCommFailureException - If problems occur establishing the connection.
        BrokerHostNotFoundException - If the specified host does not exist.
        BrokerNoPermissionException - If permission to join the specified client group is denied.
        BrokerNotRunningException - If the host exists but no broker is running on that host.
        BrokerNullParameterException - If broker_host or client_id are null.
        BrokerSecurityException - If a secure connection is attempted but is rejected by the broker.
        BrokerUnknownBrokerNameException - If the specified broker does not exist. If broker_name is null, this indicates that there is no default broker.
        BrokerUnknownClientIdException - If the specified client ID does not exist on the broker.
        BrokerException

      • reconnect

        public static BrokerClient reconnect​(java.lang.String broker_host,
                                     java.lang.String broker_name,
                                     java.lang.String client_id,
                                     BrokerConnectionDescriptor desc)
                              throws BrokerException
        Reconnects a client. 'broker_name' can be null to request the default broker. 'desc' can be null to request a default connection. The state sharing flag in the descriptor is ignored by this call. Whether or not the client shares state can only be set when making a new client. For normal clients, only one active connection can be made to the broker for a given client_id, so an error can be returned on reconnect if the client_id is already in use. For clients with shared state, multiple reconnects to the client_id can be made, but an error can be returned if the share limit is exceeded. The returned BrokerClient needs to be typecasted to work with transactions.
        Returns:
        a BrokerClient
        Throws:
        BrokerClientContentionException - If the client ID is already in use by another client. For shared state clients, this means the maximum number of reconnects has been exceeded.
        BrokerCommFailureException - If problems occur establishing the connection.
        BrokerHostNotFoundException - If the specified host does not exist.
        BrokerNoPermissionException - If permission to join the specified client group is denied.
        BrokerNotRunningException - If the host exists but no broker is running on that host.
        BrokerNullParameterException - If broker_host or client_id are null.
        BrokerSecurityException - If a secure connection is attempted but is rejected by the broker.
        BrokerUnknownBrokerNameException - If the specified broker does not exist. If broker_name is null, this indicates that there is no default broker.
        BrokerUnknownClientIdException - If the specified client ID does not exist on the broker.
        BrokerException

      • beginTransaction

        public long beginTransaction​(java.lang.String external_id)
                      throws BrokerException
        Starts a transaction. The operations done after this call will be performed after the commit method is called. If aborted, all the operations after this call will be ignored.
        Parameters:
        external_id - (optional) - A user defined, externally generated transaction identifier
        Throws:
        BrokerInvalidClientException
        BrokerException

      • beginTransaction

        public long beginTransaction​(java.lang.String external_id,
                             int flag,
                             int timeout)
                      throws BrokerException
        Starts a transaction. The operations done after this call will be performed after the commit method is called. If aborted, all the operations after this call will be ignored. This method is used for distributed transactions.
        Parameters:
        external_id - - A user defined, externally generated transaction identifier
        flag - - this will contain information if this is a new transction or joining an existing transaction.
        timeout -
        Throws:
        BrokerInvalidClientException
        BrokerException

      • endTransaction

        public void endTransaction​(java.lang.String external_id,
                           int end_state)
                    throws BrokerException
        Ends the current transaction. The transactional Broker client will no longer have a current transaction and new transactions may be started. This method can be used to indicate either success or failure. When called with BrokerTransactionalClient.TRANSACTION_END_ABORT the transaction can only be aborted. When called with BrokerTransactionalClient.TRANSACTION_END_COMMIT the transaction can be prepared, committed or aborted. Calling this method is optional. A transaction can be directly prepared, committed or aborted.
        Parameters:
        external_id - - A user defined, externally generated transaction identifier
        end_state - either BrokerTransactionalClient.TRANSACTION_END_ABORT or BrokerTransactionalClient.TRANSACTION_END_COMMIT
        Throws:
        BrokerException

      • endAll

        public static void endAll​(BrokerTransactionalClient[] tx_clients,
                          java.lang.String externalId,
                          int end_state)
                   throws BrokerException
        Ends the given list of current transactions. The transactional Broker clients will no longer have a current transaction and new transactions may be started. This method can be used to indicate either success or failure. When called with BrokerTransactionalClient.TX_STATE_FAILURE the transaction can only be aborted. When called with BrokerTransactionalClient.TX_STATE_SUCCESS the transaction can be prepared, committed or aborted. Calling this method is optional. A transaction can be directly prepared, committed or aborted.
        Parameters:
        tx_clients - the list of transactions to end
        end_state - either BrokerTransactionalClient.TX_STATE_SUCCESS or BrokerTransactionalClient.TX_STATE_FAILURE
        Throws:
        BrokerException

      • prepare

        public int prepare​(java.lang.String external_id)
            throws BrokerException
        Prepares the transactions with the specified external_id for commit. If prepare fails the transaction can only be aborted. Prepared transactions can be recovered by calling recover. Calling this method is optional. A transaction can be directly committed or aborted.
        Parameters:
        external_id - a user defined, externally generated transaction identifier
        Throws:
        BrokerException

      • prepare

        public int prepare​(long tx_id)
            throws BrokerException
        Prepares the transactions with the specified broker transaction id for commit. If prepare fails the transaction can only be aborted. Prepared transactions can be recovered by calling recover. Calling this method is optional. A transaction can be directly committed or aborted.
        Parameters:
        tx_id - The transaction identifier returned by the Broker during beginTransaction
        Throws:
        BrokerException

      • prepareAll

        public static void prepareAll​(BrokerTransactionalClient[] tx_clients,
                              java.lang.String external_id)
                       throws BrokerException
        Prepare the specified transaction for commit. If prepare fails the transaction can only be aborted. Prepared transactions can be recovered by calling recover. Calling this method is optional. A transaction can be directly committed or aborted.
        Parameters:
        external_id - a user defined, externally generated transaction identifier
        Throws:
        BrokerException

      • prepareAll

        public static void prepareAll​(BrokerTransactionalClient tx_client,
                              java.lang.String[] external_ids)
                       throws BrokerException
        Prepare the specified list of transactions for commit. If prepare fails the transaction can only be aborted. Prepared transactions can be recovered by calling recover. Calling this method is optional. A transaction can be directly committed or aborted.
        Parameters:
        tx_client - client that participated in the transaction and need to be prepared
        external_ids - list of external ids of open transactions that need to be prepared
        Throws:
        BrokerException

      • commit

        public void commit​(java.lang.String[] external_ids)
            throws BrokerException
        commits the open transaction(s) which has/have the specified external_id. All work performed on this context will be finalized. All the outstanding events in this clients queue will be acknowledged. commit() can be called before or after endTransaction or prepareTransaction. This method is typically invoked on recovered transactions for which a client has called prepare.
        Throws:
        BrokerTxClosedException
        BrokerInvalidClientException
        BrokerInvalidTxException
        BrokerException

      • commitAll

        public static void commitAll​(BrokerTransactionalClient[] tx_clients,
                             java.lang.String external_id)
                      throws BrokerException
        commits all the open transaction with the given external_id. All work performed in the transactions on the broker this client is connected to and which have a matching external_id will be finalized. All the outstanding events in these client's queues will be acknowledged. Used in distributed transactions.
        Parameters:
        tx_clients - - list of BrokerTransactionalClients
        external_id - a user defined, externally generated transaction identifier, a value must be supplied.
        Throws:
        BrokerTxClosedException
        BrokerInvalidClientException
        BrokerInvalidTxException
        BrokerException

      • abortAll

        public static void abortAll​(BrokerTransactionalClient[] tx_clients,
                            java.lang.String external_id)
                     throws BrokerException
        aborts all the transactions known to this broker with the given external_id Discarding all work previously performed, This method is used in distributed transactions. abort() can be called at any stage once the transaction has been started using beginTransaction. You can call abort() after endTransaction()or prepareTransaction(). Rollback the transaction.
        Parameters:
        tx_clients - - list of BrokerTransactionalClients
        external_id - a user defined, externally generated transaction identifier
        Throws:
        BrokerTxClosedException
        BrokerInvalidClientException
        BrokerInvalidTxException
        BrokerException

      • forget

        public void forget​(java.lang.String external_id)
            throws BrokerException
        Forget the specified heuristically completed transaction. The transaction will have timed out within the Broker transaction manager. This method is typically invoked on recovered transactions for which a client has called prepare.
        Parameters:
        external_id - a user defined, externally generated transaction identifier
        Throws:
        BrokerException

      • forget

        public void forget​(long tx_id)
            throws BrokerException
        Forget the specified heuristically completed transaction. The transaction will have timed out within the Broker transaction manager. This method is typically invoked on recovered transactions for which a client has called prepare. Used in case of distributed transactions.
        Parameters:
        tx_id - the Broker transaction context returned by beginTransaction
        Throws:
        BrokerException

      • forgetAll

        public static void forgetAll​(BrokerTransactionalClient[] tx_clients,
                             java.lang.String external_id)
                      throws BrokerException
        Forget the transaction with the specified external_id in the given list of transactional clients. The transaction will have timed out within the Broker transaction manager. This method is typically invoked on recovered transactions for which a client has called prepare. Used only in case of distributed transactions.
        Parameters:
        tx_clients - - list of BrokerTransactionalClients
        external_id - a user defined, externally generated transaction identifier
        Throws:
        BrokerException

      • forgetAll

        public static void forgetAll​(BrokerTransactionalClient tx_client,
                             java.lang.String[] external_ids)
                      throws BrokerException
        Forget the transaction with the specified external_id in the given list of transactional clients. The transaction will have timed out within the Broker transaction manager. This method is typically invoked on recovered transactions for which a client has called prepare. Used only in case of distributed transactions.
        Parameters:
        tx_client - - list of BrokerTransactionalClients
        external_ids - a user defined, externally generated transaction identifier
        Throws:
        BrokerException

      • setTransactionId

        public void setTransactionId​(long tx_id,
                             java.lang.String external_id)
                      throws BrokerException
        Associates a Broker transaction with an external identifier.
        Parameters:
        tx_id - a Broker transaction identifier
        external_id - a user defined, externally generated transaction identifier
        Throws:
        BrokerInvalidTxException - if the transaction is not found, the transaction is not open or if an external identifier already exists for the transaction.
        BrokerException - for all other errors.

      • setTransactionId

        public void setTransactionId​(java.lang.String external_id)
                      throws BrokerException
        Associates the current Broker transaction with an external identifier.
        Parameters:
        external_id - a user defined, externally generated transaction identifier
        Throws:
        BrokerInvalidTxException - if the transaction is not found, the transaction is not open or if an external identifier already exists for the transaction.
        BrokerException - for all other errors.

      • recover

        public java.lang.String[] recover​(int flags)
                           throws BrokerException
        Get the list of user defined, externally generated transaction identifiers that the client has prepared transactions for. Used only in case of distributed transactions.
        Returns:
        a list of user defined, externally generated transaction identifiers
        Throws:
        BrokerException

      • suspend

        public void suspend​(java.lang.String external_id)
             throws BrokerException
        Suspend the transaction with the given external_id. The transaction can be made active again by calling resume. Used in case of distributed transactions.
        Throws:
        BrokerException

      • suspend

        public void suspend​(long tx_id)
             throws BrokerException
        Suspend the transaction with the given external_id. he transaction can be made active again by calling resume. Used in case of distributed transactions.
        Throws:
        BrokerException

      • suspendAll

        public static void suspendAll​(BrokerTransactionalClient[] tx_clients,
                              java.lang.String external_id)
                       throws BrokerException
        Suspend the given list of current transactions. The transactions can be made active again by calling resume. Used only in case of distributed transactions.
        Parameters:
        tx_clients - the list of transactions to suspend
        Throws:
        BrokerException

      • resume

        public void resume​(java.lang.String external_id)
            throws BrokerException
        Resume a suspended transaction. Used only in case of distributed transactions.
        Parameters:
        external_id - the Broker transaction context returned by beginTransaction
        Throws:
        BrokerException

      • resume

        public void resume​(long tx_id)
            throws BrokerException
        Resume a suspended transaction. Used only in case of distributed transactions.
        Parameters:
        tx_id - the Broker transaction context returned by beginTransaction
        Throws:
        BrokerException

      • resumeAll

        public static void resumeAll​(BrokerTransactionalClient[] tx_clients,
                             java.lang.String external_id)
                      throws BrokerException
        Resume the given list of suspended transactions. Used only in case of distributed transactions.
        Parameters:
        external_id - a user defined, externally generated transaction identifier
        tx_clients - the list of transactions to resume
        Throws:
        BrokerException

      • getId

        public long getId​(java.lang.String external_id)

      • getId

        public long getId()
        used by the broker to identify the context. It is a globally unique identifier and remains constant for the life of the context.
        Returns:
        the unique identifier assigned by broker for this transaction

      • setId

        protected void setId​(long tx_id)
        used by the broker to identify the context. It is a globally unique identifier and remains constant for the life of the context.

      • getExternalId

        public java.lang.String getExternalId()
        Used by the application or an external manager to identify the context. It is a set when the context is created and remains constant for the life of the context. The external identifier is mandatory and does not have to be unique for distributed transactions and optional in case of local transactions, it need not be unique, and may be null .
        Returns:
        the external identifier

      • setXAResource

        protected void setXAResource​(BrokerXAResource bXAResource)

      • publish

        public void publish​(BrokerEvent event)
             throws BrokerException
        Publish one event with the given transaction id. The event is given to the broker to be given to all subscribing clients. In addition to the listed exceptions, any communications exception can be thrown.
        Overrides:
        publish in class BrokerClient
        Throws:
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerInvalidEventException - If the event does not match its type definition.
        BrokerNoPermissionException - If the client does not have permission to publish the event type.
        BrokerNullParameterException - If event is null.
        BrokerUnknownEventTypeException - If the event type for the event does not exist on the broker.
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerInvalidEventException - If the event does not match its type definition.
        BrokerNoPermissionException - If the client does not have permission to publish the event type.
        BrokerNullParameterException - If event is null.
        BrokerUnknownEventTypeException - If the event type for the event does not exist on the broker.
        BrokerException

      • publishWithAck

        public void publishWithAck​(BrokerEvent[] events,
                           int ack_type,
                           long[] ack_seqn)
                    throws BrokerException
        Publish multiple events for the given transaction. Gives an array of events to the broker to be given to subscribing clients. Either all of the events or none of them are published. In addition to the listed exceptions, any communications exception can be thrown.
        Overrides:
        publishWithAck in class BrokerClient
        Throws:
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerInvalidEventException - If any of the events does not match its type definition.
        BrokerNoPermissionException - If the client does not have permission to publish all of the event types.
        BrokerNullParameterException - If events is null, or if any element in the array is null.
        BrokerOutOfRangeException - If the ack_type is not a legal ACK_* value.
        BrokerUnknownEventTypeException - If the event type for any of the events does not exist on the broker.
        BrokerInvalidAcknowledgementException - If ack_seqn if not a valid event to acknowledge. Events are not published.
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerInvalidEventException - If any of the events does not match its type definition.
        BrokerNoPermissionException - If the client does not have permission to publish all of the event types.
        BrokerNullParameterException - If events is null, or if any element in the array is null.
        BrokerOutOfRangeException - If the ack_type is not a legal ACK_* value.
        BrokerUnknownEventTypeException - If the event type for any of the events does not exist on the broker.
        BrokerInvalidAcknowledgementException - If ack_seqn if not a valid event to acknowledge. Events are not published.
        BrokerException

      • deliver

        public void deliver​(java.lang.String dest_id,
                    BrokerEvent event)
             throws BrokerException
        Deliver one event in the given transaction. Gives an event to the broker to be given to the client with the given client ID. No exception is thrown if there is no client using the destination client ID. In addition to the listed exceptions, any communications exception can be thrown.
        Overrides:
        deliver in class BrokerClient
        Throws:
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerInvalidClientIdException - If the destination ID includes invalid characters.
        BrokerInvalidEventException - If the event does not match its type definition.
        BrokerNoPermissionException - If the client does not have permission to publish the event type.
        BrokerNullParameterException - If event or dest_id are null.
        BrokerUnknownEventTypeException - If the event type for the event does not exist on the broker.
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerInvalidClientIdException - If the destination ID includes invalid characters.
        BrokerInvalidEventException - If the event does not match its type definition.
        BrokerNoPermissionException - If the client does not have permission to publish the event type.
        BrokerNullParameterException - If event or dest_id are null.
        BrokerUnknownEventTypeException - If the event type for the event does not exist on the broker.
        BrokerException

      • deliver

        public void deliver​(java.lang.String dest_id,
                    BrokerEvent[] events)
             throws BrokerException
        Deliver multiple events on the given transaction. Gives an array of events to the broker to have them all delivered to the client with the given client ID. Either all of the events or none of them are delivered. No exception is thrown if there is no client using the destination client ID. In addition to the listed exceptions, any communications exception can be thrown.
        Overrides:
        deliver in class BrokerClient
        Throws:
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerInvalidClientIdException - If the destination ID includes invalid characters.
        BrokerInvalidEventException - If any of the events does not match its type definition.
        BrokerNoPermissionException - If the client does not have permission to publish all of the event types.
        BrokerNullParameterException - If dest_id or events are null, or if any element in the array is null.
        BrokerUnknownEventTypeException - If the event type for any of the events does not exist on the broker.
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerInvalidClientIdException - If the destination ID includes invalid characters.
        BrokerInvalidEventException - If any of the events does not match its type definition.
        BrokerNoPermissionException - If the client does not have permission to publish all of the event types.
        BrokerNullParameterException - If dest_id or events are null, or if any element in the array is null.
        BrokerUnknownEventTypeException - If the event type for any of the events does not exist on the broker.
        BrokerException

      • deliverWithAck

        public void deliverWithAck​(java.lang.String dest_id,
                           BrokerEvent[] events,
                           int ack_type,
                           long[] ack_seqn)
                    throws BrokerException
        Deliver multiple events on the given transaction. Gives an array of events to the broker to have them all delivered to the client with the given client ID. Either all of the events or none of them are delivered. No exception is thrown if there is no client using the destination client ID. In addition to the listed exceptions, any communications exception can be thrown.
        Overrides:
        deliverWithAck in class BrokerClient
        Throws:
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerInvalidClientIdException - If the destination ID includes invalid characters.
        BrokerInvalidEventException - If any of the events does not match its type definition.
        BrokerNoPermissionException - If the client does not have permission to publish all of the event types.
        BrokerNullParameterException - If dest_id or events are null, or if any element in the array is null.
        BrokerOutOfRangeException - If the ack_type is not a legal ACK_* value.
        BrokerUnknownEventTypeException - If the event type for any of the events does not exist on the broker.
        BrokerInvalidAcknowledgementException - If ack_seqn if not a valid event to acknowledge. Events are not published.
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerInvalidClientIdException - If the destination ID includes invalid characters.
        BrokerInvalidEventException - If any of the events does not match its type definition.
        BrokerNoPermissionException - If the client does not have permission to publish all of the event types.
        BrokerNullParameterException - If dest_id or events are null, or if any element in the array is null.
        BrokerOutOfRangeException - If the ack_type is not a legal ACK_* value.
        BrokerUnknownEventTypeException - If the event type for any of the events does not exist on the broker.
        BrokerInvalidAcknowledgementException - If ack_seqn if not a valid event to acknowledge. Events are not published.
        BrokerException

      • deliverAckReplyEvent

        public void deliverAckReplyEvent​(BrokerEvent request_event,
                                 long publish_seqn)
                          throws BrokerException
        Delivers an Adapter::ack event to the originator of the specified event, which is most likely a request event for given transaction. Properly sets the tag, trackId,businessContext and activation envelope fields to match that of the request. Properly uses the replyTo envelope field if set. Set publish_seqn to zero (0) when not using publish sequence numbers in your application. In addition to the listed exceptions, any communications exception can be thrown.
        Overrides:
        deliverAckReplyEvent in class BrokerClient
        Throws:
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerInvalidEventException - If the event was not received from the broker.
        BrokerNoPermissionException - If the client does not have permission to publish the Adapter::ack event type.
        BrokerNullParameterException - If request_event is null.
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerInvalidEventException - If the event was not received from the broker.
        BrokerNoPermissionException - If the client does not have permission to publish the Adapter::ack event type.
        BrokerNullParameterException - If request_event is null.
        BrokerException

      • deliverNullReplyEvent

        public void deliverNullReplyEvent​(BrokerEvent request_event,
                                  java.lang.String reply_event_type_name,
                                  long publish_seqn)
                           throws BrokerException
        Delivers a null event of type 'reply_event_type_name' to the originator of the specified event, which is most likely a request event for given transaction. Properly sets envelope tag, trackId, activation, businessContext, appSeqn, and appLastSeqn fields to indicate that this event is a null event. Properly uses the replyTo envelope field, if set. Null events are used to indicate that a request was successful and resulted in no data. Set publish_seqn to zero (0) when not using publish sequence numbers in your application. In addition to the listed exceptions, any communications exception can be thrown.
        Overrides:
        deliverNullReplyEvent in class BrokerClient
        Throws:
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerInvalidEventException - If the event was not received from the broker.
        BrokerNoPermissionException - If the client does not have permission to publish the reply event type.
        BrokerNullParameterException - If request_event or reply_event_type_name are null.
        BrokerUnknownEventTypeException - If the event type for the reply event does not exist on the broker.
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerInvalidEventException - If the event was not received from the broker.
        BrokerNoPermissionException - If the client does not have permission to publish the reply event type.
        BrokerNullParameterException - If request_event or reply_event_type_name are null.
        BrokerUnknownEventTypeException - If the event type for the reply event does not exist on the broker.
        BrokerException

      • deliverErrorReplyEvent

        public void deliverErrorReplyEvent​(BrokerEvent request_event,
                                   BrokerEvent error_event)
                            throws BrokerException
        Give a single error event to the broker to all be delivered to the client that published the 'request_event' for given transaction. No exception is thrown if there is no client using the destination clent ID. Properly sets the tag, trackId, activation, businessContext, appSeqn, and appLastSeqn envelope fields. Properly uses the errorsTo envelope field, if set. In addition to the listed exceptions, any communications exception can be thrown.
        Overrides:
        deliverErrorReplyEvent in class BrokerClient
        Throws:
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerInvalidEventException - If the request event was not received from the broker, or the reply event does not match its event type.
        BrokerNoPermissionException - If the client does not have permission to publish the reply event type.
        BrokerNullParameterException - If request_event or event are null.
        BrokerUnknownEventTypeException - If the event type for the reply event does not exist on the broker.
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerInvalidEventException - If the request event was not received from the broker, or the reply event does not match its event type.
        BrokerNoPermissionException - If the client does not have permission to publish the reply event type.
        BrokerNullParameterException - If request_event or event are null.
        BrokerUnknownEventTypeException - If the event type for the reply event does not exist on the broker.
        BrokerException

      • deliverReplyEvent

        public void deliverReplyEvent​(BrokerEvent request_event,
                              BrokerEvent event)
                       throws BrokerException
        Give a single event to the broker to all be delivered to the client that published the 'request_event' for the given transaction. No exception is thrown if there is no client using the destination clent ID. Properly sets the tag, trackId, activation, businessContext, appSeqn, and appLastSeqn envelope fields. Properly uses the replyTo envelope field, if set. In addition to the listed exceptions, any communications exception can be thrown.
        Overrides:
        deliverReplyEvent in class BrokerClient
        Throws:
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerInvalidEventException - If the request event was not received from the broker, or the reply event does not match its event type.
        BrokerNoPermissionException - If the client does not have permission to publish the reply event type.
        BrokerNullParameterException - If request_event or event are null.
        BrokerUnknownEventTypeException - If the event type for the reply event does not exist on the broker.
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerInvalidEventException - If the request event was not received from the broker, or the reply event does not match its event type.
        BrokerNoPermissionException - If the client does not have permission to publish the reply event type.
        BrokerNullParameterException - If request_event or event are null.
        BrokerUnknownEventTypeException - If the event type for the reply event does not exist on the broker.
        BrokerException

      • deliverReplyEvents

        public void deliverReplyEvents​(BrokerEvent request_event,
                               BrokerEvent[] events)
                        throws BrokerException
        Give multiple events to the broker to all be delivered to the client that published the 'request_event' for given transaction. No exception is thrown if there is no client using the destination client ID. Either all of the events or none of them are delivered. Properly sets the tag, trackId, activation, businessContext, appSeqn, and appLastSeqn envelope fields. Properly uses the replyTo envelope field, if set. In addition to the listed exceptions, any communications exception can be thrown.
        Overrides:
        deliverReplyEvents in class BrokerClient
        Throws:
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerInvalidEventException - If the request event was not received from the broker, or any of the reply events does not match its event type.
        BrokerNoPermissionException - If the client does not have permission to publish all of the reply events.
        BrokerNullParameterException - If request_event or events are null, or if any element in the events array is null.
        BrokerUnknownEventTypeException - If the event type for any of the reply events does not exist on the broker.
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerInvalidEventException - If the request event was not received from the broker, or any of the reply events does not match its event type.
        BrokerNoPermissionException - If the client does not have permission to publish all of the reply events.
        BrokerNullParameterException - If request_event or events are null, or if any element in the events array is null.
        BrokerUnknownEventTypeException - If the event type for any of the reply events does not exist on the broker.
        BrokerException

      • deliverPartialReplyEvents

        public int deliverPartialReplyEvents​(BrokerEvent request_event,
                                     BrokerEvent[] events,
                                     int flag,
                                     int token)
                              throws BrokerException
        Give multiple events to the broker to all be delivered to the client that published the 'request_event' for the given transaction. No exception is thrown if there is no client using the destination client ID. Either all of the events or none of them are delivered. Properly sets the tag, trackId, activation, businessContext, appSeqn, and appLastSeqn envelope fields. Properly uses the replyTo envelope field, if set. This function is used to deliver parts of a set of replies in groups. When called the first time, 'flag' should be REPLY_FLAG_START. After doing this, additional calls can be made with other flag values. During intermediate replies, 'flag' should be REPLY_FLAG_CONTINUE. On the final call, 'flag' should be REPLY_FLAG_END. Calling this function with 'flag' as REPLY_FLAG_START_AND_END allows the entire result to be passed to this function in one call. The 'token' parameter is ignored on REPLY_FLAG_START and REPLY_FLAG_START_AND_END. On other calls, the return value from the previous call should be passed. The return value exists to carry information between calls and has no meaning to the caller. In addition to the listed exceptions, any communications exception can be thrown.
        Overrides:
        deliverPartialReplyEvents in class BrokerClient
        Throws:
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerInvalidEventException - If the request event was not received from the broker, or any of the reply events does not match its event type.
        BrokerNoPermissionException - If the client does not have permission to publish all of the reply events.
        BrokerNullParameterException - If request_event or events are null, or if any element in the events array is null.
        BrokerOutOfRangeException - If flag is not a valid value.
        BrokerUnknownEventTypeException - If the event type for any of the reply events does not exist on the broker.
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerInvalidEventException - If the request event was not received from the broker, or any of the reply events does not match its event type.
        BrokerNoPermissionException - If the client does not have permission to publish all of the reply events.
        BrokerNullParameterException - If request_event or events are null, or if any element in the events array is null.
        BrokerOutOfRangeException - If flag is not a valid value.
        BrokerUnknownEventTypeException - If the event type for any of the reply events does not exist on the broker.
        BrokerException

      • getEvent

        public BrokerEvent getEvent​(int msecs)
                     throws BrokerException
        Gets a single event from this client's queue, that is part of the given open transaction context. Blocks for a given number of milliseconds then gives up. If 'msecs' is TIME_INFINITE (-1), it waits forever. Acknowledges all events which have been retrieved previously that were not explicitly acknowledged.

        Caution should be used when calling this method simultaneously from the same client on multiple threads. An event received on one thread may be acknowledged by another thread. To insure proper acknowledgement handling getEvents(int, long, int) should be used in this situation.

        In addition to the listed exceptions, any communications exception can be thrown.

        Overrides:
        getEvent in class BrokerClient
        Throws:
        BrokerInterruptedException - If interruptGetEvents is used to stop the call.
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerOutOfRangeException - If msecs is less than -1.
        BrokerTimeoutException - If the timeout is reached before an event arrives.
        BrokerInterruptedException - If interruptGetEvents is used to stop the call.
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerOutOfRangeException - If msecs is less than -1.
        BrokerTimeoutException - If the timeout is reached before an event arrives.
        BrokerException

      • getEvents

        public BrokerEvent[] getEvents​(int max_events,
                               int msecs)
                        throws BrokerException
        Gets one or more events from this client's queue, that is a part of the the give open transaction context. Blocks for a given number of milliseconds then gives up. If 'msecs' is TIME_INFINITE (-1), it waits forever. Acknowledges all events which have been retrieved previously that were not explicitly acknowledged.

        Caution should be used when calling this method simultaneously from the same client on multiple threads. An event received on one thread may be acknowledged by another thread. To insure proper acknowledgement handling BrokerClient.getEvents(int, long, int) should be used in this situation.

        The number of events being returned is not guaranteed to be 'max_events' even if there are more than than many events in the client's queue. Any number of events up to the value of 'max_events' may be returned. In addition to the listed exceptions, any communications exception can be thrown.

        Overrides:
        getEvents in class BrokerClient
        Throws:
        BrokerInterruptedException - If interruptGetEvents is used to stop the call.
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerOutOfRangeException - If msecs is less than -1, or max_events is less than zero.
        BrokerTimeoutException - If the timeout is reached before any events arrive.
        BrokerInterruptedException - If interruptGetEvents is used to stop the call.
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerOutOfRangeException - If msecs is less than -1, or max_events is less than zero.
        BrokerTimeoutException - If the timeout is reached before any events arrive.
        BrokerException

      • getEvents

        public BrokerEvent[] getEvents​(int max_events,
                               long seqn,
                               int msecs)
                        throws BrokerException
        This request gets processed only after the BrokerTransactionalClient is is committed. If the given transaction is aborted this request will not be processed. The sequence number is the event to acknowledge through. A value of zero acknowledges all events. A value of DO_NOT_ACK (-1) will not acknowledge any events. Gets one or more events from this client's queue. Blocks for a given number of milliseconds then gives up. If 'msecs' is TIME_INFINITE (-1), it waits forever. Acknowledges all events up through the specified sequence number. If seqn is 0, then it acknowledges all events which have been retrieved previously that were not explicitly acknowledged. If seqn is DO_NOT_ACK (-1), then no events are acknowledged.

        Caution should be used when calling this method simultaneously from the same client on multiple threads when seqn is 0. An event received on one thread may be acknowledged by another thread.

        The number of events being returned is not guaranteed to be 'max_events' even if there are more than than many events in the client's queue. Any number of events up to the value of 'max_events' may be returned. In addition to the listed exceptions, any communications exception can be thrown.

        Overrides:
        getEvents in class BrokerClient
        Throws:
        BrokerInterruptedException - If interruptGetEvents is used to stop the call.
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerOutOfRangeException - If msecs is less than -1, or max_events is less than zero.
        BrokerTimeoutException - If the timeout is reached before any events arrive.
        BrokerInterruptedException - If interruptGetEvents is used to stop the call.
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerOutOfRangeException - If msecs is less than -1, or max_events is less than zero, or seqn is less than -1.
        BrokerTimeoutException - If the timeout is reached before any events arrive.
        BrokerException

      • getJMSEvents

        public BrokerJMSEvent[] getJMSEvents​(int max_events,
                                     long seqn,
                                     int msecs)
                              throws BrokerException
        This request gets processed only after the BrokerTransactionalClient is is committed. If the given transaction is aborted this request will not be processed. The sequence number is the event to acknowledge through. A value of zero acknowledges all events. A value of DO_NOT_ACK (-1) will not acknowledge any events. Gets one or more events from this client's queue. Blocks for a given number of milliseconds then gives up. If 'msecs' is TIME_INFINITE (-1), it waits forever. Acknowledges all events up through the specified sequence number. If seqn is 0, then it acknowledges all events which have been retrieved previously that were not explicitly acknowledged. If seqn is DO_NOT_ACK (-1), then no events are acknowledged. The number of events being returned is not guaranteed to be 'max_events' even if there are more than than many events in the client's queue. Any number of events up to the value of 'max_events' may be returned. In addition to the listed exceptions, any communications exception can be thrown.
        Overrides:
        getJMSEvents in class BrokerClient
        Throws:
        BrokerInterruptedException - If interruptGetEvents is used to stop the call.
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerOutOfRangeException - If msecs is less than -1, or max_events is less than zero, or seqn is less than -1.
        BrokerTimeoutException - If the timeout is reached before any events arrive.
        BrokerException

      • publishRequestAndWait

        public BrokerEvent[] publishRequestAndWait​(BrokerEvent event,
                                           int msecs)
                                    throws BrokerException
        Description copied from class: BrokerClient
        Publish one request event to the broker and wait for replies. Creates a value for the 'tag' envelope field using makeTag(). Blocks until the replies are received or until the requested timeout (TIME_INFINITE (-1) for infinite timeout) is reached. In addition to the listed exceptions, any communications exception can be thrown.

        Note: This operation is intended for use only for clients which are using the callback model. It does not work properly for clients which are using the getEvents model. It also only works properly when responses will be returned from only one client due to the request.

        Overrides:
        publishRequestAndWait in class BrokerClient
        Throws:
        BrokerBadStateException - If this is called from within a callback function.
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerInvalidEventException - If the event does not match its type definition.
        BrokerNoPermissionException - If the client does not have permission to publish the event type.
        BrokerNullParameterException - If event is null.
        BrokerUnknownEventTypeException - If the event type for the event does not exist on the broker.
        BrokerException

      • deliverRequestAndWait

        public BrokerEvent[] deliverRequestAndWait​(java.lang.String dest_id,
                                           BrokerEvent event,
                                           int msecs)
                                    throws BrokerException
        Description copied from class: BrokerClient
        Deliver one request event and wait for replies. No exception is thrown if there is no client using the destination client ID. Creates a value for the 'tag' envelope field using makeTag(). Blocks until the replies are received or until the requested timeout (TIME_INFINITE (-1) for infinite timeout) is reached. In addition to the listed exceptions, any communications exception can be thrown.

        Note: This operation is intended for use only for clients which are using the callback model. It does not work properly for clients which are using the getEvents model. It also only works properly when responses will be returned from only one client due to the request.

        Overrides:
        deliverRequestAndWait in class BrokerClient
        Throws:
        BrokerBadStateException - If this is called from within a callback function.
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerInvalidClientIdException - If the destination ID includes invalid characters.
        BrokerInvalidEventException - If the event does not match its type definition.
        BrokerNoPermissionException - If the client does not have permission to publish the event type.
        BrokerNullParameterException - If dest_id or event are null.
        BrokerUnknownEventTypeException - If the event type for the event does not exist on the broker.
        BrokerException

      • registerCallback

        public void registerCallback​(BrokerCallback obj,
                             java.lang.Object client_data)
                      throws BrokerException
        Description copied from class: BrokerClient
        Register a general callback for events received by this client. Calling this on a client which already has an existing general callback will replace that callback. 'client_data' may be null.
        The callback method will be called once if an event arrives which does not match a Tag callback, which has at least one subscription ID which does not match a SubId callback, or which is delivered to the application.
        Use dispatch, mainLoop, or threadedCallbacks to make use of callbacks.
        Overrides:
        registerCallback in class BrokerClient
        Throws:
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerNullParameterException - If obj is null.
        BrokerException

      • registerCallbackForSubId

        public void registerCallbackForSubId​(int sub_id,
                                     BrokerCallback obj,
                                     java.lang.Object client_data)
                              throws BrokerException
        Description copied from class: BrokerClient
        Register a specific callback for events received by this client which matched a given subscription ID. Calling this on a client which already has an existing callback for the subscription ID will replace that callback. 'client_data' may be null.
        Before calling this function, you must use registerCallback to register a general callback.
        When using this call, it is suggested that each subscription be given a unique subscription ID.
        The callback method will be called once if an event arrives which matched the specified subscription ID. It will be called more than once if the event matches the same subscription ID more than once. Note that it will never be called for events delivered to the client.
        Overrides:
        registerCallbackForSubId in class BrokerClient
        Throws:
        BrokerBadStateException - If no general callback has been registered.
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerNullParameterException - If obj is null.
        BrokerOutOfRangeException - If sub_id is less than zero.
        BrokerException

      • registerCallbackForTag

        public void registerCallbackForTag​(int tag,
                                   boolean cancel_when_done,
                                   BrokerCallback obj,
                                   java.lang.Object client_data)
                            throws BrokerException
        Description copied from class: BrokerClient
        Register a specific callback for events received by this client which have the _env.tag field set to the specified value. Calling this on a client which already has an existing callback for the tag value will replace that callback. 'client_data' may be null.
        If 'cancel_when_done' is true, then the callback will be automatically cancelled when isLastReplyEvent returns true. Otherwise, the callback will stay in effect until explicitly cancelled.
        Before calling this function, you must use registerCallback to register a general callback.
        The callback method will be called once if an event arrives which matches the specified tag value. Note that this is usually true only for events delivered to the client.
        Overrides:
        registerCallbackForTag in class BrokerClient
        Throws:
        BrokerBadStateException - If no general callback has been registered.
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerNullParameterException - If obj is null.
        BrokerException

      • acknowledge

        public void acknowledge​(long seqn)
                 throws BrokerException
        Acknowledge the single event specified. A value of zero acknowledges all outstanding events. In addition to the listed exceptions, any communications exception can be thrown.
        Overrides:
        acknowledge in class BrokerClient
        Throws:
        BrokerInvalidAcknowledgementException - If seqn is not a valid event to acknowledge.
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerOutOfRangeException - If seqn is less than zero.
        BrokerInvalidAcknowledgementException - If seqn is not a valid event to acknowledge.
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerOutOfRangeException - If seqn is less than zero.
        BrokerException

      • acknowledge

        public void acknowledge​(long[] seqns)
                 throws BrokerException
        Acknowledge the array of events with the given seqn numbers. A value of zero acknowledges all outstanding events. In addition to the listed exceptions, any communications exception can be thrown.
        Overrides:
        acknowledge in class BrokerClient
        Throws:
        BrokerInvalidAcknowledgementException - If seqn is not a valid event to acknowledge.
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerOutOfRangeException - If seqn is less than zero.
        BrokerInvalidAcknowledgementException - If seqn is not a valid event to acknowledge.
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerOutOfRangeException - If seqn is less than zero.
        BrokerException

      • acknowledgeThrough

        public void acknowledgeThrough​(long seqn)
                        throws BrokerException
        Acknowledges all events through the event specified. A value of zero acknowledges all outstanding events. In addition to the listed exceptions, any communications exception can be thrown.
        Overrides:
        acknowledgeThrough in class BrokerClient
        Throws:
        BrokerInvalidAcknowledgementException - If seqn is not a valid event to acknowledge.
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerOutOfRangeException - If seqn is less than zero.
        BrokerInvalidAcknowledgementException - If seqn is not a valid event to acknowledge.
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerOutOfRangeException - If seqn is less than zero.
        BrokerException

      • negativeAcknowledge

        public void negativeAcknowledge​(long seqn)
                         throws BrokerException
        Negatively acknowledge the single event specified. A value of zero acknowledges all outstanding events. In addition to the listed exceptions, any communications exception can be thrown.
        Overrides:
        negativeAcknowledge in class BrokerClient
        Throws:
        BrokerInvalidAcknowledgementException - If seqn is not a valid event to acknowledge.
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerOutOfRangeException - If seqn is less than zero.
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerOutOfRangeException - If you have a negative seqn#
        BrokerInvalidOperationException - If you try to manually increment redelivery counts for a client that has automatic increments
        BrokerInvalidSequenceNumberException - If you supply a sequence number that does not correspond to a received event.
        BrokerException

      • negativeAcknowledge

        public void negativeAcknowledge​(long[] seqns)
                         throws BrokerException
        Negative acknowledge the array of events with the given seqn numbers. In addition to the listed exceptions, any communications exception can be thrown.
        Overrides:
        negativeAcknowledge in class BrokerClient
        Throws:
        BrokerInvalidAcknowledgementException - If seqn is not a valid event to acknowledge.
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerOutOfRangeException - If seqn is less than zero.
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerOutOfRangeException - If you have a negative seqn#
        BrokerInvalidOperationException - If you try to manually increment redelivery counts for a client that has automatic increments
        BrokerInvalidSequenceNumberException - If you supply a sequence number that does not correspond to a received event.
        BrokerException

      • prime

        public void prime​(int num)
           throws BrokerException
        Tell the client to send a request for events but not block. Use this method on clients which have no callbacks and for which you intend to use isClientPending() to determine if events are waiting prior to calling getEvent(). If the requested number of events is less than one the number of events will default to one. In addition to the listed exceptions, any communications exception can be thrown.
        Overrides:
        prime in class BrokerClient
        Parameters:
        num - The requested number of events.
        Throws:
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerException