Package COM.activesw.api.client

Class BrokerClient

    • Method Detail

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

      • getBrokerHost

        public java.lang.String getBrokerHost()
        Get the client's broker host name.

      • getBrokerPort

        public int getBrokerPort()
        Get the client's broker host port.

      • getTerritoryName

        public java.lang.String getTerritoryName()
                                  throws BrokerException
        Get the territory name of the client's broker. Any communications exception can be thrown. Returns null if the client is not in a territory.
        Throws:
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerException

      • getBrokerName

        public java.lang.String getBrokerName()
                               throws BrokerException
        Get the client's broker name. Any communications exception can be thrown if the default broker was used in creating the client.
        Throws:
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerException

      • getClientGroup

        public java.lang.String getClientGroup()
        Get the client's client group name.

      • getClientId

        public java.lang.String getClientId()
        Get the client's identifier.

      • getApplicationName

        public java.lang.String getApplicationName()
        Get the client's application name.

      • getBrokerVersionNumber

        public int getBrokerVersionNumber()
        Get the broker's version number. Returns one of the VERSION_* contant values.

        If the broker is newer than the client's version, the client's version is reported.

      • getBrokerVersionString

        public java.lang.String getBrokerVersionString()
        Get the broker's version string.

        If the broker is newer than the client's version, the client's version is reported.

      • getApiVersionNumber

        public java.lang.String getApiVersionNumber()
        Get the current api's version number. Returns the CURRENT_API_VERSION's contant values.

      • getConnectionDescriptor

        public BrokerConnectionDescriptor getConnectionDescriptor()
        Get the client's connection descriptor as used when this object was created. If null was passed to the descriptor argument, then a descriptor which matches the default behavior is returned.

      • destroy

        public void destroy()
             throws BrokerException
        Destroy the client. Removes the client from the broker. May throw any communications exception, but the local client object is marked as disconnected even if an exception is thrown.
        Throws:
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerException

      • disconnect

        public void disconnect()
                throws BrokerException
        Disconnect the client. Deletes the local client object, but leaves the client state on the broker for future reconnects. Note that destroy-on-disconnect clients will destroy themselves when disconnect happens, so disconnect is identical to destroy in behavior for such clients. May throw any communications exception, but the local client object is marked as disconnected even if an exception is thrown.
        Throws:
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerException

      • finalize

        protected void finalize()
        Called by Java when you stop using this object. Performs a disconnect(). Do not rely upon this method to disconnect your clients.
        Overrides:
        finalize in class java.lang.Object

      • ping

        public void ping()
          throws BrokerException
        Checks for network connectivity to the Broker using the default client timeout. In addition to the listed exceptions, any communications exception can be thrown.
        Throws:
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerException

      • ping

        public void ping​(int msecs)
          throws BrokerException
        Checks for network connectivity to the Broker. If 'msecs' is TIME_INFINITE (-1), it waits forever. In addition to the listed exceptions, any communications exception can be thrown.
        Parameters:
        msecs - The amount of time, in milliseconds, to wait for a response from the Broker.
        Throws:
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerOutOfRangeException - If msecs is less than -1.
        BrokerException

      • isConnected

        public boolean isConnected()
        Check if connected. This is a passive check, meaning it only tells if the client has been explicitly destryed or disconnected, or if an error occurred on a previous call which indicated that the connection was closed. No active test of the connection is made. Returns true if the client is valid and is still connected, or false if not.

      • toString

        public java.lang.String toString()
        Returns a string with the client information in a form suitable for human viewing.
        Overrides:
        toString in class java.lang.Object

      • publishRequestAndWait

        public BrokerEvent[] publishRequestAndWait​(BrokerEvent event,
                                           int msecs)
                                    throws BrokerException
        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.

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

        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

      • 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. Properly sets the tag, trackId, activation and businessContext 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.
        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.
        BrokerException

      • deliverAckReplyEvent

        protected void deliverAckReplyEvent​(BrokerEvent request_event,
                                    long publish_seqn,
                                    BrokerTransactionalClient tx_client)
                             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.
        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.
        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. 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.
        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.
        BrokerException

      • deliverNullReplyEvent

        protected void deliverNullReplyEvent​(BrokerEvent request_event,
                                     java.lang.String reply_event_type_name,
                                     long publish_seqn,
                                     BrokerTransactionalClient tx_client)
                              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.
        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.
        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'. 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.
        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.
        BrokerException

      • deliverErrorReplyEvent

        protected void deliverErrorReplyEvent​(BrokerEvent request_event,
                                      BrokerEvent error_event,
                                      BrokerTransactionalClient tx_client)
                               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.
        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.
        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'. 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.
        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.
        BrokerException

      • deliverReplyEvent

        protected void deliverReplyEvent​(BrokerEvent request_event,
                                 BrokerEvent event,
                                 BrokerTransactionalClient tx_client)
                          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.
        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.
        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'. 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.
        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.
        BrokerException

      • deliverReplyEvents

        public void deliverReplyEvents​(BrokerEvent request_event,
                               BrokerEvent[] events,
                               BrokerTransactionalClient tx_client)
                        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.
        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.
        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'. 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.
        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.
        BrokerException

      • deliverPartialReplyEvents

        protected int deliverPartialReplyEvents​(BrokerEvent request_event,
                                        BrokerEvent[] events,
                                        int flag,
                                        int token,
                                        BrokerTransactionalClient tx_client)
                                 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.
        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.
        BrokerException

      • beginAdapterTransaction

        public int beginAdapterTransaction​(java.lang.String transaction_id,
                                   int required_level,
                                   java.lang.String[] participants,
                                   boolean want_ack)
                            throws BrokerException
        Publishes an Adapter::beginTransaction event for the given transaction ID. After sending this event, the application can send any number of additional events with the "_env.transactionId" field set to the specified transaction ID. When it is done, it should use the endTransaction() method to close the transaction. required_level should be set to one of the TRANSACTION_LEVEL_* values. If set to something other than TRANSACTION_LEVEL_ANY, adapters which do not support the required level should generate an error on the first event they receive from this transaction. participants can be null. If any participants are specified, then only those clients should interact with the request events. These are usually adapter names. If want_ack is false, this function returns 0. Otherwise, it returns the value of the tag used in the beginTransaction event. In addition to the listed exceptions, any communications exception can be thrown.
        Throws:
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerNoPermissionException - If the client does not have permission to publish the Adapter::beginTransaction event type.
        BrokerNullParameterException - If transaction_id is null, or if any entry in participants is null.
        BrokerException

      • endAdapterTransaction

        public int endAdapterTransaction​(java.lang.String transaction_id,
                                 int mode,
                                 boolean want_ack)
                          throws BrokerException
        Publishes an Adapter::endTransaction event for the given transaction ID. The mode should be one of the TRANSACTION_MODE_* values. This method should be used in conjunction with the beginAdapterTransaction() method. If want_ack is false, this function returns 0. Otherwise, a new tag is generated, used in the Adapter::endTransaction event and returned by this function. In addition to the listed exceptions, any communications exception can be thrown.
        Throws:
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerNoPermissionException - If the client does not have permission to publish the Adapter::endTransaction event type.
        BrokerNullParameterException - If transaction_id is null.
        BrokerOutOfRangeException - If mode is not a legal value.
        BrokerException

      • getLastPublishSequenceNumber

        public long getLastPublishSequenceNumber()
                                  throws BrokerException
        Get the highest sequence number used by this client in a publish or deliver call. In addition to the listed exceptions, any communications exception can be thrown.
        Throws:
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerException

      • newSubscription

        public void newSubscription​(java.lang.String event_type_name,
                            java.lang.String filter)
                     throws BrokerException
        Subscribe to all events of a given event type which match the specified filter. The subscription id defaults to zero. 'null' can be passed to the filter parameter if you do not wish to filter the events. If a subscription with the same name and filter already exists on the broker, the new subscription request is ignored. You can use doesSubscriptionExist() to test for existing subscriptions. In addition to the listed exceptions, any communications exception can be thrown.
        Throws:
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerInvalidSubscriptionException - If the filter string contains a parse error.
        BrokerNoPermissionException - If the client does not have permission to subscribe to the event type.
        BrokerNullParameterException - If event_type_name is null.
        BrokerUnknownEventTypeException - If the event type does not exist on the broker.
        BrokerException

      • newSubscription

        public void newSubscription​(int sub_id,
                            java.lang.String event_type_name,
                            java.lang.String filter)
                     throws BrokerException
        Subscribe to all events of a given event type which match the specified filter. 'null' can be passed to the filter parameter if you do not wish to filter the events. If a subscription with the same name and filter already exists on the broker, the new subscription request is ignored. You can use doesSubscriptionExist() to test for existing subscriptions. In addition to the listed exceptions, any communications exception can be thrown.
        Throws:
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerInvalidSubscriptionException - If the filter string contains a parse error.
        BrokerNoPermissionException - If the client does not have permission to subscribe to the event type.
        BrokerNullParameterException - If event_type_name is null.
        BrokerOutOfRangeException - If sub_id is less than zero.
        BrokerUnknownEventTypeException - If the event type does not exist on the broker.
        BrokerException

      • newSubscriptions

        public void newSubscriptions​(BrokerSubscription[] subs)
                      throws BrokerException
        Open multiple subscriptions at one time. If a subscription with the same name and filter already exists on the broker, the new subscription request is ignored. You can use doesSubscriptionExist() to test for existing subscriptions. In addition to the listed exceptions, any communications exception can be thrown. NOTE that as many subscriptions as possible are created, so even when an error occurs, some subscriptions may have been created.
        Throws:
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerInvalidSubscriptionException - If any filter string contains a parse error.
        BrokerNoPermissionException - If the client does not have permission to subscribe to all the event types.
        BrokerNullParameterException - If subs is null, or if any of the subscription event_type_name fields are null.
        BrokerOutOfRangeException - If any of the subscription's sub_id fields are less than zero.
        BrokerUnknownEventTypeException - If any of the event types do not exist on the broker.
        BrokerException

      • cancelSubscriptions

        public void cancelSubscriptions​(BrokerSubscription[] subs)
                         throws BrokerException
        Cancel multiple subscriptions with matching event types and filters. The sub_id field of the subscription objects is ignored. Only the event type name and filter are used to find matching subscriptions. NOTE that as many subscriptions are cancelled as possible, so even when an exception occurs, some subscriptions may have been cancelled. In addition to the listed exceptions, any communications exception can be thrown.
        Throws:
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerInvalidSubscriptionException - If there is no existing subscription that matches one or more of the subscriptions.
        BrokerNullParameterException - If subs is null, if any array element is null, or if any array element's event_type_name field is null.
        BrokerException

      • doesSubscriptionExist

        public boolean doesSubscriptionExist​(java.lang.String event_type_name,
                                     java.lang.String filter)
                              throws BrokerException
        Checks to see if the given subscription exists. The filter can be null. In addition to the listed exceptions, any communications exception can be thrown.
        Throws:
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerException

      • makeSubId

        public int makeSubId()
        Generates a subscription id. This is only unique for subscriptions generated for this client during this execution. Use this for destroy-on-disconnect clients or explicit-destroy ones which do not already have open subscriptions.

      • makeUniqueSubId

        public int makeUniqueSubId()
                    throws BrokerException
        Generates a unique subscription id. This call first queries the broker for any open subscriptions, and then makes an ID that is unique. Use this for explicit-destroy clients which may have opened subscriptions previously. After calling this once, you may use makeSubId because this function initializes the setup for that function. In addition to the listed exceptions, any communications exception can be thrown.
        Throws:
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerException

      • makeTag

        public int makeTag()
        Generate a unique value for use in the 'tag' envelope field. This field in used in request events to identify replies.

      • makeTransactionId

        public java.lang.String makeTransactionId()
                                   throws BrokerException
        Generate a unique transaction ID for use in transaction operations. Transaction IDs are formatted like "clientId:UniqueNumber:CountNumber". In addition to the listed exceptions, any communications exception can be thrown.
        Throws:
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerException

      • checkForEvents

        public void checkForEvents​(int msecs)
                    throws BrokerException
        Check for the availability of deliverable events on the client's queue. Returns immediately if one or more events available on the queue, otherwise creates a pending check events request and blocks for a given number of milliseconds to be notified. If 'msecs' is TIME_INFINITE (-1), it waits forever. In addition to the listed exceptions, any communications exception can be thrown.
        Throws:
        BrokerInterruptedException - If interruptCheckForEvents is used to stop the call.
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerInvalidOperationException - If the client already has a pending check or get event request
        BrokerOutOfRangeException - If msecs is less than -1.
        BrokerTimeoutException - If the timeout is reached before an event arrives.
        BrokerException

      • interruptCheckForEvents

        public void interruptCheckForEvents()
                             throws BrokerException
        Interrupt any blocked awCheckForEvents call on the current client session. This operation is intended for use in multi-threaded clients. This function is safe for use in a signal handler.
        Throws:
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerException

      • cancelCheckForEvents

        public void cancelCheckForEvents()
                          throws BrokerException
        Cancel any pending check events request on the current client session. Any thread blocked on the checkForEvents call would be interrupted before canceling the check events request. This operation is intended for use in multi-threaded clients. This function is safe for use in a signal handler.
        Throws:
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerException

      • getEvent

        public BrokerEvent getEvent​(int msecs)
                     throws BrokerException
        Gets a single event from this client's queue. Blocks for a given number of milliseconds then gives up. If 'msecs' is TIME_INFINITE (-1), it waits forever. If 'msecs' is SYNCHRONOUS (-2), it returns immediately with either an event, or null if no events are available. 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.

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

      • getEvent

        protected BrokerEvent getEvent​(int msecs,
                               BrokerTransactionalClient tx_client)
                        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. If 'msecs' is SYNCHRONOUS (-2), it returns immediately with either an event, or null if no events are available. Acknowledges all events which have been retrieved previously that were not explicitly acknowledged. In addition to the listed exceptions, any communications exception can be thrown.
        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.
        BrokerException

      • getEvents

        public BrokerEvent[] getEvents​(int max_events,
                               int msecs)
                        throws BrokerException
        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. If 'msecs' is SYNCHRONOUS (-2), it returns immediately with either events, or an array length of zero if no events are available. 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.

        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.

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

      • getEvents

        protected BrokerEvent[] getEvents​(int max_events,
                                  int msecs,
                                  BrokerTransactionalClient tx_client)
                           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. If 'msecs' is SYNCHRONOUS (-2), it returns immediately with either events, or an array length of zero if no events are available. Acknowledges all events which have been retrieved previously that were not explicitly 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.
        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.
        BrokerException

      • getEvents

        public BrokerEvent[] getEvents​(int max_events,
                               long seqn,
                               int msecs)
                        throws BrokerException
        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. If 'msecs' is SYNCHRONOUS (-2), it returns immediately with either events, or an array length of zero if no events are available. 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.

        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

      • getEvents

        protected BrokerEvent[] getEvents​(int max_events,
                                  long seqn,
                                  int msecs,
                                  BrokerTransactionalClient tx_client)
                           throws BrokerException
        This request gets processed only after the given 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. If 'msecs' is SYNCHRONOUS (-2), it returns immediately with either events, or an array length of zero if no events are available. 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.
        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

      • browseEvents

        public BrokerEvent[] browseEvents​(int from_index,
                                  int max_events,
                                  BrokerFilterDescriptor[] filters)
                           throws BrokerException
        Peek one or more events from the specified client's queue. Returns immediately with either events, or an array length of zero if no events are available. 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.
        Throws:
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerOutOfRangeException - If the max_events or from_index is out of range.
        BrokerTimeoutException - If the timeout is reached before any events arrive.
        BrokerException

      • resendUnacknowledgedEvents

        public BrokerEvent[] resendUnacknowledgedEvents​(long[] seqn)
                                         throws BrokerException
        A list of events with the given "seqn" numbers will be sent to the broker again since they had not been acknowledged so far. The call returns an array of BrokerEvents which have been resent. This method does not have a timeout factor, waits until it resends all the events with the given seqn numbers. This is a new method and is only valid from 50 version of the Broker. In addition to the listed exceptions, any communications exception can be thrown.
        Throws:
        BrokerInterruptedException - If interruptGetEvents is used to stop the call.
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerOutOfRangeException - If you have duplicate/invalid seqn#
        BrokerException

      • negativeAcknowledgeInternal

        protected void negativeAcknowledgeInternal​(long[] seqn,
                                           long tx_id)
                                    throws BrokerException
        Throws:
        BrokerException

      • interruptGetEvents

        public void interruptGetEvents()
                        throws BrokerException
        Interrupt the current getEvent call for the client. If there is no such call in progress, the next such call is interrupted. This operation is intended for use in multi-threaded clients.
        Throws:
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerException

      • registerCallback

        public void registerCallback​(BrokerCallback obj,
                             java.lang.Object client_data)
                      throws BrokerException
        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.
        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
        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.
        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
        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.
        Throws:
        BrokerBadStateException - If no general callback has been registered.
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerNullParameterException - If obj is null.
        BrokerException

      • poll

        public static BrokerClientPoll[] poll​(BrokerClientPoll[] polls,
                                      int msecs)
                               throws BrokerException
        Allows one or more clients to polled for pending operations, returning only after at least one client has a ready operation, the current thread is interrupted or the given timeout has expired. It is not required that the clients be sharing connections. Passing in TIME_INFINITE (-1) will cause it to wait forever. In addition to the listed exceptions, any communications exception can be thrown.

        If one of the clients' requested operations is BrokerClientPoll.GET_EVENTS and there is not already an outstanding Broker event request then prime(1) will automatically be called for the client. If more than one event is required then it is the caller's responsibility to call prime on each of the Broker clients with the required number of events.

        Throws:
        BrokerNullParameterException - If polls is null.
        BrokerOutOfRangeException - If msecs is less than -1.
        BrokerTimeoutException - If the timeout is reached before any requested operations are ready.
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerInterruptedException - If the poll thread is interrupted.
        BrokerException

      • dispatch

        public static void dispatch​(int msecs)
                     throws BrokerException
        This function gets the next incoming event and passes it to the proper callback method. Checks all clients which have callbacks registered. It blocks for the specified number of miliseconds one event has been processed. Passing in TIME_INFINITE (-1) will cause it to wait forever. In addition to the listed exceptions, any communications exception can be thrown.
        Throws:
        BrokerBadStateException - If this is called from within a callback function.
        BrokerInterruptedException - If interruptDispatch 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 any events arrive.
        BrokerException

      • interruptDispatch

        public static void interruptDispatch()
                              throws BrokerException
        Interrupt the current dispatch call. If there is no such call in progress, the next such call is interrupted. This operation is intended for use in multi-threaded clients.
        Throws:
        BrokerException

      • mainLoop

        public static void mainLoop()
                     throws BrokerException
        A limited main loop which executes until told to stop. It is logically equivalent to: "while(do_not_stop) { dispatch() };"
        This function continues getting events and passing them to the proper callback methods. Checks all clients which have callbacks registered. In addition to the listed exceptions, any communications exception can be thrown.
        Throws:
        BrokerBadStateException - If this is called from within a callback function.
        BrokerException

      • stopMainLoop

        public static void stopMainLoop()
                         throws BrokerException
        Interrupt the current mainLoop calls. If there is no such call in progress, the next such call is interrupted. This operation is intended for use in multi-threaded clients or from within a callback method.
        Throws:
        BrokerException

      • threadedCallbacks

        public static void threadedCallbacks​(boolean enabled)
                              throws BrokerException
        A convenience method to run the mainLoop method on another thread. The same method is used to enable (start the thread) and disable (shut down the thread). Do not call this method from inside a callback. In addition to the listed exceptions, any communications exception can be thrown.
        Throws:
        BrokerException

      • prime

        public void prime()
           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(). Calling prime() is equivalent to calling prime(1). In addition to the listed exceptions, any communications exception can be thrown.
        Throws:
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        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.
        Parameters:
        num - The requested number of events.
        Throws:
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerException

      • primeAllClients

        public static void primeAllClients()
                            throws BrokerException
        Tell all clients to send a request for events but not block. Use this method if there are clients which have no callbacks and for which you intend to use isPending() or isClientPending() to determine if events are waiting prior to calling getEvent(). Calling primeAllClients() is equivalent to calling primeAllClients(1). Any communications exception can be thrown.
        Throws:
        BrokerException

      • primeAllClients

        public static void primeAllClients​(int num)
                            throws BrokerException
        Tell all clients to send a request for events but not block. Use this method if there are clients which have no callbacks and for which you intend to use isPending() or isClientPending() to determine if events are waiting prior to calling getEvent(). Any communications exception can be thrown.
        Parameters:
        num - The requested number of events.
        Throws:
        BrokerException

      • getQueueLength

        public int getQueueLength()
                   throws BrokerException
        Get the number of events currently in the client's queue. This includes any unacknowledged events in the queue. In addition to the listed exceptions, any communications exception can be thrown.
        Throws:
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerException

      • clearQueue

        public void clearQueue()
                throws BrokerException
        Clear all events from the client's queue. Use with caution. In addition to the listed exceptions, any communications exception can be thrown.
        Throws:
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerException

      • getStateShareLimit

        public int getStateShareLimit()
                       throws BrokerException
        Get the number of clients allowed to be connected using this client ID at one time. A value of NO_SHARE_LIMIT (-1) means there is no limit. Only clients created with shared state will ever have a value other than 1. No client will ever have the value 0 or less than -1. In addition to the listed exceptions, any communications exception can be thrown.
        Throws:
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerException

      • setStateShareLimit

        public void setStateShareLimit​(int limit)
                        throws BrokerException
        Set the number of clients which can be simultaneously connected using this client ID. Only usable on shared state clients. A value of NO_SHARE_LIMIT (-1) means there is no limit. In addition to the listed exceptions, any communications exception can be thrown.
        Throws:
        BrokerInvalidClientException - If the client has been destroyed or disconnected.
        BrokerNoPermissionException - If the client is not a shared state client.
        BrokerOutOfRangeException - If limit is zero or less than -1.
        BrokerException

      • getScopeNames

        public java.lang.String[] getScopeNames()
                                 throws BrokerException
        Get the complete list of event type scope names from the broker. Only lists the scopes which your client has permission to browse at least one event type from. A client normally can only browse event types which it can publish or subscribe to. In addition to the listed exceptions, any communications exception can be thrown.
        Throws:
        BrokerInvalidClientException - If the client has been disconnected or destroyed.
        BrokerException

      • getEventTypeNames

        public java.lang.String[] getEventTypeNames()
                                     throws BrokerException
        Get the complete list of event type names from the broker. Only lists the event types which your client has permission to browse. A client normally can only browse event types which it can publish or subscribe to. In addition to the listed exceptions, any communications exception can be thrown.
        Throws:
        BrokerInvalidClientException - If the client has been disconnected or destroyed.
        BrokerException

      • getEventTypeNames

        public java.lang.String[] getEventTypeNames​(java.lang.String scope_name)
                                     throws BrokerException
        Get the list of event type names from the broker which are a member of the specified event type scope. Only lists the event types which your client has permission to browse. A client normally can only browse event types which it can publish or subscribe to. In addition to the listed exceptions, any communications exception can be thrown.
        Throws:
        BrokerInvalidClientException - If the client has been disconnected or destroyed.
        BrokerNullParameterException - If scope_name is null.
        BrokerUnknownEventTypeException - If no event types exist in the specified scope on the broker.
        BrokerException

      • getCanPublishNames

        public java.lang.String[] getCanPublishNames()
                                      throws BrokerException
        Get the list of event type names which this client can publish or deliver. In addition to the listed exceptions, any communications exception can be thrown.
        Throws:
        BrokerInvalidClientException - If the client has been disconnected or destroyed.
        BrokerException

      • getCanSubscribeNames

        public java.lang.String[] getCanSubscribeNames()
                                        throws BrokerException
        Get the list of event type names which this client can subscribe to or have delivered to it. In addition to the listed exceptions, any communications exception can be thrown.
        Throws:
        BrokerInvalidClientException - If the client has been disconnected or destroyed.
        BrokerException

      • getLogPublishNames

        public java.lang.String[] getLogPublishNames()
                                      throws BrokerException
        Get the list of event types that are logged when published by clients of this client's client group. In addition to the listed exceptions, any communications exception can be thrown.
        Throws:
        BrokerInvalidClientException - If the client has been disconnected or destroyed.
        BrokerException

      • getLogAcknowledgeNames

        public java.lang.String[] getLogAcknowledgeNames()
                                          throws BrokerException
        Get the list of event types which can be logged when clients of this client group acknowledges them. In addition to the listed exceptions, any communications exception can be thrown.
        Throws:
        BrokerInvalidClientException - If the client has been disconnected or destroyed.
        BrokerException

      • getEventTypeDefs

        public BrokerTypeDef[] getEventTypeDefs​(java.lang.String[] event_type_names)
                                 throws BrokerException
        Get the definitions for the requested event types. The returned array will be the same size as array passed in, and will either have a BrokerTypeDef or null in each entry. They will be null if the specified event type does not exist or if the client does not have permission to browse the event type. Normally a client has permission to browse event types it can publish or subscribe to. In addition to the listed exceptions, any communications exception can be thrown.
        Throws:
        BrokerInvalidClientException - If the client has been disconnected or destroyed.
        BrokerNullParameterException - If event_type_names or any entry in that array is null.
        BrokerException

      • getCanPublishTypeDefs

        public BrokerTypeDef[] getCanPublishTypeDefs()
                                      throws BrokerException
        Get the definitions for the the event types this client can publish or deliver. In addition to the listed exceptions, any communications exception can be thrown.
        Throws:
        BrokerInvalidClientException - If the client has been disconnected or destroyed.
        BrokerException

      • getCanSubscribeTypeDefs

        public BrokerTypeDef[] getCanSubscribeTypeDefs()
                                        throws BrokerException
        Get the definitions for the the event types this client can subscribe to or have delivered to it. In addition to the listed exceptions, any communications exception can be thrown.
        Throws:
        BrokerInvalidClientException - If the client has been disconnected or destroyed.
        BrokerException

      • getEventTypeInfoset

        public BrokerEvent getEventTypeInfoset​(java.lang.String event_type_name,
                                       java.lang.String infoset_name)
                                throws BrokerException
        Get the specified infoset for the specified event type. The infoset itself is returned as an event for convenience. The infoset name is stored as the event's type name. In addition to the listed exceptions, any communications exception can be thrown.
        Throws:
        BrokerInvalidClientException - If the client has been disconnected or destroyed.
        BrokerNoPermissionException - If the infoset is not named "public" and the client does not have permission to publish or subscribe to the event type.
        BrokerNullParameterException - If event_type_name or infoset_name are null.
        BrokerUnknownEventTypeException - If the event type does not exist on the broker.
        BrokerUnknownInfosetException - If the infoset does not exist on the specified event type in the broker.
        BrokerException

      • getEventTypeInfosets

        public BrokerEvent[] getEventTypeInfosets​(java.lang.String event_type_name,
                                          java.lang.String[] infoset_names)
                                   throws BrokerException
        Get the requested infosets for the specified event type. If infoset_names is null, all infosets are returned. The infosets are returned as events for convenience. The infoset names are stored as the event type names. The returned infosets array will contain null entries for infosets which do not exist on the event type, or for which permission is denied. In addition to the listed exceptions, any communications exception can be thrown.
        Throws:
        BrokerInvalidClientException - If the client has been disconnected or destroyed.
        BrokerNullParameterException - If event_type_name or infoset_name are null.
        BrokerUnknownEventTypeException - If the event type does not exist on the broker.
        BrokerException

      • getClientInfoset

        public BrokerEvent getClientInfoset()
                             throws BrokerException
        Get the infoset for this client. The infoset is returned as an event object for convenience. In addition to the listed exceptions, any communications exception can be thrown.
        Throws:
        BrokerInvalidClientException - If the client has been disconnected or destroyed.
        BrokerException

      • setAutomaticControlLabel

        public void setAutomaticControlLabel​(boolean enabled)
                              throws BrokerException
        Enable or disable automatic setting of the _env.controlLabel field. If set to true, the client's access label (if any) will be placed into the _env.controlLabel field if that field is not set before publishing. In addition to the listed exceptions, any communications exception can be thrown.
        Throws:
        BrokerInvalidClientException - If the client has been disconnected or destroyed.
        BrokerException

      • registerConnectionCallback

        public void registerConnectionCallback​(BrokerConnectionCallback obj,
                                       java.lang.Object client_data)
                                throws BrokerException
        Register a connection callback for this client. Calling this on a client which already has an existing callback will replace that callback. 'obj' may be null to clear the callback. 'client_data' may be null. The callback method will be called with connect_state set to CONNECT_STATE_DISCONNECTED if the client is disconnected. It will be called with CONNECT_STATE_CONNECTED if the client connection is re-established (only happens if automatic reconnect is enabled). It will be called with CONNECT_STATE_RECONNECTED if the disconnect is discovered, but the connection is re-established immediately (only happensif automatic reconnect is enabled).
        Throws:
        BrokerInvalidClientException - If the client has been disconnected or destroyed.
        BrokerException

      • getDefaultBrokerPort

        public static int getDefaultBrokerPort()
        Get the default port number for connecting to brokers.

      • getDefaultTimeout

        public static int getDefaultTimeout()
        Gets the current default timeout for Broker requests. Returns 30000 milliseconds by default unless the timeout is explicitly set to another value.

      • setDefaultClientTimeout

        public static int setDefaultClientTimeout​(int msecs)
        Set the default timeout for broker requests. Returns the previous timeout value.

      • getPlatformInfoKeys

        public static java.lang.String[] getPlatformInfoKeys()
        Get the list of platform info keys.

      • setPlatformInfo

        public static void setPlatformInfo​(java.lang.String key,
                                   java.lang.String value)
                            throws BrokerException
        Set a platform info value. If a value was not previously defined for that key, the key is added to the platform information. Platform information is transmitted to the broker during new BrokerClient() and reconnectBrokerClient() operations.
        Throws:
        BrokerNoPermissionException - If the key refers to read-only platform information.
        BrokerNullParameterException - If key or value are null.
        BrokerException

      • getSess

        public int getSess()
        System use only. Access session information.

      • newTx

        protected long newTx​(java.lang.String external_id,
                     int existsFlag,
                     long timeout,
                     long tx_id)
              throws BrokerException
        Creates a transaction context that can be used to aggregate multiple publish and acknowledge operations into a single unit of work that can be committed or aborted atomically. If the transaction id is supplied, an external id and a timeout must also be supplied.
        Parameters:
        external_id - (optional) A user defined transaction identifier
        Returns:
        a transaction context
        Throws:
        BrokerException

      • endTx

        protected void endTx​(long[] tx_ids,
                     int tx_state)
              throws BrokerException
        Ends the transaction
        Parameters:
        tx_ids - the transaction identifiers
        tx_state - TX_END_COMMIT | TX_END_ABORT
        Throws:
        BrokerException

      • endExt

        protected void endExt​(java.lang.String[] ext_ids,
                      int tx_state)
               throws BrokerException
        Ends the transaction
        Parameters:
        ext_ids - the transaction identifiers
        tx_state - TX_END_COMMIT | TX_END_ABORT
        Throws:
        BrokerException

      • prepareTx

        protected int prepareTx​(long[] tx_ids)
                 throws BrokerException
        Prepares the transaction
        Parameters:
        tx_ids - the transaction identifiers
        Throws:
        BrokerException

      • setTxId

        protected void setTxId​(long tx_id,
                       java.lang.String external_id)
                throws BrokerException
        Sets the Broker transaction's external identifier.
        Parameters:
        tx_id - a Broker transaction identifier
        external_id - an externally generated 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.

      • forgetTx

        protected void forgetTx​(long[] tx_ids)
                 throws BrokerException
        Forgets the transaction This can be called at any time, hence informing the broker that the the current transaction should be marked invalid.
        Parameters:
        tx_ids - the transaction identifiers
        Throws:
        BrokerException

      • setAsyncExceptionListener

        public void setAsyncExceptionListener​(BrokerAsyncExceptionListener listener)
        Registers an asynchronous Broker exception listener.
        Parameters:
        listener - the exception listener

      • getAsyncExceptionListener

        public BrokerAsyncExceptionListener getAsyncExceptionListener()
        Returns the asynchronous Broker exception listner.
        Returns:
        the exception listener