Package COM.activesw.api.client

Class BrokerClient

java.lang.Object
COM.activesw.api.client.BrokerClient
Direct Known Subclasses:
BrokerAdminClient, BrokerTransactionalClient
public class BrokerClient extends Object
Representation of an Information Broker client.

Hostnames may include a ":port" on the end of them to indicate a specific (non-default) broker port.

Many calls say they can throw a "communications exception". These exceptions are:

BrokerCommFailureException
If a networking error occurs.
BrokerConnectionClosedException
If the broker disconnects from the application.
BrokerFailureException
If an error occurs on the broker which prevents the operation from being completed.
BrokerProtocolException
If an error occurs in communication between the broker and the application.
BrokerTimeoutException
If the request was not handled in a reasonable time. Most operations use the default timeout of 30 seconds.

  • Field Details

  • Constructor Details

  • Method Details

    • reconnect

      public static BrokerClient reconnect(String broker_host, String broker_name, 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

    • newOrReconnect

      public static BrokerClient newOrReconnect(String broker_host, String broker_name, String client_id, String client_group, String app_name, BrokerConnectionDescriptor desc) throws BrokerException
      Attempts to create the client. If the creation fails because the client already exists, then it reconnects to the client instead. '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 if the client already exists. Whether or not the client shares state can only be set when making a new client.
      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.
      BrokerInvalidClientIdException - If the ID contains illegal characters.
      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, client_id, client_group, or app_name 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.
      BrokerUnknownClientGroupException - If the specified client group does not exist on the broker.
      BrokerUnknownClientIdException - If the specified client ID does not exist on the broker.
      BrokerException

    • getBrokerHost

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

    • getBrokerPort

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

    • getTerritoryName

      public 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 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 String getClientGroup()
      Get the client's client group name.

    • getClientId

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

    • getApplicationName

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

    • getClientInfo

      public BrokerClientInfo getClientInfo() throws BrokerException
      Get the current client's information.
      Throws:
      BrokerInvalidClientException - If the client has been destroyed or disconnected.
      BrokerNoPermissionException - If the client does not have permission to browse the specified client.
      BrokerNullParameterException - If client_id is null.
      BrokerUnknownClientIdException - If the client does not exist on the broker.
      BrokerException

    • 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 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 String toString()
      Returns a string with the client information in a form suitable for human viewing.
      Overrides:
      toString in class Object

    • canPublish

      public boolean canPublish(String event_type_name) throws BrokerException
      Test if can publish or deliver an event of a given type. In addition to the listed exceptions, any communications exception can be thrown.
      Throws:
      BrokerInvalidClientException - If the client has been destroyed or disconnected.
      BrokerNullParameterException - If event_type_name is null.
      BrokerUnknownEventTypeException - If the event type does not exist on the broker.
      BrokerException

    • publish

      public void publish(BrokerEvent event) throws BrokerException
      Publish one event. 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.
      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.
      BrokerException

    • publish

      protected void publish(BrokerEvent event, BrokerTransactionalClient tx_client) 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.
      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.
      BrokerException

    • publish

      public void publish(BrokerEvent[] events) throws BrokerException
      Publish multiple events. 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.
      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.
      BrokerUnknownEventTypeException - If the event type for any of the events does not exist on the broker.
      BrokerException

    • jmsClientPublish

      public void jmsClientPublish(COM.activesw.api.client.BrokerJMSEvent[] events, boolean async) throws BrokerException
      Throws:
      BrokerException

    • publish

      protected void publish(BrokerEvent[] events, BrokerTransactionalClient tx_client) throws BrokerException
      Publish multiple events on 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.
      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.
      BrokerUnknownEventTypeException - If the event type for any of the events does not exist on the broker.
      BrokerException

    • jmsClientPublish

      protected void jmsClientPublish(COM.activesw.api.client.BrokerJMSEvent[] events, boolean async, BrokerTransactionalClient tx_client) throws BrokerException
      Throws:
      BrokerException

    • publishWithAck

      public void publishWithAck(BrokerEvent[] events, int ack_type, long[] ack_seqn) throws BrokerException
      Publish multiple events. 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.
      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.
      BrokerException

    • publishWithAck

      protected void publishWithAck(BrokerEvent[] events, int ack_type, long[] ack_seqn, BrokerTransactionalClient tx_client) 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.
      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.
      BrokerException

    • deliver

      public void deliver(String dest_id, BrokerEvent event) throws BrokerException
      Deliver one event. 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.
      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.
      BrokerException

    • deliver

      protected void deliver(String dest_id, BrokerEvent event, BrokerTransactionalClient tx_client) 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.
      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.
      BrokerException

    • deliver

      public void deliver(String dest_id, BrokerEvent[] events) throws BrokerException
      Deliver multiple events. 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.
      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.
      BrokerException

    • deliver

      protected void deliver(String dest_id, BrokerEvent[] events, BrokerTransactionalClient tx_client) 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.
      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.
      BrokerException

    • deliverWithAck

      public void deliverWithAck(String dest_id, BrokerEvent[] events, int ack_type, long[] ack_seqn) throws BrokerException
      Deliver multiple events. 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.
      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.
      BrokerException

    • deliverWithAck

      protected void deliverWithAck(String dest_id, BrokerEvent[] events, int ack_type, long[] ack_seqn, BrokerTransactionalClient tx_client) 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.
      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.
      BrokerException

    • 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(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, 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, 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(String transaction_id, int required_level, 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(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

    • canSubscribe

      public boolean canSubscribe(String event_type_name) throws BrokerException
      Test if can subscribe to an event type, or have events of that type delivered to this client. In addition to the listed exceptions, any communications exception can be thrown.
      Throws:
      BrokerInvalidClientException - If the client has been destroyed or disconnected.
      BrokerNullParameterException - If event_type_name is null.
      BrokerUnknownEventTypeException - If the event type does not exist on the broker.
      BrokerException

    • newSubscription

      public void newSubscription(String event_type_name, 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, String event_type_name, 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

    • newSubscription

      public void newSubscription(BrokerSubscription sub) throws BrokerException
      Subscribe to all events of a given event type. 'null' can be stored in the filter field 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 sub.event_type_name is null.
      BrokerOutOfRangeException - If sub.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

    • cancelSubscription

      public void cancelSubscription(String event_type_name, String filter) throws BrokerException
      Cancel a subscription with matching event type and filter. 'filter' may be null. 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.
      BrokerNullParameterException - If event_type_name is null.
      BrokerException

    • cancelSubscription

      public void cancelSubscription(BrokerSubscription sub) throws BrokerException
      Cancel a subscription with matching event type and filter. The filter may be null. The sub_id field of the subscription object is ignored. Only the event type name and filter are used to find the matching subscription. 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.
      BrokerNullParameterException - If sub or sub.event_type_name are null.
      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

    • getSubscriptions

      public BrokerSubscription[] getSubscriptions() throws BrokerException
      Get the list of open subscriptions. In addition to the listed exceptions, any communications exception can be thrown.
      Throws:
      BrokerInvalidClientException - If the client has been destroyed or disconnected.
      BrokerException

    • doesSubscriptionExist

      public boolean doesSubscriptionExist(String event_type_name, 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 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.
      COM.activesw.api.client.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

    • cancelGetEvents

      public void cancelGetEvents() throws BrokerException
      Throws:
      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

    • getJMSEvents

      public COM.activesw.api.client.BrokerJMSEvent[] getJMSEvents(int max_events, long seqn, int msecs) throws BrokerException
      Throws:
      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

    • getJMSEvents

      protected COM.activesw.api.client.BrokerJMSEvent[] getJMSEvents(int max_events, long seqn, int msecs, BrokerTransactionalClient tx_client) throws BrokerException
      Throws:
      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

    • incrementRedeliveryCount

      public void incrementRedeliveryCount(long seqn) throws BrokerException
      Increments the redelivery count on the single event specified. In addition to the listed exceptions, any communications exception can be thrown.
      Throws:
      BrokerInvalidClientException - If the client has been destroyed or disconnected.
      BrokerOutOfRangeException - If you have a negative seqn#
      COM.activesw.api.client.BrokerInvalidOperationException - If you try to manually increment redelivery counts for a client that has automatic increments
      COM.activesw.api.client.BrokerInvalidSequenceNumberException - If you supply a sequence number that does not correspond to a received event.
      BrokerException

    • negativeAcknowledge

      public void negativeAcknowledge(long seqn) throws BrokerException
      Negative acknowledges the single event specified. In addition to the listed exceptions, any communications exception can be thrown.
      Throws:
      BrokerInvalidClientException - If the client has been destroyed or disconnected.
      BrokerOutOfRangeException - If you have a negative seqn#
      COM.activesw.api.client.BrokerInvalidOperationException - If you try to manually increment redelivery counts for a client that has automatic increments
      COM.activesw.api.client.BrokerInvalidSequenceNumberException - If you supply a sequence number that does not correspond to a received event.
      BrokerException

    • negativeAcknowledge

      public void negativeAcknowledge(long[] seqn) throws BrokerException
      Negative acknowledges the events specified. In addition to the listed exceptions, any communications exception can be thrown.
      Throws:
      BrokerInvalidClientException - If the client has been destroyed or disconnected.
      BrokerOutOfRangeException - If you have a negative seqn#
      COM.activesw.api.client.BrokerInvalidOperationException - If you try to manually increment redelivery counts for a client that has automatic increments
      COM.activesw.api.client.BrokerInvalidSequenceNumberException - If you supply a sequence number that does not correspond to a received event.
      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, 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, 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, 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

    • cancelCallbacks

      public void cancelCallbacks() throws BrokerException
      Cancel all callbacks for the client.
      Throws:
      BrokerInvalidClientException - If the client has been destroyed or disconnected.
      BrokerException

    • cancelCallbackForSubId

      public void cancelCallbackForSubId(int sub_id) throws BrokerException
      Cancel the client's specific callback for a subscription id.
      Throws:
      BrokerInvalidClientException - If the client has been destroyed or disconnected.
      BrokerException

    • cancelCallbackForTag

      public void cancelCallbackForTag(int tag) throws BrokerException
      Cancel the client's specific callback for a tag value.
      Throws:
      BrokerInvalidClientException - If the client has been destroyed or disconnected.
      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

    • isClientPending

      public boolean isClientPending() throws BrokerException
      Check if any events are pending for the client.
      Throws:
      BrokerInvalidClientException - If the client has been destroyed or disconnected.
      BrokerException

    • isPending

      public static boolean isPending() throws BrokerException
      Check if any events are pending for any client.
      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

    • primeWithAck

      public void primeWithAck(int num) throws BrokerException
      Throws:
      BrokerException

    • prime

      protected void prime(int num, BrokerTransactionalClient tx_client) throws BrokerException
      Throws:
      BrokerException

    • primeWithAck

      protected void primeWithAck(int num, BrokerTransactionalClient tx_client) throws BrokerException
      Throws:
      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

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

    • acknowledge

      public void acknowledge(long seqn, long txid) throws BrokerException
      Acknowledge the single event specified, under the specified transaction id. A value of zero acknowledges all outstanding events. In addition to the listed exceptions, any communications exception can be thrown.
      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.
      BrokerException

    • acknowledge

      public void acknowledge(long[] seqn) 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.
      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.
      BrokerException

    • acknowledge

      public void acknowledge(long[] seqn, long txid) throws BrokerException
      Acknowledge the array of events with the given seqn numbers, under the specified transaction id. A value of zero acknowledges all outstanding events. In addition to the listed exceptions, any communications exception can be thrown.
      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.
      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.
      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.
      BrokerException

    • acknowledgeThrough

      public void acknowledgeThrough(long seqn, long txid) throws BrokerException
      Acknowledges all events through the event specified, under the specified transaction id. A value of zero acknowledges all outstanding events. In addition to the listed exceptions, any communications exception can be thrown.
      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.
      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

    • getAccessLabel

      public short[] getAccessLabel() throws BrokerException
      Get the access label for this client. In addition to the listed exceptions, any communications exception can be thrown.
      Throws:
      BrokerBadStateException - If the client has an owner, but the access label feature is not enabled.
      BrokerFailureException - If the client has an owner, but an error occurred looking up the access label.
      BrokerInvalidClientException - If the client has been destroyed or disconnected.
      BrokerNoPermissionException - If the client does not have an owner, so it cannot have an access label.
      BrokerException

    • getClientSSLEncryptionLevel

      public int getClientSSLEncryptionLevel() throws BrokerException
      Get the secure socket encryption level. See BrokerConnectionDescriptor.ENCRYPT_LEVEL_* for values.
      Throws:
      BrokerBadStateException - If the client is not using a secure socket connection.
      BrokerInvalidClientException - If the client has been destroyed or disconnected.
      BrokerException

    • getBrokerSSLCertificate

      public BrokerSSLCertificate getBrokerSSLCertificate() throws BrokerException
      Get the secure socket certificate for the broker.
      Throws:
      BrokerBadStateException - If the client is not using a secure socket connection.
      BrokerInvalidClientException - If the client has been destroyed or disconnected.
      BrokerException

    • getScopeNames

      public 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 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 String[] getEventTypeNames(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 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 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 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 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

    • getEventLogging

      public boolean getEventLogging() throws BrokerException
      Throws:
      BrokerException

    • getEventTypeDef

      public BrokerTypeDef getEventTypeDef(String event_type_name) throws BrokerException
      Get the specified event type's definition. 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 client does not have permission to browse the event type. Normally a client has permission to browse an event type it can publish or subscribe to.
      BrokerNullParameterException - If event_type_name is null.
      BrokerUnknownEventTypeException - If the event type does not exist on the broker.
      BrokerException

    • getEventTypeDefs

      public BrokerTypeDef[] getEventTypeDefs(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(String event_type_name, 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(String event_type_name, 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

    • getEventTypeInfosetNames

      public String[] getEventTypeInfosetNames(String event_type_name) throws BrokerException
      Get the list of infosets names for an event type. 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 client does not have permission to publish or subscribe to the event type.
      BrokerNullParameterException - If event_type_name is 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

    • getJMSClientInfoset

      public COM.activesw.api.client.BrokerJMSEvent getJMSClientInfoset() throws BrokerException
      Throws:
      BrokerException

    • setClientInfoset

      public void setClientInfoset(BrokerEvent infoset) throws BrokerException
      Set the infoset for this client. In addition to the listed exceptions, any communications exception can be thrown.
      Throws:
      BrokerInvalidClientException - If the client has been disconnected or destroyed.
      BrokerInvalidEventTypeNameException - If the infoset name includes colons.
      BrokerNullParameterException - If infoset is null.
      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, 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 String[] getPlatformInfoKeys()
      Get the list of platform info keys.

    • getPlatformInfo

      public static String getPlatformInfo(String key) throws BrokerException
      Get a platform info value.
      Throws:
      BrokerNullParameterException - If key is null.
      BrokerUnknownKeyException - If the key does not exist in the platform info.
      BrokerException

    • setPlatformInfo

      public static void setPlatformInfo(String key, 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(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

    • endTr

      protected void endTr(long[] tx_ids, int tx_state) throws BrokerException
      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(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

    • prepareExt

      protected void prepareExt(String[] ext_ids) throws BrokerException
      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, 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

    • forgetExt

      protected void forgetExt(String[] ext_ids) throws BrokerException
      Throws:
      BrokerException

    • recoverTx

      protected String[] recoverTx(int flags, long lastTxID) throws BrokerException
      Throws:
      BrokerException

    • setTxTimeout

      protected void setTxTimeout(int seconds, long tx_id) throws BrokerException
      Throws:
      BrokerException

    • getTxTimeout

      protected int getTxTimeout(long tx_id) throws BrokerException
      Throws:
      BrokerException

    • resetSessionFilters

      public void resetSessionFilters() throws BrokerException
      Reset existing filters on the client session.
      Throws:
      BrokerInvalidClientException - If the client has been destroyed.
      BrokerNoPermissionException - If the client has limited access.
      BrokerNullParameterException - If description is null.
      BrokerUnknownEventTypeException - If no events exist in the specified scope on the broker.
      COM.activesw.api.client.BrokerInvalidFilterException - If the specified filter expression is invalid.
      BrokerException

    • setSessionFilter

      public void setSessionFilter(BrokerFilterDescriptor filter) throws BrokerException
      Set filter for event retrieval operations.
      Throws:
      BrokerInvalidClientException - If the client has been destroyed.
      BrokerNoPermissionException - If the client has limited access.
      BrokerNullParameterException - If description is null.
      BrokerUnknownEventTypeException - If no events exist in the specified scope on the broker.
      COM.activesw.api.client.BrokerInvalidFilterException - If the specified filter expression is invalid.
      BrokerException

    • setSessionFilters

      public void setSessionFilters(BrokerFilterDescriptor[] filter) throws BrokerException
      Set filters for event retrieval operations.
      Throws:
      BrokerInvalidClientException - If the client has been destroyed.
      BrokerNoPermissionException - If the client has limited access.
      BrokerNullParameterException - If description is null.
      BrokerUnknownEventTypeException - If no events exist in the specified scope on the broker.
      COM.activesw.api.client.BrokerInvalidFilterException - If the specified filter expression is invalid.
      BrokerException

    • getSessionFilters

      public BrokerFilterDescriptor[] getSessionFilters() throws BrokerException
      Get the current filter used for event retrieval operations.
      Throws:
      BrokerInvalidClientException - If the client has been destroyed.
      BrokerFilterNotSetException - If the client does not have any filter set for event retrieval operation.
      BrokerException

    • getServerFilterCollationLocale

      public Locale getServerFilterCollationLocale() throws BrokerException
      Returns the active Broker Server Filter Collation locale.
      Throws:
      BrokerInvalidClientException - If the client has been destroyed.
      BrokerNoPermissionException - If the client has limited access.
      BrokerNullParameterException - If description is null.
      BrokerInvalidNameException - If the locale name is invalid.
      BrokerException

    • setAsyncExceptionListener

      public void setAsyncExceptionListener(COM.activesw.api.client.BrokerAsyncExceptionListener listener)
      Registers an asynchronous Broker exception listener.
      Parameters:
      listener - the exception listener

    • getAsyncExceptionListener

      public COM.activesw.api.client.BrokerAsyncExceptionListener getAsyncExceptionListener()
      Returns the asynchronous Broker exception listner.
      Returns:
      the exception listener

    • createClientQueueBrowser

      public BrokerClientQueueBrowser createClientQueueBrowser() throws BrokerException
      Creates a queue browser on the current client's queue. This queue browser can be used to browse events from the queue without holding queue lock.
      Returns:
      BrokerClientQueueBrowser object.
      Throws:
      BrokerInvalidClientException - If the client has been destroyed or disconnected.
      BrokerException