Coverage Report

Coverage Report - org.kuali.rice.kew.service.WorkflowDocument

Classes in this File
Line Coverage
Branch Coverage
Complexity
WorkflowDocument
0/393
0/126
1.841
 /*
  * Copyright 2005-2007 The Kuali Foundation
  *
  *
  * Licensed under the Educational Community License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  *
  * http://www.opensource.org/licenses/ecl2.php
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
 package org.kuali.rice.kew.service;
 
 import java.sql.Timestamp;
 import java.util.ArrayList;
 import java.util.Calendar;
 import java.util.List;
 
 import org.kuali.rice.core.exception.RiceRuntimeException;
 import org.kuali.rice.core.resourceloader.GlobalResourceLoader;
 import org.kuali.rice.kew.dto.ActionRequestDTO;
 import org.kuali.rice.kew.dto.ActionTakenDTO;
 import org.kuali.rice.kew.dto.AdHocRevokeDTO;
 import org.kuali.rice.kew.dto.DocumentContentDTO;
 import org.kuali.rice.kew.dto.DocumentDetailDTO;
 import org.kuali.rice.kew.dto.DocumentLinkDTO;
 import org.kuali.rice.kew.dto.EmplIdDTO;
 import org.kuali.rice.kew.dto.ModifiableDocumentContentDTO;
 import org.kuali.rice.kew.dto.MovePointDTO;
 import org.kuali.rice.kew.dto.NetworkIdDTO;
 import org.kuali.rice.kew.dto.NoteDTO;
 import org.kuali.rice.kew.dto.ReturnPointDTO;
 import org.kuali.rice.kew.dto.RouteHeaderDTO;
 import org.kuali.rice.kew.dto.RouteNodeInstanceDTO;
 import org.kuali.rice.kew.dto.UserIdDTO;
 import org.kuali.rice.kew.dto.WorkflowAttributeDefinitionDTO;
 import org.kuali.rice.kew.dto.WorkflowAttributeValidationErrorDTO;
 import org.kuali.rice.kew.dto.WorkflowIdDTO;
 import org.kuali.rice.kew.exception.WorkflowException;
 import org.kuali.rice.kew.exception.WorkflowRuntimeException;
 import org.kuali.rice.kew.util.KEWConstants;
 import org.kuali.rice.kim.bo.Person;
 import org.kuali.rice.kim.bo.entity.KimPrincipal;
 import org.kuali.rice.kim.service.IdentityManagementService;
 import org.kuali.rice.kim.service.PersonService;
 import org.kuali.rice.kim.util.KimConstants;
 
 /**
  * Represents a document in Workflow from the perspective of the client.  This class is one of two
  * (Java) client interfaces to the KEW system (the other being {@link WorkflowInfo} class).  The
  * first time an instance of this class is created, it will read the client configuration to determine
  * how to connect to KEW.
  *
  * <p>This class is used by creating new instances using the appropriate constructor.  To create a new
  * document in KEW, create an instance of this class passing a UserIdVO and a
  * document type name.  To load an existing document, create an instance of this class passing a
  * UserIdVO and a document ID number.
  *
  * <p>Internally, this wrapper interacts with the {@link WorkflowDocumentActions} service exported
  * over the KSB, maintaining state.
  *
  * <p>This class is not thread safe and must by synchronized externally for concurrent access.
  *
  * @author Kuali Rice Team (rice.collab@kuali.org)
  */
 public class WorkflowDocument implements java.io.Serializable {
 
         private static final long serialVersionUID = -3672966990721719088L;
 
         /**
          * The principal ID of the user as whom actions will be taken on the KEW document
          */
     private String principalId;
     /**
      * RouteHeader VO of the KEW document this WorkflowDocument represents
      */
     private RouteHeaderDTO routeHeader;
     /**
      * Flag that indicates whether the document content currently loaded needs to be refreshed.
      * This is the case either if the document content has not yet been loaded, or an action
      * that might possibly affect the document content (which is potentially any action) has
      * subsequently been taken on the document through this API.
      */
     private boolean documentContentDirty = false;
     /**
      * Value Object encapsulating the document content
      */
     private ModifiableDocumentContentDTO documentContent;
 
     /**
      * @deprecated Use the constructor which takes a principal ID instead.
      */
     public WorkflowDocument(UserIdDTO userId, String documentType) throws WorkflowException {
             String principalId = convertUserIdToPrincipalId(userId);
             init(principalId, documentType, null);
     }
 
     /**
      * @deprecated Use the constructor which takes a principal ID instead.
      */
     public WorkflowDocument(UserIdDTO userId, Long routeHeaderId) throws WorkflowException {
             String principalId = convertUserIdToPrincipalId(userId);
             init(principalId, null, routeHeaderId);
     }
 
     private String convertUserIdToPrincipalId(UserIdDTO userId) {
 
         if (userId == null) {
             return null;
         } else if (userId instanceof WorkflowIdDTO) {
             return ((WorkflowIdDTO)userId).getWorkflowId();
         } else if (userId instanceof NetworkIdDTO) {
             IdentityManagementService identityManagementService = (IdentityManagementService)GlobalResourceLoader.getService(KimConstants.KIM_IDENTITY_MANAGEMENT_SERVICE);
             String principalName = ((NetworkIdDTO)userId).getNetworkId();
             KimPrincipal principal = identityManagementService.getPrincipalByPrincipalName(principalName);
             return principal.getPrincipalId();
         } else if (userId instanceof EmplIdDTO) {
             PersonService personService = (PersonService)GlobalResourceLoader.getService(KimConstants.KIM_PERSON_SERVICE);
             String employeeId = ((EmplIdDTO)userId).getEmplId();
             Person person = personService.getPersonByEmployeeId(employeeId);
             if (person == null) {
                 throw new RiceRuntimeException("Could not locate a person with the given employee id of " + employeeId);
             }
             return person.getPrincipalId();
         }
         throw new IllegalArgumentException("Invalid UserIdDTO type was passed: " + userId);
     }
 
     /**
      * Constructs a WorkflowDocument representing a new document in the workflow system.
      * Creation/committing of the new document is deferred until the first action is
      * taken on the document.
      * @param principalId the user as which to take actions on the document
      * @param documentType the type of the document to create
      * @throws WorkflowException if anything goes awry
      */
     public WorkflowDocument(String principalId, String documentType) throws WorkflowException {
         init(principalId, documentType, null);
     }
 
     /**
      * Loads a workflow document with the given route header ID for the given User.  If no document
      * can be found with the given ID, then the {@link getRouteHeader()} method of the WorkflowDocument
      * which is created will return null.
      *
      * @throws WorkflowException if there is a problem loading the WorkflowDocument
      */
     public WorkflowDocument(String principalId, Long routeHeaderId) throws WorkflowException {
         init(principalId, null, routeHeaderId);
     }
 
     /**
      * Initializes this WorkflowDocument object, by either attempting to load an existing document by routeHeaderid
      * if one is supplied (non-null), or by constructing an empty document of the specified type.
      * @param principalId the user under which actions via this API on the specified document will be taken
      * @param documentType the type of document this WorkflowDocument should represent (either this parameter or routeHeaderId must be specified, non-null)
      * @param routeHeaderId the id of an existing document to load (either this parameter or documentType must be specified, non-null)
      * @throws WorkflowException if a routeHeaderId is specified but an exception occurs trying to load the document route header
      */
     private void init(String principalId, String documentType, Long routeHeaderId) throws WorkflowException {
             this.principalId = principalId;
             routeHeader = new RouteHeaderDTO();
             routeHeader.setDocTypeName(documentType);
             if (routeHeaderId != null) {
                     routeHeader = getWorkflowUtility().getRouteHeaderWithPrincipal(principalId, routeHeaderId);
             }
     }
 
     /**
      * Retrieves the WorkflowUtility proxy from the locator.  The locator will cache this for us.
      */
     private WorkflowUtility getWorkflowUtility() throws WorkflowException {
         WorkflowUtility workflowUtility = 
                 (WorkflowUtility)GlobalResourceLoader.getService(KEWConstants.WORKFLOW_UTILITY_SERVICE);
             if (workflowUtility == null) {
                     throw new WorkflowException("Could not locate the WorkflowUtility service.  Please ensure that KEW client is configured properly!");
             }
             return workflowUtility;
 
     }
 
     /**
      * Retrieves the WorkflowDocumentActions proxy from the locator.  The locator will cache this for us.
      */
     private WorkflowDocumentActions getWorkflowDocumentActions() throws WorkflowException {
             WorkflowDocumentActions workflowDocumentActions = 
                     (WorkflowDocumentActions)GlobalResourceLoader.getService(KEWConstants.WORKFLOW_DOCUMENT_ACTIONS_SERVICE);
             if (workflowDocumentActions == null) {
                     throw new WorkflowException("Could not locate the WorkflowDocumentActions service.  Please ensure that KEW client is configured properly!");
             }
             return workflowDocumentActions;
     }
 
     // ########################
     // Document Content methods
     // ########################
 
     /**
      * Returns an up-to-date DocumentContent of this document.
      * @see WorkflowUtility#getDocumentContent(Long)
      */
     public DocumentContentDTO getDocumentContent() {
             try {
                     // create the document if it hasn't already been created
                     if (getRouteHeader().getRouteHeaderId() == null) {
                         routeHeader = getWorkflowDocumentActions().createDocument(principalId, getRouteHeader());
                 }
                     if (documentContent == null || documentContentDirty) {
                             documentContent = new ModifiableDocumentContentDTO(getWorkflowUtility().getDocumentContent(routeHeader.getRouteHeaderId()));
                             documentContentDirty = false;
                     }
             } catch (Exception e) {
                     throw handleExceptionAsRuntime(e);
             }
             return documentContent;
     }
 
     /**
      * Returns the application specific section of the document content. This is
      * a convenience method that delegates to the {@link DocumentContentDTO}.
      *
      * For documents routed prior to Workflow 2.0:
      * If the application did NOT use attributes for XML generation, this method will
      * return the entire document content XML.  Otherwise it will return the empty string.
      * @see DocumentContentDTO#getApplicationContent()
      */
     public String getApplicationContent() {
         return getDocumentContent().getApplicationContent();
     }
 
     /**
      * Sets the application specific section of the document content. This is
      * a convenience method that delegates to the {@link DocumentContentDTO}.
      */
     public void setApplicationContent(String applicationContent) {
         getDocumentContent().setApplicationContent(applicationContent);
     }
 
     /**
      * Clears all attribute document content from the document.
      * Typically, this will be used if it is necessary to update the attribute doc content on
      * the document.  This can be accomplished by clearing the content and then adding the
      * desired attribute definitions.
      *
      * This is a convenience method that delegates to the {@link DocumentContentDTO}.
      *
      * In order for these changes to take effect, an action must be performed on the document (such as "save").
      */
     public void clearAttributeContent() {
         getDocumentContent().setAttributeContent("");
     }
 
     /**
      * Returns the attribute-generated section of the document content. This is
      * a convenience method that delegates to the {@link DocumentContentDTO}.
      * @see DocumentContentDTO#getAttributeContent()
      */
     public String getAttributeContent() {
         return getDocumentContent().getAttributeContent();
     }
 
     /**
      * Adds an attribute definition which defines creation parameters for a WorkflowAttribute
      * implementation.  The created attribute will be used to generate attribute document content.
      * When the document is sent to the server, this will be appended to the existing attribute
      * doc content.  If it is required to replace the attribute document content, then the
      * clearAttributeContent() method should be invoked prior to adding attribute definitions.
      *
      * This is a convenience method that delegates to the {@link DocumentContentDTO}.
      * @see DocumentContentDTO#addAttributeDefinition(WorkflowAttributeDefinitionDTO)
      */
     public void addAttributeDefinition(WorkflowAttributeDefinitionDTO attributeDefinition) {
         getDocumentContent().addAttributeDefinition(attributeDefinition);
     }
 
     /**
      * Validate the WorkflowAttributeDefinition against it's attribute on the server.  This will validate
      * the inputs that will eventually become xml.
      *
      * Only applies to attributes implementing WorkflowAttributeXmlValidator.
      *
      * This is a call through to the WorkflowInfo object and is here for convenience.
      *
      * @param attributeDefinition the workflow attribute definition VO to validate
      * @return WorkflowAttributeValidationErrorVO[] of error from the attribute
      * @throws WorkflowException when attribute doesn't implement WorkflowAttributeXmlValidator
      * @see WorkflowUtility#validateWorkflowAttributeDefinitionVO(WorkflowAttributeDefinitionDTO)
      */
     public WorkflowAttributeValidationErrorDTO[] validateAttributeDefinition(WorkflowAttributeDefinitionDTO attributeDefinition) throws WorkflowException {
             return getWorkflowUtility().validateWorkflowAttributeDefinitionVO(attributeDefinition);
     }
 
     /**
      * Removes an attribute definition from the document content.  This is
      * a convenience method that delegates to the {@link DocumentContentDTO}.
      * @param attributeDefinition the attribute definition VO to remove
      */
     public void removeAttributeDefinition(WorkflowAttributeDefinitionDTO attributeDefinition) {
         getDocumentContent().removeAttributeDefinition(attributeDefinition);
     }
 
     /**
      * Removes all attribute definitions from the document content. This is
      * a convenience method that delegates to the {@link DocumentContentDTO}.
      */
     public void clearAttributeDefinitions() {
             getDocumentContent().setAttributeDefinitions(new WorkflowAttributeDefinitionDTO[0]);
     }
 
     /**
      * Returns the attribute definition VOs currently defined on the document content. This is
      * a convenience method that delegates to the {@link DocumentContentDTO}.
      * @return the attribute definition VOs currently defined on the document content.
      * @see DocumentContentDTO#getAttributeDefinitions()
      */
     public WorkflowAttributeDefinitionDTO[] getAttributeDefinitions() {
         return getDocumentContent().getAttributeDefinitions();
     }
 
     /**
      * Adds a searchable attribute definition which defines creation parameters for a SearchableAttribute
      * implementation.  The created attribute will be used to generate searchable document content.
      * When the document is sent to the server, this will be appended to the existing searchable
      * doc content.  If it is required to replace the searchable document content, then the
      * clearSearchableContent() method should be invoked prior to adding definitions. This is
      * a convenience method that delegates to the {@link DocumentContentDTO}.
      */
     public void addSearchableDefinition(WorkflowAttributeDefinitionDTO searchableDefinition) {
         getDocumentContent().addSearchableDefinition(searchableDefinition);
     }
 
     /**
      * Removes a searchable attribute definition from the document content. This is
      * a convenience method that delegates to the {@link DocumentContentDTO}.
      * @param searchableDefinition the searchable attribute definition to remove
      */
     public void removeSearchableDefinition(WorkflowAttributeDefinitionDTO searchableDefinition) {
         getDocumentContent().removeSearchableDefinition(searchableDefinition);
     }
 
     /**
      * Removes all searchable attribute definitions from the document content. This is
      * a convenience method that delegates to the {@link DocumentContentDTO}.
      */
     public void clearSearchableDefinitions() {
         getDocumentContent().setSearchableDefinitions(new WorkflowAttributeDefinitionDTO[0]);
     }
 
     /**
      * Clears the searchable content from the document content. This is
      * a convenience method that delegates to the {@link DocumentContentDTO}.
      */
     public void clearSearchableContent() {
             getDocumentContent().setSearchableContent("");
     }
 
     /**
      * Returns the searchable attribute definitions on the document content. This is
      * a convenience method that delegates to the {@link DocumentContentDTO}.
      * @return the searchable attribute definitions on the document content.
      * @see DocumentContentDTO#getSearchableDefinitions()
      */
     public WorkflowAttributeDefinitionDTO[] getSearchableDefinitions() {
         return getDocumentContent().getSearchableDefinitions();
     }
 
     // ########################
     // END Document Content methods
     // ########################
 
     /**
      * Returns the RouteHeaderVO for the workflow document this WorkflowDocument represents
      */
     public RouteHeaderDTO getRouteHeader() {
         return routeHeader;
     }
 
     /**
      * Returns the id of the workflow document this WorkflowDocument represents.  If this is a new document
      * that has not yet been created, the document is first created (and therefore this will return a new id)
      * @return the id of the workflow document this WorkflowDocument represents
      * @throws WorkflowException if an error occurs during document creation
      */
     public Long getRouteHeaderId() throws WorkflowException {
             createDocumentIfNeccessary();
             return getRouteHeader().getRouteHeaderId();
     }
 
     /**
      * Returns VOs of the pending ActionRequests on this document.  If this object represents a new document
      * that has not yet been created, then an empty array will be returned.  The ordering of ActionRequests
      * returned by this method is not guaranteed.
      *
      * This method relies on the WorkflowUtility service
      *
      * @return VOs of the pending ActionRequests on this document
      * @throws WorkflowException if an error occurs obtaining the pending action requests for this document
      * @see WorkflowUtility#getActionRequests(Long)
      */
     public ActionRequestDTO[] getActionRequests() throws WorkflowException {
         if (getRouteHeaderId() == null) {
             return new ActionRequestDTO[0];
         }
         return getWorkflowUtility().getAllActionRequests(getRouteHeaderId());
     }
 
     /**
      * Returns VOs of the actions taken on this document.  If this object represents a new document
      * that has not yet been created, then an empty array will be returned.  The ordering of actions taken
      * returned by this method is not guaranteed.
      *
      * This method relies on the WorkflowUtility service
      *
      * @return VOs of the actions that have been taken on this document
      * @throws WorkflowException if an error occurs obtaining the actions taken on this document
      * @see WorkflowUtility#getActionsTaken(Long)
      */
     public ActionTakenDTO[] getActionsTaken() throws WorkflowException {
         if (getRouteHeaderId() == null) {
             return new ActionTakenDTO[0];
         }
         return getWorkflowUtility().getActionsTaken(getRouteHeaderId());
     }
 
     /**
      * Sets the "application doc id" on the document
      * @param appDocId the "application doc id" to set on the workflow document
      */
     public void setAppDocId(String appDocId) {
         routeHeader.setAppDocId(appDocId);
     }
 
     /**
      * Returns the "application doc id" set on this workflow document (if any)
      * @return the "application doc id" set on this workflow document (if any)
      */
     public String getAppDocId() {
         return routeHeader.getAppDocId();
     }
 
     /**
      * Returns the date/time the document was created, or null if the document has not yet been created
      * @return the date/time the document was created, or null if the document has not yet been created
      */
     public Timestamp getDateCreated() {
             if (routeHeader.getDateCreated() == null) {
                     return null;
             }
             return new Timestamp(routeHeader.getDateCreated().getTime().getTime());
     }
 
     /**
      * Returns the title of the document
      * @return the title of the document
      */
     public String getTitle() {
         return getRouteHeader().getDocTitle();
     }
 
     /**
      * Performs the 'save' action on the document this WorkflowDocument represents.  If this is a new document,
      * the document is created first.
      * @param annotation the message to log for the action
      * @throws WorkflowException in case an error occurs saving the document
      * @see WorkflowDocumentActions#saveDocument(UserIdDTO, RouteHeaderDTO, String)
      */
     public void saveDocument(String annotation) throws WorkflowException {
             createDocumentIfNeccessary();
             routeHeader = getWorkflowDocumentActions().saveDocument(principalId, getRouteHeader(), annotation);
             documentContentDirty = true;
     }
 
     /**
      * Performs the 'route' action on the document this WorkflowDocument represents.  If this is a new document,
      * the document is created first.
      * @param annotation the message to log for the action
      * @throws WorkflowException in case an error occurs routing the document
      * @see WorkflowDocumentActions#routeDocument(UserIdDTO, RouteHeaderDTO, String)
      */
     public void routeDocument(String annotation) throws WorkflowException {
             createDocumentIfNeccessary();
             routeHeader = getWorkflowDocumentActions().routeDocument(principalId, routeHeader, annotation);
             documentContentDirty = true;
     }
 
     /**
      * Performs the 'disapprove' action on the document this WorkflowDocument represents.  If this is a new document,
      * the document is created first.
      * @param annotation the message to log for the action
      * @throws WorkflowException in case an error occurs disapproving the document
      * @see WorkflowDocumentActions#disapproveDocument(UserIdDTO, RouteHeaderDTO, String)
      */
     public void disapprove(String annotation) throws WorkflowException {
             createDocumentIfNeccessary();
             routeHeader = getWorkflowDocumentActions().disapproveDocument(principalId, getRouteHeader(), annotation);
             documentContentDirty = true;
     }
 
     /**
      * Performs the 'approve' action on the document this WorkflowDocument represents.  If this is a new document,
      * the document is created first.
      * @param annotation the message to log for the action
      * @throws WorkflowException in case an error occurs approving the document
      * @see WorkflowDocumentActions#approveDocument(UserIdDTO, RouteHeaderDTO, String)
      */
     public void approve(String annotation) throws WorkflowException {
             createDocumentIfNeccessary();
             routeHeader = getWorkflowDocumentActions().approveDocument(principalId, getRouteHeader(), annotation);
             documentContentDirty = true;
     }
 
     /**
      * Performs the 'cancel' action on the document this WorkflowDocument represents.  If this is a new document,
      * the document is created first.
      * @param annotation the message to log for the action
      * @throws WorkflowException in case an error occurs canceling the document
      * @see WorkflowDocumentActions#cancelDocument(UserIdDTO, RouteHeaderDTO, String)
      */
     public void cancel(String annotation) throws WorkflowException {
             createDocumentIfNeccessary();
             routeHeader = getWorkflowDocumentActions().cancelDocument(principalId, getRouteHeader(), annotation);
             documentContentDirty = true;
     }
 
     /**
      * Performs the 'blanket-approve' action on the document this WorkflowDocument represents.  If this is a new document,
      * the document is created first.
      * @param annotation the message to log for the action
      * @throws WorkflowException in case an error occurs blanket-approving the document
      * @see WorkflowDocumentActions#blanketApprovalToNodes(UserIdDTO, RouteHeaderDTO, String, String[])
      */
     public void blanketApprove(String annotation) throws WorkflowException {
         blanketApprove(annotation, (String)null);
     }
 
     /**
      * Commits any changes made to the local copy of this document to the workflow system.  If this is a new document,
      * the document is created first.
      * @throws WorkflowException in case an error occurs saving the document
      * @see WorkflowDocumentActions#saveRoutingData(UserIdDTO, RouteHeaderDTO)
      */
     public void saveRoutingData() throws WorkflowException {
             createDocumentIfNeccessary();
             routeHeader = getWorkflowDocumentActions().saveRoutingData(principalId, getRouteHeader());
             documentContentDirty = true;
     }
 
     /**
      * 
      * This method sets the Application Document Status and then calls saveRoutingData() to commit 
      * the changes to the workflow system.
      * 
      * @param appDocStatus
      * @throws WorkflowException
      */
     public void updateAppDocStatus(String appDocStatus) throws WorkflowException {
                getRouteHeader().setAppDocStatus(appDocStatus);
                saveRoutingData();
     }
     
     /**
      * Performs the 'acknowledge' action on the document this WorkflowDocument represents.  If this is a new document,
      * the document is created first.
      * @param annotation the message to log for the action
      * @throws WorkflowException in case an error occurs acknowledging the document
      * @see WorkflowDocumentActions#acknowledgeDocument(UserIdDTO, RouteHeaderDTO, String)
      */
     public void acknowledge(String annotation) throws WorkflowException {
             createDocumentIfNeccessary();
             routeHeader = getWorkflowDocumentActions().acknowledgeDocument(principalId, getRouteHeader(), annotation);
             documentContentDirty = true;
     }
 
     /**
      * Performs the 'fyi' action on the document this WorkflowDocument represents.  If this is a new document,
      * the document is created first.
      * @param annotation the message to log for the action
      * @throws WorkflowException in case an error occurs fyi-ing the document
      */
     public void fyi() throws WorkflowException {
             createDocumentIfNeccessary();
             routeHeader = getWorkflowDocumentActions().clearFYIDocument(principalId, getRouteHeader());
             documentContentDirty = true;
     }
 
     /**
      * Performs the 'delete' action on the document this WorkflowDocument represents.  If this is a new document,
      * the document is created first.
      * @param annotation the message to log for the action
      * @throws WorkflowException in case an error occurs deleting the document
      * @see WorkflowDocumentActions#deleteDocument(UserIdDTO, RouteHeaderDTO)
      */
     public void delete() throws WorkflowException {
             createDocumentIfNeccessary();
             getWorkflowDocumentActions().deleteDocument(principalId, getRouteHeader());
             documentContentDirty = true;
     }
 
     /**
      * Reloads the document route header.  If this is a new document, the document is created first.
      * Next time document content is accessed, an up-to-date copy will be retrieved from workflow.
      * @throws WorkflowException in case an error occurs retrieving the route header
      */
     public void refreshContent() throws WorkflowException {
             createDocumentIfNeccessary();
             routeHeader = getWorkflowUtility().getRouteHeader(getRouteHeaderId());
             documentContentDirty = true;
     }
 
     /**
      * Sends an ad hoc request to the specified user at the current active node on the document.  If the document is
      * in a terminal state, the request will be attached to the terminal node.
      */
     public void adHocRouteDocumentToPrincipal(String actionRequested, String annotation, String principalId, String responsibilityDesc, boolean forceAction) throws WorkflowException {
             adHocRouteDocumentToPrincipal(actionRequested, null, annotation, principalId, responsibilityDesc, forceAction);
     }
 
     /**
      * Sends an ad hoc request to the specified user at the specified node on the document.  If the document is
      * in a terminal state, the request will be attached to the terminal node.
      */
     public void adHocRouteDocumentToPrincipal(String actionRequested, String nodeName, String annotation, String principalId, String responsibilityDesc, boolean forceAction) throws WorkflowException {
             adHocRouteDocumentToPrincipal(actionRequested, nodeName, annotation, principalId, responsibilityDesc, forceAction, null);
     }
 
     /**
      * Sends an ad hoc request to the specified user at the specified node on the document.  If the document is
      * in a terminal state, the request will be attached to the terminal node.
      */
     public void adHocRouteDocumentToPrincipal(String actionRequested, String nodeName, String annotation, String principalId, String responsibilityDesc, boolean forceAction, String requestLabel) throws WorkflowException {
             createDocumentIfNeccessary();
             routeHeader = getWorkflowDocumentActions().adHocRouteDocumentToPrincipal(principalId, getRouteHeader(), actionRequested, nodeName, annotation, principalId, responsibilityDesc, forceAction, requestLabel);
             documentContentDirty = true;
     }
 
     /**
      * Sends an ad hoc request to the specified workgroup at the current active node on the document.  If the document is
      * in a terminal state, the request will be attached to the terminal node.
      */
     public void adHocRouteDocumentToGroup(String actionRequested, String annotation, String groupId, String responsibilityDesc, boolean forceAction) throws WorkflowException {
             adHocRouteDocumentToGroup(actionRequested, null, annotation, groupId, responsibilityDesc, forceAction);
     }
 
     /**
      * Sends an ad hoc request to the specified workgroup at the specified node on the document.  If the document is
      * in a terminal state, the request will be attached to the terminal node.
      */
     public void adHocRouteDocumentToGroup(String actionRequested, String nodeName, String annotation, String groupId, String responsibilityDesc, boolean forceAction) throws WorkflowException {
             adHocRouteDocumentToGroup(actionRequested, nodeName, annotation, groupId, responsibilityDesc, forceAction, null);
     }
 
     /**
      * Sends an ad hoc request to the specified workgroup at the specified node on the document.  If the document is
      * in a terminal state, the request will be attached to the terminal node.
      */
     public void adHocRouteDocumentToGroup(String actionRequested, String nodeName, String annotation, String groupId, String responsibilityDesc, boolean forceAction, String requestLabel) throws WorkflowException {
             createDocumentIfNeccessary();
             routeHeader = getWorkflowDocumentActions().adHocRouteDocumentToGroup(principalId, getRouteHeader(), actionRequested, nodeName, annotation, groupId, responsibilityDesc, forceAction, requestLabel);
             documentContentDirty = true;
     }
 
     /**
      * Revokes AdHoc request(s) according to the given AdHocRevokeVO which is passed in.
      *
      * If a specific action request ID is specified on the revoke bean, and that ID is not a valid ID, this method should throw a
      * WorkflowException.
      * @param revoke AdHocRevokeVO
      * @param annotation message to note for this action
      * @throws WorkflowException if an error occurs revoking adhoc requests
      * @see WorkflowDocumentActions#revokeAdHocRequests(UserIdDTO, RouteHeaderDTO, AdHocRevokeDTO, String)
      */
     public void revokeAdHocRequests(AdHocRevokeDTO revoke, String annotation) throws WorkflowException {
             if (getRouteHeader().getRouteHeaderId() == null) {
                     throw new WorkflowException("Can't revoke request, the workflow document has not yet been created!");
             }
             createDocumentIfNeccessary();
             routeHeader = getWorkflowDocumentActions().revokeAdHocRequests(principalId, getRouteHeader(), revoke, annotation);
             documentContentDirty = true;
     }
 
     /**
      * Sets the title of the document, empty string if null is specified.
      * @param title title of the document to set, or null
      */
     // WorkflowException is declared but not thrown...
     public void setTitle(String title) throws WorkflowException {
         if (title == null) {
             title = "";
         }
         if (title.length() > KEWConstants.TITLE_MAX_LENGTH) {
             title = title.substring(0, KEWConstants.TITLE_MAX_LENGTH);
         }
         getRouteHeader().setDocTitle(title);
     }
 
     /**
      * Returns the document type of the workflow document
      * @return the document type of the workflow document
      * @throws RuntimeException if document does not exist (is not yet created)
      * @see RouteHeaderDTO#getDocTypeName()
      */
     public String getDocumentType() {
         if (getRouteHeader() == null) {
             // HACK: FIXME: we should probably proscribe, or at least handle consistently, these corner cases
             // NPEs are not nice
             throw new RuntimeException("No such document!");
         }
         return getRouteHeader().getDocTypeName();
     }
 
     /**
      * Returns whether an acknowledge is requested of the user for this document.  This is
      * a convenience method that delegates to {@link RouteHeaderDTO#isAckRequested()}.
      * @return whether an acknowledge is requested of the user for this document
      * @see RouteHeaderDTO#isAckRequested()
      */
     public boolean isAcknowledgeRequested() {
         return getRouteHeader().isAckRequested();
     }
 
     /**
      * Returns whether an approval is requested of the user for this document.  This is
      * a convenience method that delegates to {@link RouteHeaderDTO#isApproveRequested()}.
      * @return whether an approval is requested of the user for this document
      * @see RouteHeaderDTO#isApproveRequested()
      */
     public boolean isApprovalRequested() {
         return getRouteHeader().isApproveRequested();
     }
 
     /**
      * Returns whether a completion is requested of the user for this document.  This is
      * a convenience method that delegates to {@link RouteHeaderDTO#isCompleteRequested()}.
      * @return whether an approval is requested of the user for this document
      * @see RouteHeaderDTO#isCompleteRequested()
      */
     public boolean isCompletionRequested() {
         return getRouteHeader().isCompleteRequested();
     }
 
     /**
      * Returns whether an FYI is requested of the user for this document.  This is
      * a convenience method that delegates to {@link RouteHeaderDTO#isFyiRequested()}.
      * @return whether an FYI is requested of the user for this document
      * @see RouteHeaderDTO#isFyiRequested()
      */
     public boolean isFYIRequested() {
         return getRouteHeader().isFyiRequested();
     }
 
     /**
      * Returns whether the user can blanket approve the document
      * @return whether the user can blanket approve the document
      * @see RouteHeaderDTO#getValidActions()
      */
     public boolean isBlanketApproveCapable() {
         // TODO delyea - refactor this to take into account non-initiator owned documents
             return getRouteHeader().getValidActions().contains(KEWConstants.ACTION_TAKEN_BLANKET_APPROVE_CD) && (isCompletionRequested() || isApprovalRequested() || stateIsInitiated());
     }
 
     /**
      * Returns whether the specified action code is valid for the current user and document
      * @return whether the user can blanket approve the document
      * @see RouteHeaderDTO#getValidActions()
      */
     public boolean isActionCodeValidForDocument(String actionTakenCode) {
             return getRouteHeader().getValidActions().contains(actionTakenCode);
     }
 
     /**
      * Performs the 'super-user-approve' action on the document this WorkflowDocument represents.  If this is a new document,
      * the document is created first.
      * @param annotation the message to log for the action
      * @throws WorkflowException in case an error occurs super-user-approve-ing the document
      * @see WorkflowDocumentActions#superUserApprove(UserIdDTO, RouteHeaderDTO, String)
      */
     public void superUserApprove(String annotation) throws WorkflowException {
             createDocumentIfNeccessary();
             routeHeader = getWorkflowDocumentActions().superUserApprove(principalId, getRouteHeader(), annotation);
             documentContentDirty = true;
     }
 
     /**
      * Performs the 'super-user-action-request-approve' action on the document this WorkflowDocument represents and the action
      * request the id represents.
      * @param actionRequestId the action request id for the action request the super user is approved
      * @param annotation the message to log for the action
      * @throws WorkflowException in case an error occurs super-user-action-request-approve-ing the document
      * @see WorkflowDocumentActions#superUserApprove(UserIdVO, RouteHeaderVO, String)(UserIdVO, RouteHeaderVO, String)
      */
     public void superUserActionRequestApprove(Long actionRequestId, String annotation) throws WorkflowException {
             createDocumentIfNeccessary();
             routeHeader = getWorkflowDocumentActions().superUserActionRequestApprove(principalId, getRouteHeader(), actionRequestId, annotation);
             documentContentDirty = true;
     }
 
     /**
      * Performs the 'super-user-disapprove' action on the document this WorkflowDocument represents.  If this is a new document,
      * the document is created first.
      * @param annotation the message to log for the action
      * @throws WorkflowException in case an error occurs super-user-disapprove-ing the document
      * @see WorkflowDocumentActions#superUserDisapprove(UserIdDTO, RouteHeaderDTO, String)
      */
     public void superUserDisapprove(String annotation) throws WorkflowException {
             createDocumentIfNeccessary();
             routeHeader = getWorkflowDocumentActions().superUserDisapprove(principalId, getRouteHeader(), annotation);
             documentContentDirty = true;
     }
 
     /**
      * Performs the 'super-user-cancel' action on the document this WorkflowDocument represents.  If this is a new document,
      * the document is created first.
      * @param annotation the message to log for the action
      * @throws WorkflowException in case an error occurs super-user-cancel-ing the document
      * @see WorkflowDocumentActions#superUserCancel(UserIdDTO, RouteHeaderDTO, String)
      */
     public void superUserCancel(String annotation) throws WorkflowException {
             createDocumentIfNeccessary();
             routeHeader = getWorkflowDocumentActions().superUserCancel(principalId, getRouteHeader(), annotation);
             documentContentDirty = true;
     }
 
     /**
      * Returns whether the user is a super user on this document
      * @return whether the user is a super user on this document
      * @throws WorkflowException if an error occurs determining whether the user is a super user on this document
      * @see WorkflowUtility#isSuperUserForDocumentType(UserIdDTO, Long)
      */
     public boolean isSuperUser() throws WorkflowException {
             createDocumentIfNeccessary();
             return getWorkflowUtility().isSuperUserForDocumentType(principalId, getRouteHeader().getDocTypeId());
         }
 
     /**
      * Returns whether the user passed into WorkflowDocument at instantiation can route
      * the document.
          * @return if user passed into WorkflowDocument at instantiation can route
          *         the document.
          */
     public boolean isRouteCapable() {
         return isActionCodeValidForDocument(KEWConstants.ACTION_TAKEN_ROUTED_CD);
     }
 
     /**
      * Performs the 'clearFYI' action on the document this WorkflowDocument represents.  If this is a new document,
      * the document is created first.
      * @param annotation the message to log for the action
      * @throws WorkflowException in case an error occurs clearing FYI on the document
      * @see WorkflowDocumentActions#clearFYIDocument(UserIdDTO, RouteHeaderDTO)
      */
     public void clearFYI() throws WorkflowException {
             createDocumentIfNeccessary();
             getWorkflowDocumentActions().clearFYIDocument(principalId, getRouteHeader());
             documentContentDirty = true;
     }
 
     /**
      * Performs the 'complete' action on the document this WorkflowDocument represents.  If this is a new document,
      * the document is created first.
      * @param annotation the message to log for the action
      * @throws WorkflowException in case an error occurs clearing completing the document
      * @see WorkflowDocumentActions#completeDocument(UserIdDTO, RouteHeaderDTO, String)
      */
     public void complete(String annotation) throws WorkflowException {
             createDocumentIfNeccessary();
             routeHeader = getWorkflowDocumentActions().completeDocument(principalId, getRouteHeader(), annotation);
             documentContentDirty = true;
     }
 
     /**
      * Performs the 'logDocumentAction' action on the document this WorkflowDocument represents.  If this is a new document,
      * the document is created first.  The 'logDocumentAction' simply logs a message on the document.
      * @param annotation the message to log for the action
      * @throws WorkflowException in case an error occurs logging a document action on the document
      * @see WorkflowDocumentActions#logDocumentAction(UserIdDTO, RouteHeaderDTO, String)
      */
     public void logDocumentAction(String annotation) throws WorkflowException {
             createDocumentIfNeccessary();
             getWorkflowDocumentActions().logDocumentAction(principalId, getRouteHeader(), annotation);
             documentContentDirty = true;
     }
 
     /**
      * Indicates if the document is in the initiated state or not.
      *
      * @return true if in the specified state
      */
     public boolean stateIsInitiated() {
         return KEWConstants.ROUTE_HEADER_INITIATED_CD.equals(getRouteHeader().getDocRouteStatus());
     }
 
     /**
      * Indicates if the document is in the saved state or not.
      *
      * @return true if in the specified state
      */
     public boolean stateIsSaved() {
         return KEWConstants.ROUTE_HEADER_SAVED_CD.equals(getRouteHeader().getDocRouteStatus());
     }
 
     /**
      * Indicates if the document is in the enroute state or not.
      *
      * @return true if in the specified state
      */
     public boolean stateIsEnroute() {
         return KEWConstants.ROUTE_HEADER_ENROUTE_CD.equals(getRouteHeader().getDocRouteStatus());
     }
 
     /**
      * Indicates if the document is in the exception state or not.
      *
      * @return true if in the specified state
      */
     public boolean stateIsException() {
         return KEWConstants.ROUTE_HEADER_EXCEPTION_CD.equals(getRouteHeader().getDocRouteStatus());
     }
 
     /**
      * Indicates if the document is in the canceled state or not.
      *
      * @return true if in the specified state
      */
     public boolean stateIsCanceled() {
         return KEWConstants.ROUTE_HEADER_CANCEL_CD.equals(getRouteHeader().getDocRouteStatus());
     }
 
     /**
      * Indicates if the document is in the disapproved state or not.
      *
      * @return true if in the specified state
      */
     public boolean stateIsDisapproved() {
         return KEWConstants.ROUTE_HEADER_DISAPPROVED_CD.equals(getRouteHeader().getDocRouteStatus());
     }
 
     /**
      * Indicates if the document is in the approved state or not. Will answer true is document is in Processed or Finalized state.
      *
      * @return true if in the specified state
      */
     public boolean stateIsApproved() {
         return KEWConstants.ROUTE_HEADER_APPROVED_CD.equals(getRouteHeader().getDocRouteStatus()) || stateIsProcessed() || stateIsFinal();
     }
 
     /**
      * Indicates if the document is in the processed state or not.
      *
      * @return true if in the specified state
      */
     public boolean stateIsProcessed() {
         return KEWConstants.ROUTE_HEADER_PROCESSED_CD.equals(getRouteHeader().getDocRouteStatus());
     }
 
     /**
      * Indicates if the document is in the final state or not.
      *
      * @return true if in the specified state
      */
     public boolean stateIsFinal() {
         return KEWConstants.ROUTE_HEADER_FINAL_CD.equals(getRouteHeader().getDocRouteStatus());
     }
 
     /**
      * Returns the display value of the current document status
      * @return the display value of the current document status
      */
     public String getStatusDisplayValue() {
         return (String) KEWConstants.DOCUMENT_STATUSES.get(getRouteHeader().getDocRouteStatus());
     }
 
     /**
      * Returns the principalId with which this WorkflowDocument was constructed
      * @return the principalId with which this WorkflowDocument was constructed
      */
     public String getPrincipalId() {
         return principalId;
     }
 
     /**
      * Sets the principalId under which actions against this document should be taken
      * @param principalId principalId under which actions against this document should be taken
      */
     public void setPrincipalId(String principalId) {
         this.principalId = principalId;
     }
 
     /**
      * Checks if the document has been created or not (i.e. has a route header id or not) and issues
      * a call to the server to create the document if it has not yet been created.
      *
      * Also checks if the document content has been updated and saves it if it has.
      */
     private void createDocumentIfNeccessary() throws WorkflowException {
             if (getRouteHeader().getRouteHeaderId() == null) {
                     routeHeader = getWorkflowDocumentActions().createDocument(principalId, getRouteHeader());
             }
             if (documentContent != null && documentContent.isModified()) {
                     saveDocumentContent(documentContent);
             }
     }
 
     /**
      * Like handleException except it returns a RuntimeException.
      */
     private RuntimeException handleExceptionAsRuntime(Exception e) {
             if (e instanceof RuntimeException) {
                     return (RuntimeException)e;
             }
             return new WorkflowRuntimeException(e);
     }
 
     // WORKFLOW 2.1: new methods
 
     /**
      * Performs the 'blanketApprove' action on the document this WorkflowDocument represents.  If this is a new document,
      * the document is created first.
      * @param annotation the message to log for the action
      * @param nodeName the extent to which to blanket approve; blanket approval will stop at this node
      * @throws WorkflowException in case an error occurs blanket-approving the document
      * @see WorkflowDocumentActions#blanketApprovalToNodes(UserIdDTO, RouteHeaderDTO, String, String[])
      */
     public void blanketApprove(String annotation, String nodeName) throws WorkflowException {
         blanketApprove(annotation, (nodeName == null ? null : new String[] { nodeName }));
     }
 
     /**
      * Performs the 'blanketApprove' action on the document this WorkflowDocument represents.  If this is a new document,
      * the document is created first.
      * @param annotation the message to log for the action
      * @param nodeNames the nodes at which blanket approval will stop (in case the blanket approval traverses a split, in which case there may be multiple "active" nodes)
      * @throws WorkflowException in case an error occurs blanket-approving the document
      * @see WorkflowDocumentActions#blanketApprovalToNodes(UserIdDTO, RouteHeaderDTO, String, String[])
      */
     public void blanketApprove(String annotation, String[] nodeNames) throws WorkflowException {
             createDocumentIfNeccessary();
             routeHeader = getWorkflowDocumentActions().blanketApprovalToNodes(principalId, getRouteHeader(), annotation, nodeNames);
             documentContentDirty = true;
     }
 
     /**
      * The user taking action removes the action items for this workgroup and document from all other
      * group members' action lists.   If this is a new document, the document is created first.
      *
      * @param annotation the message to log for the action
      * @param workgroupId the workgroup on which to take authority
      * @throws WorkflowException user taking action is not in workgroup
      */
     public void takeGroupAuthority(String annotation, String groupId) throws WorkflowException {
             createDocumentIfNeccessary();
             routeHeader = getWorkflowDocumentActions().takeGroupAuthority(principalId, getRouteHeader(), groupId, annotation);
             documentContentDirty = true;
     }
 
     /**
      * The user that took the group authority is putting the action items back in the other users action lists.
      * If this is a new document, the document is created first.
      *
      * @param annotation the message to log for the action
      * @param workgroupId the workgroup on which to take authority
      * @throws WorkflowException user taking action is not in workgroup or did not take workgroup authority
      */
     public void releaseGroupAuthority(String annotation, String groupId) throws WorkflowException {
             createDocumentIfNeccessary();
             routeHeader = getWorkflowDocumentActions().releaseGroupAuthority(principalId, getRouteHeader(), groupId, annotation);
             documentContentDirty = true;
     }
 
     /**
      * Returns names of all active nodes the document is currently at.
      *
      * @return names of all active nodes the document is currently at.
      * @throws WorkflowException if there is an error obtaining the currently active nodes on the document
      * @see WorkflowUtility#getActiveNodeInstances(Long)
      */
     public String[] getNodeNames() throws WorkflowException {
             RouteNodeInstanceDTO[] activeNodeInstances = getWorkflowUtility().getActiveNodeInstances(getRouteHeaderId());
             String[] nodeNames = new String[(activeNodeInstances == null ? 0 : activeNodeInstances.length)];
             for (int index = 0; index < activeNodeInstances.length; index++) {
                     nodeNames[index] = activeNodeInstances[index].getName();
             }
             return nodeNames;
     }
 
     /**
      * Performs the 'returnToPrevious' action on the document this WorkflowDocument represents.  If this is a new document,
      * the document is created first.
      * @param annotation the message to log for the action
      * @param nodeName the node to return to
      * @throws WorkflowException in case an error occurs returning to previous node
      * @see WorkflowDocumentActions#returnDocumentToPreviousNode(UserIdDTO, RouteHeaderDTO, ReturnPointDTO, String)
      */
     public void returnToPreviousNode(String annotation, String nodeName) throws WorkflowException {
         ReturnPointDTO returnPoint = new ReturnPointDTO(nodeName);
         returnToPreviousNode(annotation, returnPoint);
     }
 
     /**
      * Performs the 'returnToPrevious' action on the document this WorkflowDocument represents.  If this is a new document,
      * the document is created first.
      * @param annotation the message to log for the action
      * @param ReturnPointDTO the node to return to
      * @throws WorkflowException in case an error occurs returning to previous node
      * @see WorkflowDocumentActions#returnDocumentToPreviousNode(UserIdDTO, RouteHeaderDTO, ReturnPointDTO, String)
      */
     public void returnToPreviousNode(String annotation, ReturnPointDTO returnPoint) throws WorkflowException {
             createDocumentIfNeccessary();
             routeHeader = getWorkflowDocumentActions().returnDocumentToPreviousNode(principalId, getRouteHeader(), returnPoint, annotation);
             documentContentDirty = true;
     }
 
     /**
      * Moves the document from a current node in it's route to another node.  If this is a new document,
      * the document is created first.
      * @param MovePointDTO VO representing the node at which to start, and the number of steps to move (negative steps is reverse)
      * @param annotation the message to log for the action
      * @throws WorkflowException in case an error occurs moving the document
      * @see WorkflowDocumentActions#moveDocument(UserIdDTO, RouteHeaderDTO, MovePointDTO, String)
      */
     public void moveDocument(MovePointDTO movePoint, String annotation) throws WorkflowException {
             createDocumentIfNeccessary();
             routeHeader =  getWorkflowDocumentActions().moveDocument(principalId, getRouteHeader(), movePoint, annotation);
             documentContentDirty = true;
     }
 
     /**
      * Returns the route node instances that have been created so far during the life of this document.  This includes
      * all previous instances which have already been processed and are no longer active.
      * @return the route node instances that have been created so far during the life of this document
      * @throws WorkflowException if there is an error getting the route node instances for the document
      * @see WorkflowUtility#getDocumentRouteNodeInstances(Long)
      */
     public RouteNodeInstanceDTO[] getRouteNodeInstances() throws WorkflowException {
             return getWorkflowUtility().getDocumentRouteNodeInstances(getRouteHeaderId());
     }
 
     /**
      * Returns Array of Route Nodes Names that can be safely returned to using the 'returnToPreviousXXX' methods.
      * Names are sorted in reverse chronological order.
      *
      * @return array of Route Nodes Names that can be safely returned to using the 'returnToPreviousXXX' methods
      * @throws WorkflowException if an error occurs obtaining the names of the previous route nodes for this document
      * @see WorkflowUtility#getPreviousRouteNodeNames(Long)
      */
     public String[] getPreviousNodeNames() throws WorkflowException {
             return getWorkflowUtility().getPreviousRouteNodeNames(getRouteHeaderId());
         }
 
     /**
      * Returns a document detail VO representing the route header along with action requests, actions taken,
      * and route node instances.
      * @return Returns a document detail VO representing the route header along with action requests, actions taken, and route node instances.
      * @throws WorkflowException
      */
     public DocumentDetailDTO getDetail() throws WorkflowException {
             return getWorkflowUtility().getDocumentDetail(getRouteHeaderId());
     }
 
     /**
      * Saves the given DocumentContentVO for this document.
      * @param documentContent document content VO to store for this document
      * @since 2.3
      * @see WorkflowDocumentActions#saveDocumentContent(DocumentContentDTO)
      */
     public DocumentContentDTO saveDocumentContent(DocumentContentDTO documentContent) throws WorkflowException {
             if (documentContent.getRouteHeaderId() == null) {
                     throw new WorkflowException("Document Content does not have a valid document ID.");
             }
             // important to check directly against getRouteHeader().getRouteHeaderId() instead of just getRouteHeaderId() because saveDocumentContent
             // is called from createDocumentIfNeccessary which is called from getRouteHeaderId().  If that method was used, we would have an infinite loop.
             if (!documentContent.getRouteHeaderId().equals(getRouteHeader().getRouteHeaderId())) {
                     throw new WorkflowException("Attempted to save content on this document with an invalid document id of " + documentContent.getRouteHeaderId());
             }
             DocumentContentDTO newDocumentContent = getWorkflowDocumentActions().saveDocumentContent(documentContent);
             this.documentContent = new ModifiableDocumentContentDTO(newDocumentContent);
             documentContentDirty = false;
             return this.documentContent;
     }
     
     public void placeInExceptionRouting(String annotation) throws WorkflowException {
             createDocumentIfNeccessary();
             routeHeader = getWorkflowDocumentActions().placeInExceptionRouting(principalId, getRouteHeader(), annotation);
             documentContentDirty = true;
     }
 
 
 
     // DEPRECATED: as of Workflow 2.1
 
     /**
      * @deprecated use blanketApprove(String annotation, String nodeName) instead
      */
     public void blanketApprove(String annotation, Integer routeLevel) throws WorkflowException {
             createDocumentIfNeccessary();
             routeHeader = getWorkflowDocumentActions().blanketApproval(principalId, getRouteHeader(), annotation, routeLevel);
             documentContentDirty = true;
     }
 
     /**
      * @deprecated use getNodeNames() instead
      */
     public Integer getDocRouteLevel() {
         return routeHeader.getDocRouteLevel();
     }
 
     /**
      * @deprecated use returnToPreviousNode(String annotation, String nodeName) instead
      */
     public void returnToPreviousRouteLevel(String annotation, Integer destRouteLevel) throws WorkflowException {
             createDocumentIfNeccessary();
             getWorkflowDocumentActions().returnDocumentToPreviousRouteLevel(principalId, getRouteHeader(), destRouteLevel, annotation);
             documentContentDirty = true;
     }
 
     /**
      * Returns a list of NoteVO representing the notes on the document
      * @return a list of NoteVO representing the notes on the document
      * @see RouteHeaderDTO#getNotes()
      */
     public List<NoteDTO> getNoteList(){
             List<NoteDTO> notesList = new ArrayList<NoteDTO>();
             NoteDTO[] notes = routeHeader.getNotes();
             if (notes != null){
                     for (int i=0; i<notes.length; i++){
                             if (! isDeletedNote(notes[i])){
                                     notesList.add(notes[i]);
                             }
                     }
             }
             return notesList;
     }
 
     /**
      * Deletes a note from the document.  The deletion is deferred until the next time the document is committed (via an action).
      * @param noteVO the note to remove from the document
      */
     public void deleteNote(NoteDTO noteVO){
             if (noteVO != null && noteVO.getNoteId()!=null){
                     NoteDTO noteToDelete = new NoteDTO();
                     noteToDelete.setNoteId(new Long(noteVO.getNoteId().longValue()));
                     /*noteToDelete.setRouteHeaderId(noteVO.getRouteHeaderId());
                     noteToDelete.setNoteAuthorWorkflowId(noteVO.getNoteAuthorWorkflowId());
                     noteToDelete.setNoteCreateDate(noteVO.getNoteCreateDate());
                     noteToDelete.setNoteText(noteVO.getNoteText());
                     noteToDelete.setLockVerNbr(noteVO.getLockVerNbr());*/
                     increaseNotesToDeleteArraySizeByOne();
                     routeHeader.getNotesToDelete()[routeHeader.getNotesToDelete().length - 1]=noteToDelete;
             }
     }
 
     /**
      * Updates the note of the same note id, on the document. The update is deferred until the next time the document is committed (via an action).
      * @param noteVO the note to update
      */
     public void updateNote (NoteDTO noteVO){
             boolean isUpdateNote = false;
             if (noteVO != null){
                     NoteDTO[] notes = routeHeader.getNotes();
                     NoteDTO  copyNote = new NoteDTO();
                         if (noteVO.getNoteId() != null){
                                 copyNote.setNoteId(new Long(noteVO.getNoteId().longValue()));
                         }
 
                         if (noteVO.getRouteHeaderId() != null){
                                 copyNote.setRouteHeaderId(new Long(noteVO.getRouteHeaderId().longValue()));
                         } else {
                                 copyNote.setRouteHeaderId(routeHeader.getRouteHeaderId());
                         }
 
                         if (noteVO.getNoteAuthorWorkflowId() != null){
                                 copyNote.setNoteAuthorWorkflowId(new String(noteVO.getNoteAuthorWorkflowId()));
                         } else {
                             copyNote.setNoteAuthorWorkflowId(principalId.toString())        ;
                         }
 
                         if (noteVO.getNoteCreateDate() != null){
                                 Calendar cal = Calendar.getInstance();
                                 cal.setTimeInMillis(noteVO.getNoteCreateDate().getTimeInMillis());
                                 copyNote.setNoteCreateDate(cal);
                         } else {
                                 copyNote.setNoteCreateDate(Calendar.getInstance());
                         }
 
                         if (noteVO.getNoteText() != null){
                                 copyNote.setNoteText(new String(noteVO.getNoteText()));
                         }
                         if (noteVO.getLockVerNbr() != null){
                                 copyNote.setLockVerNbr(new Integer(noteVO.getLockVerNbr().intValue()));
                         }
                     if (notes != null){
                             for (int i=0; i<notes.length; i++){
                                     if (notes[i].getNoteId()!= null && notes[i].getNoteId().equals(copyNote.getNoteId())){
                                             notes[i] = copyNote;
                                             isUpdateNote = true;
                                             break;
                                     }
                             }
                     }
                     // add new note to the notes array
                     if (! isUpdateNote){
                             copyNote.setNoteId(null);
                             increaseNotesArraySizeByOne();
                             routeHeader.getNotes()[routeHeader.getNotes().length-1]= copyNote;
                     }
             }
     }
 
     /**
      * Sets a variable on the document.  The assignment is deferred until the next time the document is committed (via an action).
      * @param name name of the variable
      * @param value value of the variable
      */
     public void setVariable(String name, String value) throws WorkflowException {
             createDocumentIfNeccessary();
         getRouteHeader().setVariable(name, value);
     }
 
     /**
      * Gets the value of a variable on the document, creating the document first if it does not exist.
      * @param name variable name
      * @return variable value
      */
     public String getVariable(String name) throws WorkflowException {
             createDocumentIfNeccessary();
         return getRouteHeader().getVariable(name);
     }
 
     /**
      *
      * Tells workflow that the current the document is constructed as will receive all future requests routed to them
      * disregarding any force action flags set on the action request.  Uses the setVariable method behind the seens so
      * an action needs taken on the document to set this state on the document.
      *
      * @throws WorkflowException
      */
     public void setReceiveFutureRequests() throws WorkflowException {
         WorkflowUtility workflowUtility = getWorkflowUtility();
         this.setVariable(workflowUtility.getFutureRequestsKey(principalId), workflowUtility.getReceiveFutureRequestsValue());
     }
 
     /**
      * Tell workflow that the current document is constructed as will not receive any future requests routed to them
      * disregarding any force action flags set on action requests.  Uses the setVariable method behind the scenes so
      * an action needs taken on the document to set this state on the document.
      *
      * @throws WorkflowException
      */
     public void setDoNotReceiveFutureRequests() throws WorkflowException {
         WorkflowUtility workflowUtility = getWorkflowUtility();
         this.setVariable(workflowUtility.getFutureRequestsKey(principalId), workflowUtility.getDoNotReceiveFutureRequestsValue());
     }
 
     /**
      * Clears any state set on the document regarding a user receiving or not receiving action requests.  Uses the setVariable method
      * behind the seens so an action needs taken on the document to set this state on the document.
      *
      * @throws WorkflowException
      */
     public void setClearFutureRequests() throws WorkflowException {
         WorkflowUtility workflowUtility = getWorkflowUtility();
         this.setVariable(workflowUtility.getFutureRequestsKey(principalId), workflowUtility.getClearFutureRequestsValue());
     }
 
     /**
      * Deletes the note of with the same id as that of the argument on the document.
      * @param noteVO the note to test for deletion
      * @return whether the note is already marked for deletion.
      */
     private boolean isDeletedNote(NoteDTO noteVO) {
             NoteDTO[] notesToDelete = routeHeader.getNotesToDelete();
             if (notesToDelete != null){
                     for (int i=0; i<notesToDelete.length; i++){
                             if (notesToDelete[i].getNoteId().equals(noteVO.getNoteId())){
                                     return true;
                             }
                     }
             }
             return false;
     }
 
     /**
      * Increases the size of the routeHeader notes VO array
      */
    private void increaseNotesArraySizeByOne() {
            NoteDTO[] tempArray;
            NoteDTO[] notes = routeHeader.getNotes();
            if (notes == null){
                    tempArray = new NoteDTO[1];
            } else {
                    tempArray = new NoteDTO[notes.length + 1];
                    for (int i=0; i<notes.length; i++){
                            tempArray[i] = notes[i];
                    }
            }
            routeHeader.setNotes(tempArray);
    }
 
    /**
     * Increases the size of the routeHeader notesToDelete VO array
     */
    private void increaseNotesToDeleteArraySizeByOne() {
            NoteDTO[] tempArray;
            NoteDTO[] notesToDelete = routeHeader.getNotesToDelete();
            if (notesToDelete == null){
                    tempArray = new NoteDTO[1];
            } else {
                    tempArray = new NoteDTO[notesToDelete.length + 1];
                    for (int i=0; i<notesToDelete.length; i++){
                            tempArray[i] = notesToDelete[i];
                    }
            }
            routeHeader.setNotesToDelete(tempArray);
    }
    
    //add 1 link between 2 docs by DTO, double link added
    public void addLinkedDocument(DocumentLinkDTO docLinkVO) throws WorkflowException{
            try{
                    if(DocumentLinkDTO.checkDocLink(docLinkVO))
                            getWorkflowUtility().addDocumentLink(docLinkVO);
            }
            catch(Exception e){
                    throw handleExceptionAsRuntime(e); 
            } 
    }
    
    //get link from orgn doc to a specifc doc
    public DocumentLinkDTO getLinkedDocument(DocumentLinkDTO docLinkVO) throws WorkflowException{
            try{
                    if(DocumentLinkDTO.checkDocLink(docLinkVO))
                            return getWorkflowUtility().getLinkedDocument(docLinkVO);
                    else
                            return null;
            }
            catch(Exception e){
                    throw handleExceptionAsRuntime(e); 
            }
    }
    
    //get all links to orgn doc
    public List<DocumentLinkDTO> getLinkedDocumentsByDocId(Long id) throws WorkflowException{
            if(id == null)
                    throw new WorkflowException("doc id is null");
            try{   
                    return getWorkflowUtility().getLinkedDocumentsByDocId(id);
            } 
            catch (Exception e) {
                    throw handleExceptionAsRuntime(e);
            }
    }
    
    //remove all links from orgn: double links removed
    public void removeLinkedDocuments(Long docId) throws WorkflowException{
            
            if(docId == null)
                    throw new WorkflowException("doc id is null");
            
            try{   
                    getWorkflowUtility().deleteDocumentLinksByDocId(docId);
            } 
            catch (Exception e) {
                    throw handleExceptionAsRuntime(e);
            }
    }
    
    //remove link between 2 docs, double link removed
    public void removeLinkedDocument(DocumentLinkDTO docLinkVO) throws WorkflowException{
            
            try{
                    if(DocumentLinkDTO.checkDocLink(docLinkVO))
                            getWorkflowUtility().deleteDocumentLink(docLinkVO);
            }
            catch(Exception e){
                    throw handleExceptionAsRuntime(e); 
            } 
    }
 
 }