COM.activesw.api.client
Class BrokerClusterPublisher

java.lang.Object
  COM.activesw.api.client.BrokerClusterPublisher

public class BrokerClusterPublisher
extends java.lang.Object

Constructor Summary

BrokerClusterPublisher(java.lang.String broker_host, java.lang.String broker_name, java.lang.String client_id, java.lang.String client_group, java.lang.String app_name, BrokerConnectionDescriptor desc, BrokerConnectionDescriptor mon_desc)
Creates a BrokerClusterPublisher.

Method Summary

void	cancelConnectionCallback() Cancel the cluster publisher's connection callback, if any registered.
void	cancelSelectionCallback() Cancel the cluster publisher's selection callback, if any registered.
boolean	canPublish(java.lang.String event_type_name) Test if can publish or deliver an event of a given type.
void	deliver(java.lang.String dest_id, BrokerEvent event) Deliver one event.
void	deliver(java.lang.String dest_id, BrokerEvent[] events) Deliver multiple events.
BrokerEvent[]	deliverRequestAndWait(java.lang.String dest_id, BrokerEvent event, int msecs) Deliver one request event and wait for replies.
void	destroy() Destroy BrokerClusterPublisher.
void	disconnect() Disconnect BrokerClusterPublisher.
void	excludeBroker(java.lang.String brokerName) Exclude specified broker for cluster operations.
java.lang.String	getApplicationName() Get the application name.
java.lang.String[]	getCanPublishNames() Get the list of event type names which this client can publish or deliver.
java.lang.String	getClientGroup() Get the client group name.
java.lang.String	getClientId() Get the application client identifier.
BrokerEvent	getClusterPublisherInfo() Get the cluster publisher info.
BrokerEvent	getClusterPublisherStats() Get the cluster publisher statistics.
java.lang.String	getLastUsed() Get the broker name on which the last cluster operation was executed.
java.lang.String	getMonitorClientId() Get the cluster monitor client's identifier.
java.lang.String	getTerritoryName() Get the territory name of the client's broker.
void	includeBroker(java.lang.String brokerName) Include specified broker for cluster operations.
boolean	isConnected() Check if connected.
void	localPublish(BrokerEvent event) Publish one event to clients on the local broker only.
void	localPublish(BrokerEvent[] events) Publish multiple events to clients on the local broker only.
BrokerEvent[]	localPublishRequestAndWait(BrokerEvent event, int msecs) Publish one request event and wait for replies.
static BrokerClusterPublisher	newOrReconnect(java.lang.String broker_host, java.lang.String broker_name, java.lang.String client_id, java.lang.String client_group, java.lang.String app_name, BrokerConnectionDescriptor desc, BrokerConnectionDescriptor mon_desc) Attempts to create BrokerClusterPublisher.
void	publish(BrokerEvent event) Publish one event.
void	publish(BrokerEvent[] events) Publish multiple events.
BrokerEvent[]	publishRequestAndWait(BrokerEvent event, int msecs) Publish one request event and wait for replies.
static BrokerClusterPublisher	reconnect(java.lang.String broker_host, java.lang.String broker_name, java.lang.String client_id, java.lang.String client_group, java.lang.String app_name, BrokerConnectionDescriptor desc, BrokerConnectionDescriptor mon_desc) Reconnects BrokerClusterPublisher.
void	registerConnectionCallback(BrokerCPConnectionCallback obj, java.lang.Object client_data) Register a connection callback for the cluster publisher.
void	registerSelectionCallback(BrokerCPSelectionCallback obj, java.lang.Object client_data) Register a cluster publisher selection callback for this client.
java.lang.String	toString() Returns a string with the client information in a form suitable for human viewing.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

BrokerClusterPublisher

public BrokerClusterPublisher(java.lang.String broker_host,
                              java.lang.String broker_name,
                              java.lang.String client_id,
                              java.lang.String client_group,
                              java.lang.String app_name,
                              BrokerConnectionDescriptor desc,
                              BrokerConnectionDescriptor mon_desc)
                       throws BrokerException

Creates a BrokerClusterPublisher. 'broker_name' can be null to request the default broker. 'client_id' cannot be null and 'desc' can be null to create a default connection.

Throws:

BrokerClientExistsException - If a client using the specified client ID already exists.

BrokerCommFailureException - If problems occur establishing the connection.

BrokerHostNotFoundException - If the specified host does not exist.

BrokerInvalidClientIdException - If the ID contains illegal characters.

BrokerInvalidNameException - If the app_name 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_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.

BrokerException

Method Detail

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(java.lang.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(java.lang.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(java.lang.String dest_id,
                                           BrokerEvent event,
                                           int msecs)
                                    throws BrokerException

Deliver one request event and wait for replies. No exception is thrown if there is no client using the destination client ID. Creates a value for the 'tag' envelope field using makeTag(). Blocks until the replies are received or until the requested timeout (TIME_INFINITE (-1) for infinite timeout) is reached. In addition to the listed exceptions, any communications exception can be thrown.

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(java.lang.String broker_host,
                                                    java.lang.String broker_name,
                                                    java.lang.String client_id,
                                                    java.lang.String client_group,
                                                    java.lang.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(java.lang.String broker_host,
                                               java.lang.String broker_name,
                                               java.lang.String client_id,
                                               java.lang.String client_group,
                                               java.lang.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,
                                      java.lang.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,
                                       java.lang.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(java.lang.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(java.lang.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 java.lang.String getClientGroup()

Get the client group name.

getClientId

public java.lang.String getClientId()

Get the application client identifier.

getMonitorClientId

public java.lang.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 java.lang.String getApplicationName()

Get the application name.

canPublish

public boolean canPublish(java.lang.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 java.lang.String[] getCanPublishNames()
                                      throws BrokerException

Get the list of event type names which this client can publish or deliver. In addition to the listed exceptions, any communications exception can be thrown.

Throws:

BrokerInvalidClientException - If the client has been disconnected or destroyed.

BrokerClusterPublisherException - If no broker is available on the cluster pool.

BrokerException

getTerritoryName

public java.lang.String getTerritoryName()
                                  throws BrokerException

Get the territory name of the client's broker. Any communications exception can be thrown. Returns null if the client is not in a territory.

Throws:

BrokerInvalidClientException - If the client has been destroyed or disconnected.

BrokerClusterPublisherException - If no broker is available on the cluster pool.

BrokerException

getLastUsed

public java.lang.String getLastUsed()

Get the broker name on which the last cluster operation was executed.

toString

public java.lang.String toString()

Returns a string with the client information in a form suitable for human viewing.

Overrides:

toString in class java.lang.Object

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