Package com.softwareag.entirex.aci

Class 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 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();
    Since:
    6.2.1.0

    • 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 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 updateUserStatus()
      Updates the user status field of the current unit of work.

      • 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.
        • 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 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 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 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

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

        @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 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.

      • 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

      • 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 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.