public class UnitofWork extends BrokerCommunication
commit
or commitBoth
method.
When a unit of work has been committed, the application can either create a new unit of work (by calling the send method) or receive a new unit of work (by calling the receive method), using the same UnitofWork object.
Each unit of work runs implicitly in a conversation. This conversation is
handled automatically by the UnitofWork object without using the Conversation
object. The conversation spans the lifetime of a UnitofWork object and can be
explicitly terminated by the commitCancelConversation
,
commitEndConversation
or endConversation
method.
Example for a sender: send numberConversations
conversations,
each with numberUows
units of work, containing
numberMessages
messages each. Thus, numberConversations *
numberUows * numberMessages
messages are sent in total.
Broker b = new Broker("my broker id", "my user id"); BrokerService service = new BrokerService(b, "ACLASS/ASERVER/ASERVICE"); BrokerMessage msg = new BrokerMessage(); for (int i = 0; i < numberConversations; i++) { ConversationState state = null; for (int j = 0; j < numberUows; j++) { UnitofWork uow = (j == 0) ? new UnitofWork(service) : new UnitofWork(service, state); for (int k = 0; k < numberMessages; k++) { msg.setMessage("Message " + k + " in UOW " + uow.getUnitofWorkID() + " (" + j + ") in " + ((j > 0) ? state.getTicket() : "(no ticket)") + " (" + i + ")."); uow.send(msg); } if (j + 1 == numberUows) uow.commitEndConversation(); else uow.commit(); state = uow.saveState(); } }Example for a receiver: receive all available messages in all units of work over multiple conversations.
Broker b = new Broker("my broker id", "my user id"); BrokerService service = new BrokerService(b, "ACLASS/ASERVER/ASERVICE"); service.register(); String wait = "10S"; boolean nextMessage = true; BrokerMessage msg = new BrokerMessage(); UnitofWork uow = null; try { // loop over the conversations while (true) { try { ConversationState state = null; // loop over the units of work in one conversation. while (true) { uow = (state == null) ? new UnitofWork(service) : new UnitofWork(service, state); // loop over all messages in one unit of work. while (nextMessage) { msg = uow.receive(wait); if (msg != null) { // do something with the message. } nextMessage = !(uow.getStatus().equals("RECV_ONLY") || uow.getStatus().equals("RECV_LAST")); } nextMessage = true; uow.commit(); state = uow.saveState(); } } catch (BrokerException bEx) { if (bEx.getErrorClass() == 3 && bEx.getErrorCode() == 5) { // conversation has ended, try next conversation. } else { throw bEx; } } } } catch (BrokerException bEx1) { if (bEx1.getErrorClass() == 74 && bEx1.getErrorCode() == 74) { // timeout means: no more messages, thus deregister. } else { throw bEx1; } } service.deregisterImmediate();
brokerService
Constructor and Description |
---|
UnitofWork(BrokerService brokerService)
Creates a new UnitofWork object and
attaches it to the given BrokerService.
|
UnitofWork(BrokerService brokerService,
ConversationState cstate)
Creates a new UnitofWork object and
attaches it to the given BrokerService.
|
Modifier and Type | Method and Description |
---|---|
void |
backout()
Backs out the current unit of work.
|
void |
cancel()
Cancels the current unit of work.
|
void |
commit()
Commits the current unit of work.
|
void |
commitBoth()
Commits the two units of work, one being currently received and one
being currently sent in a single atomic operation.
|
void |
commitCancelConversation()
Commits the current unit of work and cancels the associated conversation.
|
void |
commitEndConversation()
Commits the current unit of work and ends the associated conversation.
|
void |
delete()
Deletes the persistent status of the current unit of work.
|
static void |
delete(java.lang.String unitofWorkID,
Broker broker)
Deletes the persistent status of the specified unit of work.
|
void |
endConversation()
Ends the current conversation.
|
int |
getAttemptedDeliveryCount()
Returns how often it was attempted to deliver the unit of work.
|
java.util.Date |
getCommitTimestamp()
Returns the sender's commit timestamp for this unit of work as a
Date
object. |
java.lang.String |
getCommitTimestampString()
Returns the sender's commit timestamp for this unit of work as a
String object. |
java.lang.String |
getLifetime()
Returns the lifetime value of a unit of work.
|
java.lang.String |
getStatus()
Returns the current status of the current unit of work.
|
java.lang.String |
getUnitofWorkID()
Returns the unique identifier for the current unit of work.
|
java.lang.String |
getUserStatus()
Returns the user-defined status associated with the current unit of work.
|
static UnitofWork |
lastUOWForThisBrokerInstance(Broker broker)
Retrieve the last UOW which has been used by the instance of the Broker object (parameter).
|
UnitofWork |
query()
Queries the status of the current unit of work.
|
static UnitofWork |
query(java.lang.String unitofWorkID,
Broker broker)
Queries the status of the specified unit of work.
|
static UnitofWork |
query(java.lang.String unitofWorkID,
BrokerService service)
Deprecated.
If more than one service is used by one user, the returned
UnitofWork object might belong to some other service.
|
static UnitofWork |
queryLast(Broker broker)
Queries the status of the last unit of work created by the caller.
|
static UnitofWork |
queryLast(BrokerService service)
Deprecated.
If more than one service is used by one user, the returned
UnitofWork object might belong to some other service.
|
BrokerMessage |
receive()
Receives the first or subsequent message of a unit of work.
|
BrokerMessage |
receive(java.lang.String wait)
Receives the first or subsequent message of a unit of work.
|
static BrokerMessage |
receiveAny(BrokerService bs)
Receives the first message or subsequent message of a unit of work.
|
static BrokerMessage |
receiveAny(BrokerService bs,
java.lang.String wait)
Receives the first or subsequent message of a unit of work.
|
static BrokerMessage |
receiveOld(BrokerService bs)
Receives the first message or subsequent message of a unit of work.
|
static BrokerMessage |
receiveOld(BrokerService bs,
java.lang.String wait)
Receives the first or subsequent message of a unit of work.
|
void |
send(BrokerMessage msg)
Sends an asynchronous message as part of a unit of work.
|
void |
sendCommit(BrokerMessage msg)
Sends an asynchronous message which commits the unit of work.
|
void |
setDataPersistence(boolean persist)
Enables or disables data persistence when creating a new unit of work.
|
void |
setLifetime(java.lang.String t)
Sets the lifetime value of a unit of work.
|
void |
setStatusPersistence(boolean persist)
Enables or disables status persistence when creating a new unit of work.
|
void |
setStatusPersistence(int lifetimeMultiplier)
Enables status persistence when creating a new unit of work and sets the lifetime
of the persistent status.
|
void |
setStatusPersistence(java.lang.String lifetime)
Enables status persistence when creating a new unit of work and sets
the lifetime of the persistent status.
|
void |
setUserStatus(java.lang.String status)
Sets the user-defined status associated with the current unit of work.
|
void |
setUserStatusFromException(java.lang.Exception e) |
void |
updateUserStatus()
Updates the user status field of the current unit of work.
|
dispose, getBrokerService, getUserData, saveState, setUserData
public UnitofWork(BrokerService brokerService)
brokerService
- the BrokerService object to which the unit of work communication belongs.public UnitofWork(BrokerService brokerService, ConversationState cstate) throws java.lang.IllegalArgumentException
brokerService
- the BrokerService object to which the unit of work communication belongs.cstate
- the ConversationState object to be restored.java.lang.IllegalArgumentException
- if ConversationState object is nullConversationState
public void setDataPersistence(boolean persist)
persist
- if true sender wants data persistence, if false
sender does not want data persistence.public void setStatusPersistence(boolean persist)
persist
- if true sender wants persistence of status, if false
sender does not want status persistence.setStatusPersistence(int)
,
getStatus()
public void setStatusPersistence(int lifetimeMultiplier)
lifetimeMultiplier
- a value between 1 and 254 (inclusive).java.lang.IllegalArgumentException
- if argument is not in the range of 1
to 254.setStatusPersistence(boolean)
,
setLifetime(java.lang.String)
,
getStatus()
public void setStatusPersistence(java.lang.String lifetime)
setStatusPersistence(int)
with a
multiplier and setStatusPersistence(java.lang.String)
with
a lifetime value, the second method wins.lifetime
- a period, how the status of th unit of work should live.
This time is measured in seconds/minutes/hours (depending on the
trailing S/M/H character). When null or "NO" is specified, the
operation is non-blocked.setStatusPersistence(boolean)
,
setStatusPersistence(int)
,
setLifetime(java.lang.String)
,
getStatus()
public java.lang.String getStatus()
RECEIVED
-
one or more messages have been sent as part of a unit of work which is not yet committed.
ACCEPTED
-
the unit of work has been committed by the sender.
DELIVERED
-
the unit of work is currently being received by the sender.
BACKEDOUT
-
the unit of work was backed out prior to being committed by the sender.
PROCESSED
-
the receiver of the unit of work has committed it.
CANCELLED
-
the unit of work was not processed within the specified lifetime.
DISCARDED
-
the unit of work was not persistent and its data was discarded over a restart.
POSTPONED
-
the unit of work is currently being postponed.
In addition the following status values are returned by the receive method,
they all reflect an current status of DELIVERED
:
RECV_FIRST
-
this message is the first message in the unit of work.
RECV_MIDDLE
-
this message is not the first or last message in the unit of work.
RECV_LAST
-
this message is the last message in the unit of work.
RECV_ONLY
-
this message is the only message in the unit of work.
public void setLifetime(java.lang.String t)
ACCEPTED
when this lifetime expires, it is placed
into a TIMEOUT
status. Lifetime timeouts will not occur in the
RECEIVED
or DELIVERED
status.
t
- the lifetime value measured in seconds/minutes/hours/days
(depending on the trailing S/M/H/D character).java.lang.IllegalArgumentException
- if argument is invalid.public java.lang.String getLifetime()
public java.lang.String getUnitofWorkID()
query(java.lang.String, BrokerService)
public void setUserStatus(java.lang.String status)
status
- the user status, maximum length is 32 characters.public void setUserStatusFromException(java.lang.Exception e)
e
- the exception
the user status, maximum length is 32 characters.public java.lang.String getUserStatus()
public int getAttemptedDeliveryCount()
int
.public void send(BrokerMessage msg) throws BrokerException
RECEIVED
.msg
- BrokerMessage to send.BrokerException
- A Broker exception.java.lang.IllegalArgumentException
- if parameter is invalid.public void sendCommit(BrokerMessage msg) throws BrokerException
RECEIVED
to ACCEPTED
.
It is now available to be received by the server.msg
- BrokerMessage to send.BrokerException
- A Broker exception.java.lang.IllegalArgumentException
- Thrown if parameter is invalid.public void backout() throws BrokerException
RECEIVED
, the status changes to BACKEDOUT
.
If persistent status is disabled, no trace of this unit of work remains.
DELIVERED
, the status changes to
ACCEPTED
and the number of attempted deliveries is
incremented.BrokerException
- A Broker exception.public void cancel() throws BrokerException
ACCEPTED
, the status changes to CANCELLED
.
DELIVERED
, the status changes to CANCELLED
.
BrokerException
- A Broker exception.public void commit() throws BrokerException
RECEIVED
to ACCEPTED
.
It is now available to be received by the server.
DELIVERED
, the status changes to PROCESSED
.
If persistent status is disabled, no trace of this unit of work remains.BrokerException
- A Broker exceptionpublic void commitBoth() throws BrokerException
BrokerException
- A Broker exceptioncommit()
public void delete() throws BrokerException
BrokerException
- A Broker exceptionpublic static void delete(java.lang.String unitofWorkID, Broker broker) throws BrokerException
unitofWorkID
- unique identifier retrieved by the getUnitofWorkID methodbroker
- reference to a Broker objectBrokerException
- A Broker exceptiongetUnitofWorkID()
public void commitEndConversation() throws BrokerException
BrokerException
- A Broker exceptioncommit()
public void commitCancelConversation() throws BrokerException
BrokerException
- A Broker exceptioncommit()
public static UnitofWork queryLast(BrokerService service) throws BrokerException
null
is returned.service
- a reference to the BrokerService the object belongs to.null
.BrokerException
- A Broker exceptionjava.lang.IllegalArgumentException
- if applied to a generic service.public static UnitofWork queryLast(Broker broker) throws BrokerException
UnitofWork
object is returned which is
created automatically if necessary. If there is no UnitofWork
object for the caller, null
is returned.broker
- the Broker object.null
BrokerException
- A Broker exceptionpublic UnitofWork query() throws BrokerException
getStatus
method.BrokerException
- A Broker exceptionpublic static UnitofWork query(java.lang.String unitofWorkID, BrokerService service) throws BrokerException
unitofWorkID
- unique identifier retrieved by the getUnitofWorkID methodservice
- reference to a BrokerService objectBrokerException
- A Broker exception.java.lang.IllegalArgumentException
- Thrown if parameter is invalid.public static UnitofWork query(java.lang.String unitofWorkID, Broker broker) throws BrokerException
unitofWorkID
- unique identifier retrieved by the getUnitofWorkID methodbroker
- the Broker object.BrokerException
- A Broker exception.public void updateUserStatus() throws BrokerException
BrokerException
- A Broker exceptionsetUserStatus(java.lang.String)
public BrokerMessage receive(java.lang.String wait) throws BrokerException
wait
- A timeout period, how long to wait for
a receive, measured in seconds/minutes/hours
(depending on the trailing S/M/H character).
When null or "NO" is specified, the operation is non-blocked.BrokerException
- A Broker exceptionjava.lang.IllegalArgumentException
- Thrown if parameter is invalid.public BrokerMessage receive() throws BrokerException
BrokerException
- A Broker exceptionpublic static BrokerMessage receiveOld(BrokerService bs, java.lang.String wait) throws BrokerException
bs
- The BrokerService used to receive the message.wait
- A timeout period, how long to wait for
a receive, measured in seconds/minutes/hours
(depending on the trailing S/M/H character).
When null or "NO" is specified, the operation is non-blocked.BrokerException
- A Broker exceptionjava.lang.IllegalArgumentException
- Thrown if parameter is invalid.public static BrokerMessage receiveOld(BrokerService bs) throws BrokerException
bs
- The BrokerService used to receive the message.BrokerException
- A Broker exceptionjava.lang.IllegalArgumentException
- Thrown if a parameter is invalid.public static BrokerMessage receiveAny(BrokerService bs, java.lang.String wait) throws BrokerException
bs
- The BrokerService used to receive the message.wait
- A timeout period, how long to wait for
a receive, measured in seconds/minutes/hours
(depending on the trailing S/M/H character).
When null or "NO" is specified, the operation is non-blocked.BrokerException
- A Broker exceptionjava.lang.IllegalArgumentException
- Thrown if parameter is invalid.public static BrokerMessage receiveAny(BrokerService bs) throws BrokerException
bs
- The BrokerService used to receive the message.BrokerException
- A Broker exceptionjava.lang.IllegalArgumentException
- Thrown if a parameter is invalid.public static UnitofWork lastUOWForThisBrokerInstance(Broker broker)
broker
- the Broker object instancepublic void endConversation() throws BrokerException
BrokerException
- if the broker call fails.public java.util.Date getCommitTimestamp()
Date
object. If no commit timestamp is available or not in the format yyyyMMddHHmmssSSSZ
,
null
is returned.public java.lang.String getCommitTimestampString()
String
object. The format is "yyyyMMddHHmmssSSSz";
"yyyy" for the year, "MM" for the month, "dd" for the day, "HH" for
the hour, "mm" for the minute, "ss" for the second, "SSS" for the
millisecond, and "z" for the timezone (see also
SimpleDateFormat
for detailed information on the
format). The timezone is given as an offset and is always "-0000" for
UTC. The timezone is provided to avoid unintended changes if supplied to
the Date
class or other classes. If no commit timestamp is
available, null
is returned.