COM.activesw.api.client
Class BrokerTransactionalClient

java.lang.Object
  COM.activesw.api.client.BrokerClient
      COM.activesw.api.client.BrokerTransactionalClient

public class BrokerTransactionalClient
extends BrokerClient

Field Summary

static int	BEGIN_NEW_TRANSACTION
static int	JOIN_EXISTING_TRANSACTION
static int	TRANSACTION_END_ABORT
static int	TRANSACTION_END_COMMIT
protected static int	TX_STATE_ABORTED
protected static int	TX_STATE_COMMITTED
protected static int	TX_STATE_END
protected static int	TX_STATE_OPEN
protected static int	TX_STATE_SUSPENDED
protected java.util.Map	txIdMap

Fields inherited from class COM.activesw.api.client.BrokerClient

ACK_AUTOMATIC, ACK_NONE, ACK_SELECTIVE, ACK_THROUGH, browser_open, CONNECT_STATE_CONNECTED, CONNECT_STATE_DISCONNECTED, CONNECT_STATE_RECONNECTED, CURRENT_API_VERSION, DEFAULT_TIMEOUT, DO_NOT_ACK, event_req_id, NO_SHARE_LIMIT, RECEIVE_SYNCHRONOUS, REPLY_FLAG_CONTINUE, REPLY_FLAG_END, REPLY_FLAG_START, REPLY_FLAG_START_AND_END, SYNCHRONOUS, TIME_INFINITE, TRANSACTION_LEVEL_ANY, TRANSACTION_LEVEL_BASIC, TRANSACTION_LEVEL_CONVERSATIONAL, TRANSACTION_LEVEL_PSEUDO, TRANSACTION_MODE_COMMIT, TRANSACTION_MODE_ROLLBACK, TRANSACTION_MODE_SAVEPOINT, VERSION_31, VERSION_40, VERSION_50, VERSION_60, VERSION_61, VERSION_62, VERSION_63, VERSION_64, VERSION_65, VERSION_66, VERSION_71, VERSION_80, VERSION_82, VERSION_90

Constructor Summary

protected	BrokerTransactionalClient(java.lang.String broker_host, java.lang.String broker_name, java.lang.String client_id, BrokerConnectionDescriptor desc) Protected reconnect constructor.
	BrokerTransactionalClient(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) Creates a broker client that is transactional.

Method Summary

void	abort() aborts the open transaction on this client, discarding all work previously performed, and invalidates Rollback the transaction the context.
void	abort(long tx_id) aborts the open transaction on this client, discarding all work previously performed, and invalidates Rollback the transaction the context.
void	abort(java.lang.String external_id) aborts all the transactions with the given external id, discarding all work previously performed Rollback the transaction the context.
void	abort(java.lang.String[] external_ids) Aborts the transaction(s) which has/have the specified external_id.
static void	abortAll(BrokerTransactionalClient[] tx_clients) aborts the given list of open transactions, discarding all work previously performed, and invalidates the context.
static void	abortAll(BrokerTransactionalClient[] tx_clients, java.lang.String external_id) aborts all the transactions known to this broker with the given external_id Discarding all work previously performed, This method is used in distributed transactions.
void	acknowledge(long seqn) Acknowledge the single event specified.
void	acknowledge(long[] seqns) Acknowledge the array of events with the given seqn numbers.
void	acknowledgeThrough(long seqn) Acknowledges all events through the event specified.
long	beginTransaction(java.lang.String external_id) Starts a transaction.
long	beginTransaction(java.lang.String external_id, int flag, int timeout) Starts a transaction.
void	cancelCallbackForSubId(int sub_id) Cancel the client's specific callback for a subscription id.
void	cancelCallbackForTag(int tag) Cancel the client's specific callback for a tag value.
void	cancelCallbacks() Cancel all callbacks for the client.
void	cancelGetEvents()
void	commit() commits the open transaction.
void	commit(long tx_id) commits the open transaction.
void	commit(java.lang.String external_id) commits the open transaction(s) which has/have the specified external_id.
void	commit(java.lang.String[] external_ids) commits the open transaction(s) which has/have the specified external_id.
static void	commitAll(BrokerTransactionalClient[] tx_clients) commits the given list of open transaction.
static void	commitAll(BrokerTransactionalClient[] tx_clients, java.lang.String external_id) commits all the open transaction with the given external_id.
void	deliver(java.lang.String dest_id, BrokerEvent event) Deliver one event in the given transaction.
void	deliver(java.lang.String dest_id, BrokerEvent[] events) Deliver multiple events on the given transaction.
void	deliverAckReplyEvent(BrokerEvent request_event, long publish_seqn) Delivers an Adapter::ack event to the originator of the specified event, which is most likely a request event for given transaction.
void	deliverErrorReplyEvent(BrokerEvent request_event, BrokerEvent error_event) Give a single error event to the broker to all be delivered to the client that published the 'request_event' for given transaction.
void	deliverNullReplyEvent(BrokerEvent request_event, java.lang.String reply_event_type_name, long publish_seqn) 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.
int	deliverPartialReplyEvents(BrokerEvent request_event, BrokerEvent[] events, int flag, int token) Give multiple events to the broker to all be delivered to the client that published the 'request_event' for the given transaction.
void	deliverReplyEvent(BrokerEvent request_event, BrokerEvent event) Give a single event to the broker to all be delivered to the client that published the 'request_event' for the given transaction.
void	deliverReplyEvents(BrokerEvent request_event, BrokerEvent[] events) Give multiple events to the broker to all be delivered to the client that published the 'request_event' for given transaction.
BrokerEvent[]	deliverRequestAndWait(java.lang.String dest_id, BrokerEvent event, int msecs) Deliver one request event and wait for replies.
void	deliverWithAck(java.lang.String dest_id, BrokerEvent[] events, int ack_type, long[] ack_seqn) Deliver multiple events on the given transaction.
static void	dispatch(int msecs)
static void	endAll(BrokerTransactionalClient[] tx_clients, int end_state)
static void	endAll(BrokerTransactionalClient[] tx_clients, java.lang.String externalId, int end_state) Ends the given list of current transactions.
void	endTransaction(long tx_id, int end_state)
void	endTransaction(java.lang.String external_id, int end_state) Ends the current transaction.
void	forget(long tx_id) Forget the specified heuristically completed transaction.
void	forget(java.lang.String external_id) Forget the specified heuristically completed transaction.
static void	forgetAll(BrokerTransactionalClient[] tx_clients, java.lang.String external_id) Forget the transaction with the specified external_id in the given list of transactional clients.
static void	forgetAll(BrokerTransactionalClient tx_client, java.lang.String[] external_ids) Forget the transaction with the specified external_id in the given list of transactional clients.
BrokerEvent	getEvent(int msecs) Gets a single event from this client's queue, that is part of the given open transaction context.
BrokerEvent[]	getEvents(int max_events, int msecs) Gets one or more events from this client's queue, that is a part of the the give open transaction context.
BrokerEvent[]	getEvents(int max_events, long seqn, int msecs) This request gets processed only after the BrokerTransactionalClient is is committed.
java.lang.String	getExternalId() Used by the application or an external manager to identify the context.
long	getId() used by the broker to identify the context.
long	getId(java.lang.String external_id)
COM.activesw.api.client.BrokerJMSEvent[]	getJMSEvents(int max_events, long seqn, int msecs) This request gets processed only after the BrokerTransactionalClient is is committed.
int	getTransactionTimeout()
COM.activesw.api.client.BrokerXAResource	getXAResource()
static void	interruptDispatch()
void	interruptGetEvents() Interrupt the current getEvents() call for the client.
void	jmsClientPublish(COM.activesw.api.client.BrokerJMSEvent[] events, boolean async) Publish multiple events on the given transaction.
static void	mainLoop()
void	negativeAcknowledge(long seqn) Negatively acknowledge the single event specified.
void	negativeAcknowledge(long[] seqns) Negative acknowledge the array of events with the given seqn numbers.
static BrokerClient	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) Attempts to create the broker client.If the creation fails because the client already exists, then it reconnects to the client instead.
static BrokerTransactionalClient	newOrReconnectTransactionalClient(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) Attempts to create the transactional client.
int	prepare(long tx_id) Prepares the transactions with the specified broker transaction id for commit.
int	prepare(java.lang.String external_id) Prepares the transactions with the specified external_id for commit.
static void	prepareAll(BrokerTransactionalClient[] tx_clients, java.lang.String external_id) Prepare the specified transaction for commit.
static void	prepareAll(BrokerTransactionalClient tx_client, java.lang.String[] external_ids) Prepare the specified list of transactions for commit.
void	prime(int num) Tell the client to send a request for events but not block.
void	primeWithAck(int num)
void	publish(BrokerEvent event) Publish one event with the given transaction id.
void	publish(COM.activesw.api.client.BrokerJMSEvent event) Publish one event with the given transaction id.
BrokerEvent[]	publishRequestAndWait(BrokerEvent event, int msecs) Publish one request event to the broker and wait for replies.
void	publishWithAck(BrokerEvent[] events, int ack_type, long[] ack_seqn) Publish multiple events for the given transaction.
static BrokerClient	reconnect(java.lang.String broker_host, java.lang.String broker_name, java.lang.String client_id, BrokerConnectionDescriptor desc) Reconnects a client.
static BrokerTransactionalClient	reconnectTransactionalClient(java.lang.String broker_host, java.lang.String broker_name, java.lang.String client_id, BrokerConnectionDescriptor desc) Reconnects a transactional client.
java.lang.String[]	recover(int flag) Get the list of user defined, externally generated transaction identifiers that the client has prepared transactions for.
void	registerCallback(BrokerCallback obj, java.lang.Object client_data) Register a general callback for events received by this client.
void	registerCallbackForSubId(int sub_id, BrokerCallback obj, java.lang.Object client_data) Register a specific callback for events received by this client which matched a given subscription ID.
void	registerCallbackForTag(int tag, boolean cancel_when_done, BrokerCallback obj, java.lang.Object client_data) Register a specific callback for events received by this client which have the _env.tag field set to the specified value.
void	resume(long tx_id) Resume a suspended transaction.
void	resume(java.lang.String external_id) Resume a suspended transaction.
static void	resumeAll(BrokerTransactionalClient[] tx_clients, java.lang.String external_id) Resume the given list of suspended transactions.
protected void	setId(long tx_id) used by the broker to identify the context.
void	setTransactionId(long tx_id, java.lang.String external_id) Associates a Broker transaction with an external identifier.
void	setTransactionId(java.lang.String external_id) Associates the current Broker transaction with an external identifier.
void	setTransactionTimeout(int seconds)
protected void	setXAResource(COM.activesw.api.client.BrokerXAResource bXAResource)
static void	stopMainLoop()
void	suspend(long tx_id) Suspend the transaction with the given external_id.
void	suspend(java.lang.String external_id) Suspend the transaction with the given external_id.
static void	suspendAll(BrokerTransactionalClient[] tx_clients, java.lang.String external_id) Suspend the given list of current transactions.
static void	threadedCallbacks(boolean enabled)

Methods inherited from class COM.activesw.api.client.BrokerClient

acknowledge, acknowledge, acknowledgeThrough, beginAdapterTransaction, browseEvents, cancelCheckForEvents, cancelSubscription, cancelSubscription, cancelSubscriptions, canPublish, canSubscribe, checkForEvents, clearQueue, createClientQueueBrowser, deliver, deliver, deliverAckReplyEvent, deliverErrorReplyEvent, deliverNullReplyEvent, deliverPartialReplyEvents, deliverReplyEvent, deliverReplyEvents, deliverWithAck, destroy, disconnect, doesSubscriptionExist, endAdapterTransaction, endExt, endTr, endTx, finalize, forgetExt, forgetTx, getAccessLabel, getApiVersionNumber, getApplicationName, getAsyncExceptionListener, getBrokerHost, getBrokerName, getBrokerPort, getBrokerSSLCertificate, getBrokerVersionNumber, getBrokerVersionString, getCanPublishNames, getCanPublishTypeDefs, getCanSubscribeNames, getCanSubscribeTypeDefs, getClientGroup, getClientId, getClientInfo, getClientInfoset, getClientSSLEncryptionLevel, getConnectionDescriptor, getDefaultBrokerPort, getDefaultTimeout, getEvent, getEventLogging, getEvents, getEvents, getEventTypeDef, getEventTypeDefs, getEventTypeInfoset, getEventTypeInfosetNames, getEventTypeInfosets, getEventTypeNames, getEventTypeNames, getJMSClientInfoset, getJMSEvents, getLastPublishSequenceNumber, getLogAcknowledgeNames, getLogPublishNames, getPlatformInfo, getPlatformInfoKeys, getQueueLength, getScopeNames, getServerFilterCollationLocale, getSess, getSessionFilters, getStateShareLimit, getSubscriptions, getTerritoryName, getTxTimeout, incrementRedeliveryCount, interruptCheckForEvents, isClientPending, isConnected, isPending, jmsClientPublish, makeSubId, makeTag, makeTransactionId, makeUniqueSubId, negativeAcknowledgeInternal, newSubscription, newSubscription, newSubscription, newSubscriptions, newTx, ping, ping, poll, prepareExt, prepareTx, prime, prime, primeAllClients, primeAllClients, primeWithAck, publish, publish, publish, publishWithAck, recoverTx, registerConnectionCallback, resendUnacknowledgedEvents, resetSessionFilters, setAsyncExceptionListener, setAutomaticControlLabel, setClientInfoset, setDefaultClientTimeout, setPlatformInfo, setSessionFilter, setSessionFilters, setStateShareLimit, setTxId, setTxTimeout, toString

Methods inherited from class java.lang.Object

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

Field Detail

BEGIN_NEW_TRANSACTION

public static final int BEGIN_NEW_TRANSACTION

See Also:

Constant Field Values

JOIN_EXISTING_TRANSACTION

public static final int JOIN_EXISTING_TRANSACTION

See Also:

Constant Field Values

TRANSACTION_END_COMMIT

public static final int TRANSACTION_END_COMMIT

See Also:

Constant Field Values

TRANSACTION_END_ABORT

public static final int TRANSACTION_END_ABORT

See Also:

Constant Field Values

TX_STATE_OPEN

protected static final int TX_STATE_OPEN

See Also:

Constant Field Values

TX_STATE_END

protected static final int TX_STATE_END

See Also:

Constant Field Values

TX_STATE_COMMITTED

protected static final int TX_STATE_COMMITTED

See Also:

Constant Field Values

TX_STATE_ABORTED

protected static final int TX_STATE_ABORTED

See Also:

Constant Field Values

TX_STATE_SUSPENDED

protected static final int TX_STATE_SUSPENDED

See Also:

Constant Field Values

txIdMap

protected java.util.Map txIdMap

Constructor Detail

BrokerTransactionalClient

public BrokerTransactionalClient(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)
                          throws BrokerException

Creates a broker client that is transactional. 'broker_name' can be null to request the default broker. 'client_id' can be null to request the broker to create an identifier (usually used with destroy-on-disconnect clients). '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

BrokerTransactionalClient

protected BrokerTransactionalClient(java.lang.String broker_host,
                                    java.lang.String broker_name,
                                    java.lang.String client_id,
                                    BrokerConnectionDescriptor desc)
                             throws BrokerException

Protected reconnect constructor. See reconnect() for details.

Throws:

BrokerException

Method Detail

reconnectTransactionalClient

public static BrokerTransactionalClient reconnectTransactionalClient(java.lang.String broker_host,
                                                                     java.lang.String broker_name,
                                                                     java.lang.String client_id,
                                                                     BrokerConnectionDescriptor desc)
                                                              throws BrokerException

Reconnects a transactional client. 'broker_name' can be null to request the default broker. 'desc' can be null to request a default connection. The state sharing flag in the descriptor is ignored by this call. Whether or not the client shares state can only be set when making a new client. For normal clients, only one active connection can be made to the broker for a given client_id, so an error can be returned on reconnect if the client_id is already in use. For clients with shared state, multiple reconnects to the client_id can be made, but an error can be returned if the share limit is exceeded.

Returns:

a BrokerTransactionalClient

Throws:

BrokerClientContentionException - If the client ID is already in use by another client. For shared state clients, this means the maximum number of reconnects has been exceeded.

BrokerCommFailureException - If problems occur establishing the connection.

BrokerHostNotFoundException - If the specified host does not exist.

BrokerNoPermissionException - If permission to join the specified client group is denied.

BrokerNotRunningException - If the host exists but no broker is running on that host.

BrokerNullParameterException - If broker_host or client_id are null.

BrokerSecurityException - If a secure connection is attempted but is rejected by the broker.

BrokerUnknownBrokerNameException - If the specified broker does not exist. If broker_name is null, this indicates that there is no default broker.

BrokerUnknownClientIdException - If the specified client ID does not exist on the broker.

BrokerException

reconnect

public static BrokerClient reconnect(java.lang.String broker_host,
                                     java.lang.String broker_name,
                                     java.lang.String client_id,
                                     BrokerConnectionDescriptor desc)
                              throws BrokerException

Reconnects a client. 'broker_name' can be null to request the default broker. 'desc' can be null to request a default connection. The state sharing flag in the descriptor is ignored by this call. Whether or not the client shares state can only be set when making a new client. For normal clients, only one active connection can be made to the broker for a given client_id, so an error can be returned on reconnect if the client_id is already in use. For clients with shared state, multiple reconnects to the client_id can be made, but an error can be returned if the share limit is exceeded. The returned BrokerClient needs to be typecasted to work with transactions.

Returns:

a BrokerClient

Throws:

BrokerClientContentionException - If the client ID is already in use by another client. For shared state clients, this means the maximum number of reconnects has been exceeded.

BrokerCommFailureException - If problems occur establishing the connection.

BrokerHostNotFoundException - If the specified host does not exist.

BrokerNoPermissionException - If permission to join the specified client group is denied.

BrokerNotRunningException - If the host exists but no broker is running on that host.

BrokerNullParameterException - If broker_host or client_id are null.

BrokerSecurityException - If a secure connection is attempted but is rejected by the broker.

BrokerUnknownBrokerNameException - If the specified broker does not exist. If broker_name is null, this indicates that there is no default broker.

BrokerUnknownClientIdException - If the specified client ID does not exist on the broker.

BrokerException

newOrReconnectTransactionalClient

public static BrokerTransactionalClient newOrReconnectTransactionalClient(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)
                                                                   throws BrokerException

Attempts to create the transactional client. If the creation fails because the transactional client already exists, then it reconnects to the existing transactional 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.

Returns:

a BrokerTransactionalClient

Throws:

BrokerClientContentionException - If the client ID is already in use by another client. For shared state clients, this means the maximum number of reconnects has been exceeded.

BrokerCommFailureException - If problems occur establishing the connection.

BrokerHostNotFoundException - If the specified host does not exist.

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

newOrReconnect

public static BrokerClient 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)
                                   throws BrokerException

Attempts to create the broker 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. The returned BrokerClient needs to be typecasted to work with transactions.

Returns:

a BrokerClient

Throws:

BrokerClientContentionException - If the client ID is already in use by another client. For shared state clients, this means the maximum number of reconnects has been exceeded.

BrokerCommFailureException - If problems occur establishing the connection.

BrokerHostNotFoundException - If the specified host does not exist.

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

beginTransaction

public long beginTransaction(java.lang.String external_id)
                      throws BrokerException

Starts a transaction. The operations done after this call will be performed after the commit method is called. If aborted, all the operations after this call will be ignored.

Parameters:

external_id - (optional) - A user defined, externally generated transaction identifier

Throws:

BrokerInvalidClientException

BrokerException

beginTransaction

public long beginTransaction(java.lang.String external_id,
                             int flag,
                             int timeout)
                      throws BrokerException

Starts a transaction. The operations done after this call will be performed after the commit method is called. If aborted, all the operations after this call will be ignored. This method is used for distributed transactions.

Parameters:

external_id - - A user defined, externally generated transaction identifier

flag - - this will contain information if this is a new transction or joining an existing transaction.

timeout -

Throws:

BrokerInvalidClientException

BrokerException

endTransaction

public void endTransaction(java.lang.String external_id,
                           int end_state)
                    throws BrokerException

Ends the current transaction. The transactional Broker client will no longer have a current transaction and new transactions may be started. This method can be used to indicate either success or failure. When called with BrokerTransactionalClient.TRANSACTION_END_ABORT the transaction can only be aborted. When called with BrokerTransactionalClient.TRANSACTION_END_COMMIT the transaction can be prepared, committed or aborted. Calling this method is optional. A transaction can be directly prepared, committed or aborted.

Parameters:

external_id - - A user defined, externally generated transaction identifier

end_state - either BrokerTransactionalClient.TRANSACTION_END_ABORT or BrokerTransactionalClient.TRANSACTION_END_COMMIT

Throws:

BrokerException

endTransaction

public void endTransaction(long tx_id,
                           int end_state)
                    throws BrokerException

Throws:

BrokerException

endAll

public static void endAll(BrokerTransactionalClient[] tx_clients,
                          java.lang.String externalId,
                          int end_state)
                   throws BrokerException

Ends the given list of current transactions. The transactional Broker clients will no longer have a current transaction and new transactions may be started. This method can be used to indicate either success or failure. When called with BrokerTransactionalClient.TX_STATE_FAILURE the transaction can only be aborted. When called with BrokerTransactionalClient.TX_STATE_SUCCESS the transaction can be prepared, committed or aborted. Calling this method is optional. A transaction can be directly prepared, committed or aborted.

Parameters:

tx_clients - the list of transactions to end

end_state - either BrokerTransactionalClient.TX_STATE_SUCCESS or BrokerTransactionalClient.TX_STATE_FAILURE

Throws:

BrokerException

endAll

public static void endAll(BrokerTransactionalClient[] tx_clients,
                          int end_state)
                   throws BrokerException

Throws:

BrokerException

prepare

public int prepare(java.lang.String external_id)
            throws BrokerException

Prepares the transactions with the specified external_id for commit. If prepare fails the transaction can only be aborted. Prepared transactions can be recovered by calling recover. Calling this method is optional. A transaction can be directly committed or aborted.

Parameters:

external_id - a user defined, externally generated transaction identifier

Throws:

BrokerException

prepare

public int prepare(long tx_id)
            throws BrokerException

Prepares the transactions with the specified broker transaction id for commit. If prepare fails the transaction can only be aborted. Prepared transactions can be recovered by calling recover. Calling this method is optional. A transaction can be directly committed or aborted.

Parameters:

tx_id - The transaction identifier returned by the Broker during beginTransaction

Throws:

BrokerException

prepareAll

public static void prepareAll(BrokerTransactionalClient[] tx_clients,
                              java.lang.String external_id)
                       throws BrokerException

Prepare the specified transaction for commit. If prepare fails the transaction can only be aborted. Prepared transactions can be recovered by calling recover. Calling this method is optional. A transaction can be directly committed or aborted.

Parameters:

external_id - a user defined, externally generated transaction identifier

Throws:

BrokerException

prepareAll

public static void prepareAll(BrokerTransactionalClient tx_client,
                              java.lang.String[] external_ids)
                       throws BrokerException

Prepare the specified list of transactions for commit. If prepare fails the transaction can only be aborted. Prepared transactions can be recovered by calling recover. Calling this method is optional. A transaction can be directly committed or aborted.

Parameters:

tx_client - client that participated in the transaction and need to be prepared

external_ids - list of external ids of open transactions that need to be prepared

Throws:

BrokerException

commit

public void commit()
            throws BrokerException

commits the open transaction. All work performed on this context will be finalized. All the outstanding events in this clients queue will be acknowledged.

Throws:

BrokerTxClosedException

BrokerInvalidClientException

BrokerInvalidTxException

BrokerException

commit

public void commit(long tx_id)
            throws BrokerException

commits the open transaction. All work performed on this context will be finalized. All the outstanding events in this clients queue will be acknowledged.

Throws:

BrokerTxClosedException

BrokerInvalidClientException

BrokerInvalidTxException

BrokerException

commit

public void commit(java.lang.String external_id)
            throws BrokerException

commits the open transaction(s) which has/have the specified external_id. All work performed on this context will be finalized. All the outstanding events in this clients queue will be acknowledged. commit() can be called before or after endTransaction or prepareTransaction.

Throws:

BrokerTxClosedException

BrokerInvalidClientException

BrokerInvalidTxException

BrokerException

commit

public void commit(java.lang.String[] external_ids)
            throws BrokerException

commits the open transaction(s) which has/have the specified external_id. All work performed on this context will be finalized. All the outstanding events in this clients queue will be acknowledged. commit() can be called before or after endTransaction or prepareTransaction. This method is typically invoked on recovered transactions for which a client has called prepare.

Throws:

BrokerTxClosedException

BrokerInvalidClientException

BrokerInvalidTxException

BrokerException

commitAll

public static void commitAll(BrokerTransactionalClient[] tx_clients)
                      throws BrokerException

commits the given list of open transaction. All work performed on these contexts will be finalized. All the outstanding events in these client's queues will be acknowledged. Used in local transactions only.

Throws:

BrokerTxClosedException

BrokerInvalidClientException

BrokerInvalidTxException

BrokerException

commitAll

public static void commitAll(BrokerTransactionalClient[] tx_clients,
                             java.lang.String external_id)
                      throws BrokerException

commits all the open transaction with the given external_id. All work performed in the transactions on the broker this client is connected to and which have a matching external_id will be finalized. All the outstanding events in these client's queues will be acknowledged. Used in distributed transactions.

Parameters:

tx_clients - - list of BrokerTransactionalClients

external_id - a user defined, externally generated transaction identifier, a value must be supplied.

Throws:

BrokerTxClosedException

BrokerInvalidClientException

BrokerInvalidTxException

BrokerException

abort

public void abort()
           throws BrokerException

aborts the open transaction on this client, discarding all work previously performed, and invalidates Rollback the transaction the context. Not used in distributed transactions.

Throws:

BrokerTxClosedException

BrokerInvalidClientException

BrokerInvalidTxException

BrokerException

abort

public void abort(long tx_id)
           throws BrokerException

aborts the open transaction on this client, discarding all work previously performed, and invalidates Rollback the transaction the context. Not used in distributed transactions.

Throws:

BrokerTxClosedException

BrokerInvalidClientException

BrokerInvalidTxException

BrokerException

abort

public void abort(java.lang.String external_id)
           throws BrokerException

aborts all the transactions with the given external id, discarding all work previously performed Rollback the transaction the context. Used in case of distributed transactions.

Parameters:

external_id - -a user defined, externally generated transaction identifier, mandatory

Throws:

BrokerTxClosedException

BrokerInvalidClientException

BrokerInvalidTxException

BrokerException

abort

public void abort(java.lang.String[] external_ids)
           throws BrokerException

Aborts the transaction(s) which has/have the specified external_id. abort() can be called before or after endTransaction or prepareTransaction. This method is typically invoked on recovered transactions for which a client has called prepare.

Throws:

BrokerTxClosedException

BrokerInvalidClientException

BrokerInvalidTxException

BrokerException

abortAll

public static void abortAll(BrokerTransactionalClient[] tx_clients)
                     throws BrokerException

aborts the given list of open transactions, discarding all work previously performed, and invalidates the context. Rollback the transaction. Used for local transactions only.

Parameters:

tx_clients - - list of BrokerTransactionalClients

Throws:

BrokerTxClosedException

BrokerInvalidClientException

BrokerInvalidTxException

BrokerException

abortAll

public static void abortAll(BrokerTransactionalClient[] tx_clients,
                            java.lang.String external_id)
                     throws BrokerException

aborts all the transactions known to this broker with the given external_id Discarding all work previously performed, This method is used in distributed transactions. abort() can be called at any stage once the transaction has been started using beginTransaction. You can call abort() after endTransaction()or prepareTransaction(). Rollback the transaction.

Parameters:

tx_clients - - list of BrokerTransactionalClients

external_id - a user defined, externally generated transaction identifier

Throws:

BrokerTxClosedException

BrokerInvalidClientException

BrokerInvalidTxException

BrokerException

forget

public void forget(java.lang.String external_id)
            throws BrokerException

Forget the specified heuristically completed transaction. The transaction will have timed out within the Broker transaction manager. This method is typically invoked on recovered transactions for which a client has called prepare.

Parameters:

external_id - a user defined, externally generated transaction identifier

Throws:

BrokerException

forget

public void forget(long tx_id)
            throws BrokerException

Forget the specified heuristically completed transaction. The transaction will have timed out within the Broker transaction manager. This method is typically invoked on recovered transactions for which a client has called prepare. Used in case of distributed transactions.

Parameters:

tx_id - the Broker transaction context returned by beginTransaction

Throws:

BrokerException

forgetAll

public static void forgetAll(BrokerTransactionalClient[] tx_clients,
                             java.lang.String external_id)
                      throws BrokerException

Forget the transaction with the specified external_id in the given list of transactional clients. The transaction will have timed out within the Broker transaction manager. This method is typically invoked on recovered transactions for which a client has called prepare. Used only in case of distributed transactions.

Parameters:

tx_clients - - list of BrokerTransactionalClients

external_id - a user defined, externally generated transaction identifier

Throws:

BrokerException

forgetAll

public static void forgetAll(BrokerTransactionalClient tx_client,
                             java.lang.String[] external_ids)
                      throws BrokerException

Forget the transaction with the specified external_id in the given list of transactional clients. The transaction will have timed out within the Broker transaction manager. This method is typically invoked on recovered transactions for which a client has called prepare. Used only in case of distributed transactions.

Parameters:

tx_client - - list of BrokerTransactionalClients

external_ids - a user defined, externally generated transaction identifier

Throws:

BrokerException

setTransactionId

public void setTransactionId(long tx_id,
                             java.lang.String external_id)
                      throws BrokerException

Associates a Broker transaction with an external identifier.

Parameters:

tx_id - a Broker transaction identifier

external_id - a user defined, externally generated transaction identifier

Throws:

BrokerInvalidTxException - if the transaction is not found, the transaction is not open or if an external identifier already exists for the transaction.

BrokerException - for all other errors.

setTransactionId

public void setTransactionId(java.lang.String external_id)
                      throws BrokerException

Associates the current Broker transaction with an external identifier.

Parameters:

external_id - a user defined, externally generated transaction identifier

Throws:

BrokerInvalidTxException - if the transaction is not found, the transaction is not open or if an external identifier already exists for the transaction.

BrokerException - for all other errors.

recover

public java.lang.String[] recover(int flag)
                           throws BrokerException

Get the list of user defined, externally generated transaction identifiers that the client has prepared transactions for. Used only in case of distributed transactions.

Returns:

a list of user defined, externally generated transaction identifiers

Throws:

BrokerException

suspend

public void suspend(java.lang.String external_id)
             throws BrokerException

Suspend the transaction with the given external_id. The transaction can be made active again by calling resume. Used in case of distributed transactions.

Throws:

BrokerException

suspend

public void suspend(long tx_id)
             throws BrokerException

Suspend the transaction with the given external_id. he transaction can be made active again by calling resume. Used in case of distributed transactions.

Throws:

BrokerException

suspendAll

public static void suspendAll(BrokerTransactionalClient[] tx_clients,
                              java.lang.String external_id)
                       throws BrokerException

Suspend the given list of current transactions. The transactions can be made active again by calling resume. Used only in case of distributed transactions.

Parameters:

tx_clients - the list of transactions to suspend

Throws:

BrokerException

resume

public void resume(java.lang.String external_id)
            throws BrokerException

Resume a suspended transaction. Used only in case of distributed transactions.

Parameters:

external_id - the Broker transaction context returned by beginTransaction

Throws:

BrokerException

resume

public void resume(long tx_id)
            throws BrokerException

Resume a suspended transaction. Used only in case of distributed transactions.

Parameters:

tx_id - the Broker transaction context returned by beginTransaction

Throws:

BrokerException

resumeAll

public static void resumeAll(BrokerTransactionalClient[] tx_clients,
                             java.lang.String external_id)
                      throws BrokerException

Resume the given list of suspended transactions. Used only in case of distributed transactions.

Parameters:

external_id - a user defined, externally generated transaction identifier

tx_clients - the list of transactions to resume

Throws:

BrokerException

getId

public long getId(java.lang.String external_id)

getId

public long getId()

used by the broker to identify the context. It is a globally unique identifier and remains constant for the life of the context.

Returns:

the unique identifier assigned by broker for this transaction

setId

protected void setId(long tx_id)

used by the broker to identify the context. It is a globally unique identifier and remains constant for the life of the context.

getExternalId

public java.lang.String getExternalId()

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

Returns:

the external identifier

getTransactionTimeout

public int getTransactionTimeout()
                          throws BrokerException

Throws:

BrokerException

setTransactionTimeout

public void setTransactionTimeout(int seconds)
                           throws BrokerException

Throws:

BrokerException

getXAResource

public COM.activesw.api.client.BrokerXAResource getXAResource()

setXAResource

protected void setXAResource(COM.activesw.api.client.BrokerXAResource bXAResource)

publish

public void publish(BrokerEvent event)
             throws BrokerException

Publish one event with the given transaction id. The event is given to the broker to be given to all subscribing clients. In addition to the listed exceptions, any communications exception can be thrown.

Overrides:

publish in class BrokerClient

Throws:

BrokerInvalidClientException - If the client has been destroyed or disconnected.

BrokerInvalidEventException - If the event does not match its type definition.

BrokerNoPermissionException - If the client does not have permission to publish the event type.

BrokerNullParameterException - If event is null.

BrokerUnknownEventTypeException - If the event type for the event does not exist on the broker.

BrokerException

publish

public void publish(COM.activesw.api.client.BrokerJMSEvent event)
             throws BrokerException

Publish one event with the given transaction id. The event is given to the broker to be given to all subscribing clients. In addition to the listed exceptions, any communications exception can be thrown.

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

jmsClientPublish

public void jmsClientPublish(COM.activesw.api.client.BrokerJMSEvent[] events,
                             boolean async)
                      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.

Overrides:

jmsClientPublish in class BrokerClient

Throws:

BrokerInvalidClientException - If the client has been destroyed or disconnected.

BrokerInvalidEventException - If any of the events does not match its type definition.

BrokerNoPermissionException - If the client does not have permission to publish all of the event types.

BrokerNullParameterException - If events is null, or if any element in the array is null.

BrokerUnknownEventTypeException - If the event type for any of the events does not exist on the broker.

BrokerException

publishWithAck

public void publishWithAck(BrokerEvent[] events,
                           int ack_type,
                           long[] ack_seqn)
                    throws BrokerException

Publish multiple events for the given transaction. Gives an array of events to the broker to be given to subscribing clients. Either all of the events or none of them are published. In addition to the listed exceptions, any communications exception can be thrown.

Overrides:

publishWithAck in class BrokerClient

Throws:

BrokerInvalidClientException - If the client has been destroyed or disconnected.

BrokerInvalidEventException - If any of the events does not match its type definition.

BrokerNoPermissionException - If the client does not have permission to publish all of the event types.

BrokerNullParameterException - If events is null, or if any element in the array is null.

BrokerOutOfRangeException - If the ack_type is not a legal ACK_* value.

BrokerUnknownEventTypeException - If the event type for any of the events does not exist on the broker.

BrokerInvalidAcknowledgementException - If ack_seqn if not a valid event to acknowledge. Events are not published.

BrokerException

deliver

public void deliver(java.lang.String dest_id,
                    BrokerEvent event)
             throws BrokerException

Deliver one event in the given transaction. Gives an event to the broker to be given to the client with the given client ID. No exception is thrown if there is no client using the destination client ID. In addition to the listed exceptions, any communications exception can be thrown.

Overrides:

deliver in class BrokerClient

Throws:

BrokerInvalidClientException - If the client has been destroyed or disconnected.

BrokerInvalidClientIdException - If the destination ID includes invalid characters.

BrokerInvalidEventException - If the event does not match its type definition.

BrokerNoPermissionException - If the client does not have permission to publish the event type.

BrokerNullParameterException - If event or dest_id are null.

BrokerUnknownEventTypeException - If the event type for the event does not exist on the broker.

BrokerException

deliver

public void deliver(java.lang.String dest_id,
                    BrokerEvent[] events)
             throws BrokerException

Deliver multiple events on the given transaction. Gives an array of events to the broker to have them all delivered to the client with the given client ID. Either all of the events or none of them are delivered. No exception is thrown if there is no client using the destination client ID. In addition to the listed exceptions, any communications exception can be thrown.

Overrides:

deliver in class BrokerClient

Throws:

BrokerInvalidClientException - If the client has been destroyed or disconnected.

BrokerInvalidClientIdException - If the destination ID includes invalid characters.

BrokerInvalidEventException - If any of the events does not match its type definition.

BrokerNoPermissionException - If the client does not have permission to publish all of the event types.

BrokerNullParameterException - If dest_id or events are null, or if any element in the array is null.

BrokerUnknownEventTypeException - If the event type for any of the events does not exist on the broker.

BrokerException

deliverWithAck

public void deliverWithAck(java.lang.String dest_id,
                           BrokerEvent[] events,
                           int ack_type,
                           long[] ack_seqn)
                    throws BrokerException

Deliver multiple events on the given transaction. Gives an array of events to the broker to have them all delivered to the client with the given client ID. Either all of the events or none of them are delivered. No exception is thrown if there is no client using the destination client ID. In addition to the listed exceptions, any communications exception can be thrown.

Overrides:

deliverWithAck in class BrokerClient

Throws:

BrokerInvalidClientException - If the client has been destroyed or disconnected.

BrokerInvalidClientIdException - If the destination ID includes invalid characters.

BrokerInvalidEventException - If any of the events does not match its type definition.

BrokerNoPermissionException - If the client does not have permission to publish all of the event types.

BrokerNullParameterException - If dest_id or events are null, or if any element in the array is null.

BrokerOutOfRangeException - If the ack_type is not a legal ACK_* value.

BrokerUnknownEventTypeException - If the event type for any of the events does not exist on the broker.

BrokerInvalidAcknowledgementException - If ack_seqn if not a valid event to acknowledge. Events are not published.

BrokerException

deliverAckReplyEvent

public void deliverAckReplyEvent(BrokerEvent request_event,
                                 long publish_seqn)
                          throws BrokerException

Delivers an Adapter::ack event to the originator of the specified event, which is most likely a request event for given transaction. Properly sets the tag, trackId,businessContext and activation envelope fields to match that of the request. Properly uses the replyTo envelope field if set. Set publish_seqn to zero (0) when not using publish sequence numbers in your application. In addition to the listed exceptions, any communications exception can be thrown.

Overrides:

deliverAckReplyEvent in class BrokerClient

Throws:

BrokerInvalidClientException - If the client has been destroyed or disconnected.

BrokerInvalidEventException - If the event was not received from the broker.

BrokerNoPermissionException - If the client does not have permission to publish the Adapter::ack event type.

BrokerNullParameterException - If request_event is null.

BrokerException

deliverNullReplyEvent

public void deliverNullReplyEvent(BrokerEvent request_event,
                                  java.lang.String reply_event_type_name,
                                  long publish_seqn)
                           throws BrokerException

Delivers a null event of type 'reply_event_type_name' to the originator of the specified event, which is most likely a request event for given transaction. Properly sets envelope tag, trackId, activation, businessContext, appSeqn, and appLastSeqn fields to indicate that this event is a null event. Properly uses the replyTo envelope field, if set. Null events are used to indicate that a request was successful and resulted in no data. Set publish_seqn to zero (0) when not using publish sequence numbers in your application. In addition to the listed exceptions, any communications exception can be thrown.

Overrides:

deliverNullReplyEvent in class BrokerClient

Throws:

BrokerInvalidClientException - If the client has been destroyed or disconnected.

BrokerInvalidEventException - If the event was not received from the broker.

BrokerNoPermissionException - If the client does not have permission to publish the reply event type.

BrokerNullParameterException - If request_event or reply_event_type_name are null.

BrokerUnknownEventTypeException - If the event type for the reply event does not exist on the broker.

BrokerException

deliverErrorReplyEvent

public void deliverErrorReplyEvent(BrokerEvent request_event,
                                   BrokerEvent error_event)
                            throws BrokerException

Give a single error event to the broker to all be delivered to the client that published the 'request_event' for given transaction. No exception is thrown if there is no client using the destination clent ID. Properly sets the tag, trackId, activation, businessContext, appSeqn, and appLastSeqn envelope fields. Properly uses the errorsTo envelope field, if set. In addition to the listed exceptions, any communications exception can be thrown.

Overrides:

deliverErrorReplyEvent in class BrokerClient

Throws:

BrokerInvalidClientException - If the client has been destroyed or disconnected.

BrokerInvalidEventException - If the request event was not received from the broker, or the reply event does not match its event type.

BrokerNoPermissionException - If the client does not have permission to publish the reply event type.

BrokerNullParameterException - If request_event or event are null.

BrokerUnknownEventTypeException - If the event type for the reply event does not exist on the broker.

BrokerException

deliverReplyEvent

public void deliverReplyEvent(BrokerEvent request_event,
                              BrokerEvent event)
                       throws BrokerException

Give a single event to the broker to all be delivered to the client that published the 'request_event' for the given transaction. No exception is thrown if there is no client using the destination clent ID. Properly sets the tag, trackId, activation, businessContext, appSeqn, and appLastSeqn envelope fields. Properly uses the replyTo envelope field, if set. In addition to the listed exceptions, any communications exception can be thrown.

Overrides:

deliverReplyEvent in class BrokerClient

Throws:

BrokerInvalidClientException - If the client has been destroyed or disconnected.

BrokerInvalidEventException - If the request event was not received from the broker, or the reply event does not match its event type.

BrokerNoPermissionException - If the client does not have permission to publish the reply event type.

BrokerNullParameterException - If request_event or event are null.

BrokerUnknownEventTypeException - If the event type for the reply event does not exist on the broker.

BrokerException

deliverReplyEvents

public void deliverReplyEvents(BrokerEvent request_event,
                               BrokerEvent[] events)
                        throws BrokerException

Give multiple events to the broker to all be delivered to the client that published the 'request_event' for given transaction. No exception is thrown if there is no client using the destination client ID. Either all of the events or none of them are delivered. Properly sets the tag, trackId, activation, businessContext, appSeqn, and appLastSeqn envelope fields. Properly uses the replyTo envelope field, if set. In addition to the listed exceptions, any communications exception can be thrown.

Overrides:

deliverReplyEvents in class BrokerClient

Throws:

BrokerInvalidClientException - If the client has been destroyed or disconnected.

BrokerInvalidEventException - If the request event was not received from the broker, or any of the reply events does not match its event type.

BrokerNoPermissionException - If the client does not have permission to publish all of the reply events.

BrokerNullParameterException - If request_event or events are null, or if any element in the events array is null.

BrokerUnknownEventTypeException - If the event type for any of the reply events does not exist on the broker.

BrokerException

deliverPartialReplyEvents

public int deliverPartialReplyEvents(BrokerEvent request_event,
                                     BrokerEvent[] events,
                                     int flag,
                                     int token)
                              throws BrokerException

Give multiple events to the broker to all be delivered to the client that published the 'request_event' for the given transaction. No exception is thrown if there is no client using the destination client ID. Either all of the events or none of them are delivered. Properly sets the tag, trackId, activation, businessContext, appSeqn, and appLastSeqn envelope fields. Properly uses the replyTo envelope field, if set. This function is used to deliver parts of a set of replies in groups. When called the first time, 'flag' should be REPLY_FLAG_START. After doing this, additional calls can be made with other flag values. During intermediate replies, 'flag' should be REPLY_FLAG_CONTINUE. On the final call, 'flag' should be REPLY_FLAG_END. Calling this function with 'flag' as REPLY_FLAG_START_AND_END allows the entire result to be passed to this function in one call. The 'token' parameter is ignored on REPLY_FLAG_START and REPLY_FLAG_START_AND_END. On other calls, the return value from the previous call should be passed. The return value exists to carry information between calls and has no meaning to the caller. In addition to the listed exceptions, any communications exception can be thrown.

Overrides:

deliverPartialReplyEvents in class BrokerClient

Throws:

BrokerInvalidClientException - If the client has been destroyed or disconnected.

BrokerInvalidEventException - If the request event was not received from the broker, or any of the reply events does not match its event type.

BrokerNoPermissionException - If the client does not have permission to publish all of the reply events.

BrokerNullParameterException - If request_event or events are null, or if any element in the events array is null.

BrokerOutOfRangeException - If flag is not a valid value.

BrokerUnknownEventTypeException - If the event type for any of the reply events does not exist on the broker.

BrokerException

cancelGetEvents

public void cancelGetEvents()
                     throws BrokerException

Overrides:

cancelGetEvents in class BrokerClient

Throws:

BrokerException

getEvent

public BrokerEvent getEvent(int msecs)
                     throws BrokerException

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

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

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

Overrides:

getEvent in class BrokerClient

Throws:

BrokerInterruptedException - If interruptGetEvents is used to stop the call.

BrokerInvalidClientException - If the client has been destroyed or disconnected.

BrokerOutOfRangeException - If msecs is less than -1.

BrokerTimeoutException - If the timeout is reached before an event arrives.

BrokerException

getEvents

public BrokerEvent[] getEvents(int max_events,
                               int msecs)
                        throws BrokerException

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

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

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

Overrides:

getEvents in class BrokerClient

Throws:

BrokerInterruptedException - If interruptGetEvents is used to stop the call.

BrokerInvalidClientException - If the client has been destroyed or disconnected.

BrokerOutOfRangeException - If msecs is less than -1, or max_events is less than zero.

BrokerTimeoutException - If the timeout is reached before any events arrive.

BrokerException

getEvents

public BrokerEvent[] getEvents(int max_events,
                               long seqn,
                               int msecs)
                        throws BrokerException

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

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

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

Overrides:

getEvents in class BrokerClient

Throws:

BrokerInterruptedException - If interruptGetEvents is used to stop the call.

BrokerInvalidClientException - If the client has been destroyed or disconnected.

BrokerOutOfRangeException - If msecs is less than -1, or max_events is less than zero.

BrokerTimeoutException - If the timeout is reached before any events arrive.

BrokerException

getJMSEvents

public COM.activesw.api.client.BrokerJMSEvent[] getJMSEvents(int max_events,
                                                             long seqn,
                                                             int msecs)
                                                      throws BrokerException

This request gets processed only after the BrokerTransactionalClient is is committed. If the given transaction is aborted this request will not be processed. The sequence number is the event to acknowledge through. A value of zero acknowledges all events. A value of DO_NOT_ACK (-1) will not acknowledge any events. Gets one or more events from this client's queue. Blocks for a given number of milliseconds then gives up. If 'msecs' is TIME_INFINITE (-1), it waits forever. Acknowledges all events up through the specified sequence number. If seqn is 0, then it acknowledges all events which have been retrieved previously that were not explicitly acknowledged. If seqn is DO_NOT_ACK (-1), then no events are acknowledged. The number of events being returned is not guaranteed to be 'max_events' even if there are more than than many events in the client's queue. Any number of events up to the value of 'max_events' may be returned. In addition to the listed exceptions, any communications exception can be thrown.

Overrides:

getJMSEvents in class BrokerClient

Throws:

BrokerInterruptedException - If interruptGetEvents is used to stop the call.

BrokerInvalidClientException - If the client has been destroyed or disconnected.

BrokerOutOfRangeException - If msecs is less than -1, or max_events is less than zero, or seqn is less than -1.

BrokerTimeoutException - If the timeout is reached before any events arrive.

BrokerException

interruptGetEvents

public void interruptGetEvents()
                        throws BrokerException

Interrupt the current getEvents() 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.

Overrides:

interruptGetEvents in class BrokerClient

Throws:

BrokerTxClosedException

BrokerInvalidClientException - If the client has been destroyed or disconnected.

BrokerException

publishRequestAndWait

public BrokerEvent[] publishRequestAndWait(BrokerEvent event,
                                           int msecs)
                                    throws BrokerException

Description copied from class: BrokerClient

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

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

Overrides:

publishRequestAndWait in class BrokerClient

Throws:

BrokerBadStateException - If this is called from within a callback function.

BrokerInvalidClientException - If the client has been destroyed or disconnected.

BrokerInvalidEventException - If the event does not match its type definition.

BrokerNoPermissionException - If the client does not have permission to publish the event type.

BrokerNullParameterException - If event is null.

BrokerUnknownEventTypeException - If the event type for the event does not exist on the broker.

BrokerException

deliverRequestAndWait

public BrokerEvent[] deliverRequestAndWait(java.lang.String dest_id,
                                           BrokerEvent event,
                                           int msecs)
                                    throws BrokerException

Description copied from class: BrokerClient

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

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

Overrides:

deliverRequestAndWait in class BrokerClient

Throws:

BrokerBadStateException - If this is called from within a callback function.

BrokerInvalidClientException - If the client has been destroyed or disconnected.

BrokerInvalidClientIdException - If the destination ID includes invalid characters.

BrokerInvalidEventException - If the event does not match its type definition.

BrokerNoPermissionException - If the client does not have permission to publish the event type.

BrokerNullParameterException - If dest_id or event are null.

BrokerUnknownEventTypeException - If the event type for the event does not exist on the broker.

BrokerException

registerCallback

public void registerCallback(BrokerCallback obj,
                             java.lang.Object client_data)
                      throws BrokerException

Description copied from class: BrokerClient

Register a general callback for events received by this client. Calling this on a client which already has an existing general callback will replace that callback. 'client_data' may be null.
The callback method will be called once if an event arrives which does not match a Tag callback, which has at least one subscription ID which does not match a SubId callback, or which is delivered to the application.
Use dispatch, mainLoop, or threadedCallbacks to make use of callbacks.

Overrides:

registerCallback in class BrokerClient

Throws:

BrokerInvalidClientException - If the client has been destroyed or disconnected.

BrokerNullParameterException - If obj is null.

BrokerException

registerCallbackForSubId

public void registerCallbackForSubId(int sub_id,
                                     BrokerCallback obj,
                                     java.lang.Object client_data)
                              throws BrokerException

Description copied from class: BrokerClient

Register a specific callback for events received by this client which matched a given subscription ID. Calling this on a client which already has an existing callback for the subscription ID will replace that callback. 'client_data' may be null.
Before calling this function, you must use registerCallback to register a general callback.
When using this call, it is suggested that each subscription be given a unique subscription ID.
The callback method will be called once if an event arrives which matched the specified subscription ID. It will be called more than once if the event matches the same subscription ID more than once. Note that it will never be called for events delivered to the client.

Overrides:

registerCallbackForSubId in class BrokerClient

Throws:

BrokerBadStateException - If no general callback has been registered.

BrokerInvalidClientException - If the client has been destroyed or disconnected.

BrokerNullParameterException - If obj is null.

BrokerOutOfRangeException - If sub_id is less than zero.

BrokerException

registerCallbackForTag

public void registerCallbackForTag(int tag,
                                   boolean cancel_when_done,
                                   BrokerCallback obj,
                                   java.lang.Object client_data)
                            throws BrokerException

Description copied from class: BrokerClient

Register a specific callback for events received by this client which have the _env.tag field set to the specified value. Calling this on a client which already has an existing callback for the tag value will replace that callback. 'client_data' may be null.
If 'cancel_when_done' is true, then the callback will be automatically cancelled when isLastReplyEvent returns true. Otherwise, the callback will stay in effect until explicitly cancelled.
Before calling this function, you must use registerCallback to register a general callback.
The callback method will be called once if an event arrives which matches the specified tag value. Note that this is usually true only for events delivered to the client.

Overrides:

registerCallbackForTag in class BrokerClient

Throws:

BrokerBadStateException - If no general callback has been registered.

BrokerInvalidClientException - If the client has been destroyed or disconnected.

BrokerNullParameterException - If obj is null.

BrokerException

cancelCallbacks

public void cancelCallbacks()
                     throws BrokerException

Description copied from class: BrokerClient

Cancel all callbacks for the client.

Overrides:

cancelCallbacks in class BrokerClient

Throws:

BrokerInvalidClientException - If the client has been destroyed or disconnected.

BrokerException

cancelCallbackForSubId

public void cancelCallbackForSubId(int sub_id)
                            throws BrokerException

Description copied from class: BrokerClient

Cancel the client's specific callback for a subscription id.

Overrides:

cancelCallbackForSubId in class BrokerClient

Throws:

BrokerInvalidClientException - If the client has been destroyed or disconnected.

BrokerException

cancelCallbackForTag

public void cancelCallbackForTag(int tag)
                          throws BrokerException

Description copied from class: BrokerClient

Cancel the client's specific callback for a tag value.

Overrides:

cancelCallbackForTag in class BrokerClient

Throws:

BrokerInvalidClientException - If the client has been destroyed or disconnected.

BrokerException

dispatch

public static void dispatch(int msecs)
                     throws BrokerException

Throws:

BrokerException

interruptDispatch

public static void interruptDispatch()
                              throws BrokerException

Throws:

BrokerException

mainLoop

public static void mainLoop()
                     throws BrokerException

Throws:

BrokerException

stopMainLoop

public static void stopMainLoop()
                         throws BrokerException

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.

Overrides:

acknowledge in class BrokerClient

Throws:

BrokerInvalidAcknowledgementException - If seqn is not a valid event to acknowledge.

BrokerInvalidClientException - If the client has been destroyed or disconnected.

BrokerOutOfRangeException - If seqn is less than zero.

BrokerException

acknowledge

public void acknowledge(long[] seqns)
                 throws BrokerException

Acknowledge the array of events with the given seqn numbers. A value of zero acknowledges all outstanding events. In addition to the listed exceptions, any communications exception can be thrown.

Overrides:

acknowledge in class BrokerClient

Throws:

BrokerInvalidAcknowledgementException - If seqn is not a valid event to acknowledge.

BrokerInvalidClientException - If the client has been destroyed or disconnected.

BrokerOutOfRangeException - If seqn is less than zero.

BrokerException

acknowledgeThrough

public void acknowledgeThrough(long seqn)
                        throws BrokerException

Acknowledges all events through the event specified. A value of zero acknowledges all outstanding events. In addition to the listed exceptions, any communications exception can be thrown.

Overrides:

acknowledgeThrough in class BrokerClient

Throws:

BrokerInvalidAcknowledgementException - If seqn is not a valid event to acknowledge.

BrokerInvalidClientException - If the client has been destroyed or disconnected.

BrokerOutOfRangeException - If seqn is less than zero.

BrokerException

negativeAcknowledge

public void negativeAcknowledge(long seqn)
                         throws BrokerException

Negatively acknowledge the single event specified. A value of zero acknowledges all outstanding events. In addition to the listed exceptions, any communications exception can be thrown.

Overrides:

negativeAcknowledge in class BrokerClient

Throws:

BrokerInvalidAcknowledgementException - If seqn is not a valid event to acknowledge.

BrokerInvalidClientException - If the client has been destroyed or disconnected.

BrokerOutOfRangeException - If seqn is less than zero.

BrokerException

negativeAcknowledge

public void negativeAcknowledge(long[] seqns)
                         throws BrokerException

Negative acknowledge the array of events with the given seqn numbers. In addition to the listed exceptions, any communications exception can be thrown.

Overrides:

negativeAcknowledge in class BrokerClient

Throws:

BrokerInvalidAcknowledgementException - If seqn is not a valid event to acknowledge.

BrokerInvalidClientException - If the client has been destroyed or disconnected.

BrokerOutOfRangeException - If seqn is less than zero.

BrokerException

threadedCallbacks

public static void threadedCallbacks(boolean enabled)
                              throws BrokerException

Throws:

BrokerException

prime

public void prime(int num)
           throws BrokerException

Tell the client to send a request for events but not block. Use this method on clients which have no callbacks and for which you intend to use isClientPending() to determine if events are waiting prior to calling getEvent(). If the requested number of events is less than one the number of events will default to one. In addition to the listed exceptions, any communications exception can be thrown.

Overrides:

prime in class BrokerClient

Parameters:

num - The requested number of events.

Throws:

BrokerInvalidClientException - If the client has been destroyed or disconnected.

BrokerException

primeWithAck

public void primeWithAck(int num)
                  throws BrokerException

Overrides:

primeWithAck in class BrokerClient

Throws:

BrokerException