com.softwareag.entirex.aci
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 the 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 send 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();
 

Since:

6.2.1.0

Field Summary

Fields inherited from class com.softwareag.entirex.aci.BrokerCommunication

brokerService

Constructor Summary

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

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.
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 u) 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

Methods inherited from class java.lang.Object

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

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 call setStatusPersistence(int) with a multiplier and setStatusPersistence(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.

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 status ACCEPTED when this lifetime expires, it is placed into a TIMEOUT status. Lifetime timeouts will not occur in the RECEIVED or DELIVERED 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 u)

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.

Parameters:

u - the user status, maximum length is 32 characters.

Throws:

java.lang.IllegalArgumentException - Thrown if the length of the user status exceeds 32 bytes.

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 is RECEIVED.

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 from RECEIVED to ACCEPTED. 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 is RECEIVED, the status changes to BACKEDOUT. 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 is DELIVERED, the status changes to ACCEPTED 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 is ACCEPTED, the status changes to CANCELLED.
If the receiver of the unit of work calls this method and the status is DELIVERED, the status changes to CANCELLED.
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 from RECEIVED to ACCEPTED. It is now available to be received by the server.
If the receiver of the unit of work calls this method and the status is DELIVERED, the status changes to PROCESSED. 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 method

broker - 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

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 exception

java.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 corresponding UnitofWork object is returned which is created automatically if necessary. If there is no UnitofWork 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 the getStatus method.

Returns:

the current unit of work.

Throws:

BrokerException - A Broker exception

query

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 method

service - 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 method

broker - 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 exception

java.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 exception

java.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 exception

java.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 exception

java.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 exception

java.lang.IllegalArgumentException - Thrown if a parameter is invalid.

Since:

EntireX 6.2.1.16

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 a Date object. If no commit timestamp is available or not in the format yyyyMMddHHmmssSSSZ, 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 a 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.

Returns:

the string for the commit timestamp or null.