Class UnitofWork
- java.lang.Object
-
- com.softwareag.entirex.aci.BrokerCommunication
-
- com.softwareag.entirex.aci.UnitofWork
-
public class UnitofWork extends BrokerCommunication
Represents a UnitofWork communication.
A unit of work is a set of one or more messages that are processed as a single unit. The sender of a unit of work adds messages to the unit of work and then indicates that it is complete by calling the commit or sendCommit method. The unit of work and its messages are not visible to the receiver until the sender has committed the unit of work. Once it is committed, the receiver can receive messages and can indicate when it is complete by calling thecommit
orcommitBoth
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
orendConversation
method. Example for a sender: sendnumberConversations
conversations, each withnumberUows
units of work, containingnumberMessages
messages each. Thus,numberConversations * numberUows * numberMessages
messages are sent in total.
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"); 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(); } }
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();
- Since:
- 6.2.1.0
-
-
Field Summary
-
Fields inherited from class com.softwareag.entirex.aci.BrokerCommunication
brokerService
-
-
Constructor Summary
Constructors Constructor 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.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method 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 aDate
object.java.lang.String
getCommitTimestampString()
Returns the sender's commit timestamp for this unit of work as aString
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
updateUserStatus()
Updates the user status field of the current unit of work.-
Methods inherited from class com.softwareag.entirex.aci.BrokerCommunication
dispose, getBrokerService, getUserData, saveState, setUserData
-
-
-
-
Constructor Detail
-
UnitofWork
public UnitofWork(BrokerService brokerService)
Creates a new UnitofWork object and attaches it to the given BrokerService.- Parameters:
brokerService
- the BrokerService object to which the unit of work communication belongs.
-
UnitofWork
public UnitofWork(BrokerService brokerService, ConversationState cstate) throws java.lang.IllegalArgumentException
Creates a new UnitofWork object and attaches it to the given BrokerService.
The conversation of the UnitofWork object is restored from the ConversationState object.- Parameters:
brokerService
- the BrokerService object to which the unit of work communication belongs.cstate
- the ConversationState object to be restored.- Throws:
java.lang.IllegalArgumentException
- if ConversationState object is null- Since:
- 7.1.1.10
- See Also:
ConversationState
-
-
Method Detail
-
setDataPersistence
public void setDataPersistence(boolean persist)
Enables or disables data persistence when creating a new unit of work.
When a new unit of work is created and this method has not been previously called, the persistence option specified in the Broker attribute file (keyword STORE) is used. If the sender wants to control data persistence, this method must be called before the first send method call which creates the unit of work.
If a unit of work is persistent, its messages are saved in the persistent store when the sender commits the unit of work. They are retained until the receiver commits or cancels the unit of work or until its lifetime expires. If the EntireX Broker or the system fails after the unit of work is committed, the unit of work (and its associated conversation) will be restored to their last stable status when the EntireX Broker restarts.- Parameters:
persist
- if true sender wants data persistence, if false sender does not want data persistence.
-
setStatusPersistence
public void setStatusPersistence(boolean persist)
Enables or disables status persistence when creating a new unit of work.
When a new unit of work is created and this method has not been previously called, the persistence option specified in the Broker attribute file (keyword UWSTATP) is used. If the sender wants to control status persistence, this method must be called before the first send method call which creates the unit of work. The lifetime of the persistent status is the same as the lifetime of the unit of work.- Parameters:
persist
- if true sender wants persistence of status, if false sender does not want status persistence.- See Also:
setStatusPersistence(int)
,getStatus()
-
setStatusPersistence
public void setStatusPersistence(int lifetimeMultiplier)
Enables status persistence when creating a new unit of work and sets the lifetime of the persistent status.
The lifetime for persistent status is a multiplier of the unit of work lifetime. The default is 1. This method must be called before the first send method call to set a higher lifetime value.
If a unit of work has persistent status, this status is maintained in the persistent store and is updated whenever the status changes. The persistent status remains in the persistent store after the unit of work is completed until the status lifetime has expired.- Parameters:
lifetimeMultiplier
- a value between 1 and 254 (inclusive).- Throws:
java.lang.IllegalArgumentException
- if argument is not in the range of 1 to 254.- See Also:
setStatusPersistence(boolean)
,setLifetime(java.lang.String)
,getStatus()
-
setStatusPersistence
public void setStatusPersistence(java.lang.String lifetime)
Enables status persistence when creating a new unit of work and sets the lifetime of the persistent status.
The lifetime for persistent status is set as a time value. This lifetime is added to the lifetime of the unit of work. This method must be called before the first send method call to set a higher lifetime value.
If a unit of work has persistent status, this status is maintained in the persistent store and is updated whenever the status changes. The persistent status remains in the persistent store after the unit of work is completed until the status lifetime has expired.
If you callsetStatusPersistence(int)
with a multiplier andsetStatusPersistence(java.lang.String)
with a lifetime value, the second method wins.- Parameters:
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.- See Also:
setStatusPersistence(boolean)
,setStatusPersistence(int)
,setLifetime(java.lang.String)
,getStatus()
-
getStatus
public java.lang.String getStatus()
Returns the current status of the current unit of work.
The status is set by all methods which manipulate or query a unit of work. Applicable values are: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.
- Returns:
- the status as a String.
-
setLifetime
public void setLifetime(java.lang.String t)
Sets the lifetime value of a unit of work.
Each unit of work has a lifetime value. This is the period of time the unit of work is allowed to exist without being completed. It starts when the unit of work is created and ends when it is completed. If the unit of work has statusACCEPTED
when this lifetime expires, it is placed into aTIMEOUT
status. Lifetime timeouts will not occur in theRECEIVED
orDELIVERED
status.
The lifetime clock is running only when the EntireX Broker is up and active.- Parameters:
t
- the lifetime value measured in seconds/minutes/hours/days (depending on the trailing S/M/H/D character).- Throws:
java.lang.IllegalArgumentException
- if argument is invalid.
-
getLifetime
public java.lang.String getLifetime()
Returns the lifetime value of a unit of work.- Returns:
- the lifetime as a String.
-
getUnitofWorkID
public java.lang.String getUnitofWorkID()
Returns the unique identifier for the current unit of work.
The value generated by the EntireX Broker can be used by the query method call.- Returns:
- the UnitofWorkID as a String.
- See Also:
query(java.lang.String, BrokerService)
-
setUserStatus
public void setUserStatus(java.lang.String status)
Sets the user-defined status associated with the current unit of work. It will be transmitted with a send or receive call. It will be returned with a query or queryLast call. If the length exceeds 32 characters, the status is truncated.- Parameters:
status
- the user status, maximum length is 32 characters.
-
getUserStatus
public java.lang.String getUserStatus()
Returns the user-defined status associated with the current unit of work.
It will be transmitted with a send or receive call. It will be returned with a query or queryLast call.- Returns:
- the current value of the user status of this unit of work.
-
getAttemptedDeliveryCount
public int getAttemptedDeliveryCount()
Returns how often it was attempted to deliver the unit of work.
This count is incremented whenever a unit of work is backed out, either explicitly or by a timeout or restart.- Returns:
- the attempted delivery count as
int
.
-
send
public void send(BrokerMessage msg) throws BrokerException
Sends an asynchronous message as part of a unit of work. Sends the message to the Broker without waiting for an answer.
The status of the unit of work isRECEIVED
.- Parameters:
msg
- BrokerMessage to send.- Throws:
BrokerException
- A Broker exception.java.lang.IllegalArgumentException
- if parameter is invalid.
-
sendCommit
public void sendCommit(BrokerMessage msg) throws BrokerException
Sends an asynchronous message which commits the unit of work. Sends the message to the Broker without waiting for an answer.
The status of the unit of work changes fromRECEIVED
toACCEPTED
. It is now available to be received by the server.- Parameters:
msg
- BrokerMessage to send.- Throws:
BrokerException
- A Broker exception.java.lang.IllegalArgumentException
- Thrown if parameter is invalid.
-
backout
public void backout() throws BrokerException
Backs out the current unit of work.
If the sender of the unit of work calls this method and the status isRECEIVED
, the status changes toBACKEDOUT
. If persistent status is disabled, no trace of this unit of work remains.
If the receiver of the unit of work calls this method and the status isDELIVERED
, the status changes toACCEPTED
and the number of attempted deliveries is incremented.- Throws:
BrokerException
- A Broker exception.
-
cancel
public void cancel() throws BrokerException
Cancels the current unit of work.
If the sender of the unit of work calls this method and the status isACCEPTED
, the status changes toCANCELLED
.
If the receiver of the unit of work calls this method and the status isDELIVERED
, the status changes toCANCELLED
.
In both cases, if persistent status is disabled, no trace of this unit of work remains.- Throws:
BrokerException
- A Broker exception.
-
commit
public void commit() throws BrokerException
Commits the current unit of work.
If the sender of the unit of work calls this method, the status of the unit of work changes fromRECEIVED
toACCEPTED
. It is now available to be received by the server.
If the receiver of the unit of work calls this method and the status isDELIVERED
, the status changes toPROCESSED
. If persistent status is disabled, no trace of this unit of work remains.- Throws:
BrokerException
- A Broker exception
-
commitBoth
public void commitBoth() throws BrokerException
Commits the two units of work, one being currently received and one being currently sent in a single atomic operation.- Throws:
BrokerException
- A Broker exception- See Also:
commit()
-
delete
public void delete() throws BrokerException
Deletes the persistent status of the current unit of work.
The unit of work must be complete and must have been created by the caller. If persistent status is disabled, no trace of this unit of work remains.- Throws:
BrokerException
- A Broker exception
-
delete
public static void delete(java.lang.String unitofWorkID, Broker broker) throws BrokerException
Deletes the persistent status of the specified unit of work.
The unit of work must be complete and must have been created by the caller. The caller is identified by the user ID and token specified in the constructor for the Broker object (which is the second parameter). If persistent status is disabled, no trace of this unit of work remains.- Parameters:
unitofWorkID
- unique identifier retrieved by the getUnitofWorkID methodbroker
- reference to a Broker object- Throws:
BrokerException
- A Broker exception- See Also:
getUnitofWorkID()
-
commitEndConversation
public void commitEndConversation() throws BrokerException
Commits the current unit of work and ends the associated conversation.- Throws:
BrokerException
- A Broker exception- See Also:
commit()
-
commitCancelConversation
public void commitCancelConversation() throws BrokerException
Commits the current unit of work and cancels the associated conversation.- Throws:
BrokerException
- A Broker exception- See Also:
commit()
-
queryLast
@Deprecated public static UnitofWork queryLast(BrokerService service) throws BrokerException
Deprecated.If more than one service is used by one user, the returned UnitofWork object might belong to some other service.Queries the status of the last unit of work created by the caller.
The caller is identified by the user ID and token specified in the constructor for the Broker object the BrokerService object belongs to.
A corresponding UnitofWork object is returned which is created automatically if necessary. If there is no UnitofWork object for the caller,null
is returned.- Parameters:
service
- a reference to the BrokerService the object belongs to.- Returns:
- a UnitofWork object or
null
. - Throws:
BrokerException
- A Broker exceptionjava.lang.IllegalArgumentException
- if applied to a generic service.
-
queryLast
public static UnitofWork queryLast(Broker broker) throws BrokerException
Queries the status of the last unit of work created by the caller.
The caller is identified by the user ID and token specified in the constructor for the Broker object.
A correspondingUnitofWork
object is returned which is created automatically if necessary. If there is noUnitofWork
object for the caller,null
is returned.- Parameters:
broker
- the Broker object.- Returns:
- a UnitofWork object or
null
- Throws:
BrokerException
- A Broker exception
-
query
public UnitofWork query() throws BrokerException
Queries the status of the current unit of work.
The status can be read with thegetStatus
method.- Returns:
- the current unit of work.
- Throws:
BrokerException
- A Broker exception
-
query
@Deprecated public static UnitofWork query(java.lang.String unitofWorkID, BrokerService service) throws BrokerException
Deprecated.If more than one service is used by one user, the returned UnitofWork object might belong to some other service.Queries the status of the specified unit of work.
The unit of work must have been created by the caller. A corresponding unit of work object is returned which is created automatically if necessary.- Parameters:
unitofWorkID
- unique identifier retrieved by the getUnitofWorkID methodservice
- reference to a BrokerService object- Returns:
- the unit of work for this ID and this BrokerService
- Throws:
BrokerException
- A Broker exception.java.lang.IllegalArgumentException
- Thrown if parameter is invalid.
-
query
public static UnitofWork query(java.lang.String unitofWorkID, Broker broker) throws BrokerException
Queries the status of the specified unit of work.
The unit of work must have been created by the caller. A corresponding unit of work object is returned which is created automatically if necessary.- Parameters:
unitofWorkID
- unique identifier retrieved by the getUnitofWorkID methodbroker
- the Broker object.- Returns:
- the unit of work for this ID and this Broker.
- Throws:
BrokerException
- A Broker exception.
-
updateUserStatus
public void updateUserStatus() throws BrokerException
Updates the user status field of the current unit of work.- Throws:
BrokerException
- A Broker exception- See Also:
setUserStatus(java.lang.String)
-
receive
public BrokerMessage receive(java.lang.String wait) throws BrokerException
Receives the first or subsequent message of a unit of work. Uses the maximum receive length from the service.- Parameters:
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.- Returns:
- the BrokerMessage received.
- Throws:
BrokerException
- A Broker exceptionjava.lang.IllegalArgumentException
- Thrown if parameter is invalid.
-
receive
public BrokerMessage receive() throws BrokerException
Receives the first or subsequent message of a unit of work. Uses the maximum receive length and the default wait time from the service.- Returns:
- the BrokerMessage received.
- Throws:
BrokerException
- A Broker exception- Since:
- EntireX 5.2.1
-
receiveOld
public static BrokerMessage receiveOld(BrokerService bs, java.lang.String wait) throws BrokerException
Receives the first or subsequent message of a unit of work.
This receive method will accept only messages from existing conversations. Uses the maximum receive length from the service.- Parameters:
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.- Returns:
- the BrokerMessage received.
- Throws:
BrokerException
- A Broker exceptionjava.lang.IllegalArgumentException
- Thrown if parameter is invalid.- Since:
- EntireX 6.2.1.16
-
receiveOld
public static BrokerMessage receiveOld(BrokerService bs) throws BrokerException
Receives the first message or subsequent message of a unit of work.
This receive method will accept only messages from existing conversations. Uses the maximum receive length and the default wait time from the service.- Parameters:
bs
- The BrokerService used to receive the message.- Returns:
- the BrokerMessage received.
- Throws:
BrokerException
- A Broker exceptionjava.lang.IllegalArgumentException
- Thrown if a parameter is invalid.- Since:
- EntireX 6.2.1.16
-
receiveAny
public static BrokerMessage receiveAny(BrokerService bs, java.lang.String wait) throws BrokerException
Receives the first or subsequent message of a unit of work.
This receive method will accept messages from existing conversations and new conversations. Uses the maximum receive length from the service.- Parameters:
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.- Returns:
- the BrokerMessage received.
- Throws:
BrokerException
- A Broker exceptionjava.lang.IllegalArgumentException
- Thrown if parameter is invalid.- Since:
- EntireX 6.2.1.16
-
receiveAny
public static BrokerMessage receiveAny(BrokerService bs) throws BrokerException
Receives the first message or subsequent message of a unit of work.
This receive method will accept messages from existing conversations and new conversations. Uses the maximum receive length and the default wait time from the service.- Parameters:
bs
- The BrokerService used to receive the message.- Returns:
- the BrokerMessage received.
- Throws:
BrokerException
- A Broker exceptionjava.lang.IllegalArgumentException
- Thrown if a parameter is invalid.- Since:
- EntireX 6.2.1.16
-
lastUOWForThisBrokerInstance
public static UnitofWork lastUOWForThisBrokerInstance(Broker broker)
Retrieve the last UOW which has been used by the instance of the Broker object (parameter). Returns an UOW object or null. If the UOW status cannot be determined it is set to "UNKNOWN".- Parameters:
broker
- the Broker object instance- Returns:
- the last used Unitofwork or null if no UOW is available
-
endConversation
public void endConversation() throws BrokerException
Ends the current conversation.
If the sender of the unit of work calls this method, the current conversation ends normally. It is now available to be received by the server.
If the receiver of the unit of work calls this method, the current conversation ends. Receiving further messages is possible.- Throws:
BrokerException
- if the broker call fails.
-
getCommitTimestamp
public java.util.Date getCommitTimestamp()
Returns the sender's commit timestamp for this unit of work as aDate
object. If no commit timestamp is available or not in the formatyyyyMMddHHmmssSSSZ
,null
is returned.- Returns:
- the date object for the commit timestamp or null.
-
getCommitTimestampString
public java.lang.String getCommitTimestampString()
Returns the sender's commit timestamp for this unit of work as aString
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 alsoSimpleDateFormat
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 theDate
class or other classes. If no commit timestamp is available,null
is returned.- Returns:
- the string for the commit timestamp or null.
-
-