Package COM.activesw.api.client

Class BrokerClusterPublisher

java.lang.Object
COM.activesw.api.client.BrokerClusterPublisher
public class BrokerClusterPublisher extends Object

  • Constructor Details

  • Method Details

    • localPublish

      public void localPublish(BrokerEvent[] events) throws BrokerException
      Publish multiple events to clients on the local broker only. 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.
      BrokerClusterPublisherException - If no broker is available on the cluster pool.
      BrokerException

    • localPublish

      public void localPublish(BrokerEvent event) throws BrokerException
      Publish one event to clients on the local broker only. 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.
      BrokerClusterPublisherException - If no broker is available on the cluster pool.
      BrokerException

    • localPublishRequestAndWait

      public BrokerEvent[] localPublishRequestAndWait(BrokerEvent event, int msecs) throws BrokerException
      Publish one request event and wait for replies. The event is given to the subscribers on the local broker only. 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.

      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.
      BrokerClusterPublisherException - If no broker is available on the cluster pool.
      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.
      BrokerClusterPublisherException - If no broker is available on the cluster pool.
      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.
      BrokerClusterPublisherException - If no broker is available on the cluster pool.
      BrokerException

    • publishRequestAndWait

      public BrokerEvent[] publishRequestAndWait(BrokerEvent event, int msecs) throws BrokerException
      Publish one request event and wait for replies. The event is given to the broker to be given to all subscribing clients. 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.

      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.
      BrokerClusterPublisherException - If no broker is available on the cluster pool.
      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.
      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.
      BrokerClusterPublisherException - If no broker is available on the cluster pool.
      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.
      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.
      BrokerClusterPublisherException - If no broker is available on the cluster pool.
      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.

      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 dest_id or event are null.
      BrokerUnknownEventTypeException - If the event type for the event does not exist on the broker.
      BrokerClusterPublisherException - If no broker is available on the cluster pool.
      BrokerException

    • newOrReconnect

      public static BrokerClusterPublisher newOrReconnect(String broker_host, String broker_name, String client_id, String client_group, String app_name, BrokerConnectionDescriptor desc, BrokerConnectionDescriptor mon_desc) throws BrokerException
      Attempts to create BrokerClusterPublisher. If the creation fails because the client already exists, then it reconnects to the client instead.
      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

    • reconnect

      public static BrokerClusterPublisher reconnect(String broker_host, String broker_name, String client_id, String client_group, String app_name, BrokerConnectionDescriptor desc, BrokerConnectionDescriptor mon_desc) throws BrokerException
      Reconnects BrokerClusterPublisher. '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 BrokerClusterPublisher, only one active connection can be made to the broker for a given client_id, and so an error will be returned on reconnect if the client_id is already in use on any of the territory brokers.
      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

    • disconnect

      public void disconnect() throws BrokerException
      Disconnect BrokerClusterPublisher. 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.
      BrokerClusterPublisherException - If no client is found on the cluster pool or all the clients have been already destroyed or disconnected.
      BrokerException

    • destroy

      public void destroy() throws BrokerException
      Destroy BrokerClusterPublisher. Destroys all the clients created on the territory brokers as part of the cluster operations. May throw any communications exception, but the local client object is marked as disconnected even if an exception is thrown.
      Throws:
      BrokerInvalidClientException - If any of the cluster client has been already destroyed or disconnected.
      BrokerClusterPublisherException - If no client is found on the cluster pool or all the clients have been already destroyed or disconnected.
      BrokerException

    • registerSelectionCallback

      public void registerSelectionCallback(BrokerCPSelectionCallback obj, Object client_data) throws BrokerException
      Register a cluster publisher selection 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 invoded whenever a cluster client needs to be selected from the cluster client pool in order to execute a publish operation. It will be called with an event or an array event to be published along with a BrokerInfo[] array containing a list of territory brokers to which cluster client connection exists at present.
      Throws:
      BrokerInvalidClientException - If the client has been destroyed or disconnected.
      BrokerNullParameterException - If obj is null.
      BrokerException

    • cancelSelectionCallback

      public void cancelSelectionCallback() throws BrokerException
      Cancel the cluster publisher's selection callback, if any registered.
      Throws:
      BrokerInvalidClientException - If the client has been destroyed or disconnected.
      BrokerException

    • registerConnectionCallback

      public void registerConnectionCallback(BrokerCPConnectionCallback obj, Object client_data) throws BrokerException
      Register a connection callback for the cluster publisher. 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 when the client connection is first established. It will again be called with CONNECT_STATE_RECONNECTED when the cluster client reestablishes client connection
      Throws:
      BrokerInvalidClientException - If the client has been destroyed or disconnected.
      BrokerNullParameterException - If obj is null.
      BrokerException

    • cancelConnectionCallback

      public void cancelConnectionCallback() throws BrokerException
      Cancel the cluster publisher's connection callback, if any registered.
      Throws:
      BrokerInvalidClientException - If the client has been destroyed or disconnected.
      BrokerException

    • excludeBroker

      public void excludeBroker(String brokerName) throws BrokerException
      Exclude specified broker for cluster operations. This call just takes a broker name string as an argument. If the specified broker is found in the current cluster publisher's broker pool, it will be removed from the pool. The specified broker will not be considered for future cluster operations. If the broker is not found in the cluster publisher's broker pool, an exception will be thrown.
      Throws:
      BrokerInvalidClientException - If the client has been destroyed or disconnected.
      BrokerClusterPublisherException - If the specified broker is not part of the cluster publisher operation or the last single broker client connection found on the client pool.
      BrokerInvalidPortException - If the specified port is invalid
      BrokerException

    • includeBroker

      public void includeBroker(String brokerName) throws BrokerException
      Include specified broker for cluster operations. This call just takes a broker name string as an argument. If the specified broker is found in the current cluster publisher's broker pool, it will be removed from the pool. The specified broker will be considered for future cluster operations. If the broker is not found or not in the territory or already present in the cluster pool, appropriate exception will be thrown.
      Throws:
      BrokerInvalidClientException - If the client has been destroyed or disconnected.
      BrokerClusterPublisherException - If the specified broker was not previously excluded from the client pool or the it is currently present in the client pool.
      BrokerInvalidPortException - If the specified port is invalid
      BrokerException

    • getClientGroup

      public String getClientGroup()
      Get the client group name.

    • getClientId

      public String getClientId()
      Get the application client identifier.

    • getMonitorClientId

      public String getMonitorClientId()
      Get the cluster monitor client's identifier.

    • isConnected

      public boolean isConnected()
      Check if connected. This is a passive check, meaning it only tells if the BrokerClusterPublisher 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 connection is valid and is still connected, or false if not.

    • getApplicationName

      public String getApplicationName()
      Get the application name.

    • 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.
      BrokerClusterPublisherException - If no broker is available on the cluster pool
      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.
      BrokerClusterPublisherException - If no broker is available on the cluster pool.
      BrokerException

    • 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.
      BrokerClusterPublisherException - If no broker is available on the cluster pool.
      BrokerException

    • getLastUsed

      public String getLastUsed()
      Get the broker name on which the last cluster operation was executed.

    • toString

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

    • getClusterPublisherInfo

      public BrokerEvent getClusterPublisherInfo() throws BrokerException
      Get the cluster publisher info. Info is set into a BrokerEvent as fields. The available values are:
      • client_id -- (unicode string) Client id
      • client_group -- (unicode string) Client Group
      • app_name -- (unicode string) Application Name
      • connection_callback -- (boolean) true, if a connection callback is registered; otherwise false.
      • selection_callback -- (boolean) true, if a selection callback is registered; otherwise false.
      • monitor_client -- (unicode string) Client id of the monitor client
      • brokers -- (structure array) An array of structures describing brokers used as part of cluster operations.
      • brokers[].broker_host -- (unicode string) Broker host name.
      • brokers[].broker_name -- (unicode string) Broker name.
      • brokers[].description -- (unicode string) Broker description.
      • brokers[].territory_name -- (unicode string) Broker's territory name.
      • exclude_brokers -- (unicode string array) An array of strings listing the broker names that are excluded from the cluster operations.
      Throws:
      BrokerException

    • getClusterPublisherStats

      public BrokerEvent getClusterPublisherStats() throws BrokerException
      Get the cluster publisher statistics. Statistics are set into a BrokerEvent as fields. The available values are:
      • now -- (date) Current time on the broker host.
      • numClients -- (int) Number of clients employed in cluster operations.
      • numExcludedBrokers -- (int) Number of brokers excluded from the cluster operations.
      • numEventsPublished -- (int) Number of events published using this publisher.
      • lastEventPublishTime -- (date) Time when last event was published by a member. Forever (zero date and time) if no events ever published.
      • numEventsDelivered -- (int) Number of events delivered using this cluster publisher.
      • lastEventDeliverTime -- (date) Time when last event was delivered using this cluter client. Forever (zero date and time) if no events ever delivered.
      • numEventsReceived -- (int) Number of events received as part of publish/deliverRequestAndWait operations on this cluster publisher.
      • lastEventReceiveTime -- (date) Time when last event was received on this cluter client. Forever (zero date and time) if no events ever received.
      • lastActivityOn -- (unicode string) Client id of the client on which the last operation was executed.
      Throws:
      BrokerException