001/**
002 * Copyright 2005-2016 The Kuali Foundation
003 *
004 * Licensed under the Educational Community License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.opensource.org/licenses/ecl2.php
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016package org.kuali.rice.kew.engine.node.service;
017
018import org.kuali.rice.kew.doctype.bo.DocumentType;
019import org.kuali.rice.kew.engine.node.Branch;
020import org.kuali.rice.kew.engine.node.NodeGraphSearchCriteria;
021import org.kuali.rice.kew.engine.node.NodeGraphSearchResult;
022import org.kuali.rice.kew.engine.node.NodeState;
023import org.kuali.rice.kew.engine.node.ProcessDefinitionBo;
024import org.kuali.rice.kew.engine.node.RouteNode;
025import org.kuali.rice.kew.engine.node.RouteNodeInstance;
026import org.kuali.rice.kew.routeheader.DocumentRouteHeaderValue;
027
028import java.util.List;
029
030
031/**
032 * A service which provides data access for {@link RouteNode}, {@link RouteNodeInstance}, 
033 * {@link NodeState}, and {@link Branch} objects.
034 * 
035 * @author Kuali Rice Team (rice.collab@kuali.org)
036 */
037public interface RouteNodeService {
038
039    public RouteNode save(RouteNode node);
040    public RouteNodeInstance save(RouteNodeInstance nodeInstance);
041    public void save(NodeState nodeState);
042    public Branch save(Branch branch);
043    public RouteNode findRouteNodeById(String nodeId);
044    public RouteNodeInstance findRouteNodeInstanceById(String nodeInstanceId);
045    
046    /**
047     * 
048     * This method looks though the passed in DocumentRouteHeaderValue and retrieves a nodeInstance that
049     * matches the ID passed in. 
050     * 
051     * @param nodeInstanceId
052     * @param document
053     * @return
054     */
055    public RouteNodeInstance findRouteNodeInstanceById(String nodeInstanceId, DocumentRouteHeaderValue document);
056
057    /**
058     * Retrieves the initial node instances of the given document.  The initial node instances are 
059     * those node instances which are at the very beginning of the route.  Usually, this will
060     * just be a single node instance.
061     */
062    public List getInitialNodeInstances(String documentId);
063
064    /**
065     * Retrieves the active node instances of the given Document.  The active node instances
066     * represent where in the route path the document is currently located.
067     * @param documentId of the document
068     * @return list of route node instances
069     */
070    public List<RouteNodeInstance> getActiveNodeInstances(String documentId);
071
072    /**
073     * Retrieves the names of the route node instances where the document is currently located
074     * for the document with the given id. This could be active nodes in the document if it is
075     * in the middle of the routing process or it could be the names of the terminal nodes if
076     * the document has completed routing.
077     *
078     * @param documentId of the document
079     * @return list of names of the current route node instances
080     * @since 2.1
081     */
082    public List<String> getCurrentRouteNodeNames(String documentId);
083
084    /**
085     * Retrieves the names of active node instances for the document with the
086     * given id.  The active node instances represent where in the route path
087     * the document is currently located.
088     * @param documentId of the document
089     * @return list of names of route node instances
090     * @since 2.1
091     */
092    public List<String> getActiveRouteNodeNames(String documentId);
093    
094    public List<RouteNodeInstance> getActiveNodeInstances(DocumentRouteHeaderValue document);
095    
096    /**
097     * Retrieves the names of terminal node instances for the document with the
098     * given id. The terminal node instances are nodes in the route path which
099     * are both inactive and complete and have no next nodes in their path.
100     * Terminal node instances will typically only exist on documents which are
101     * no longer enroute.
102     * @param documentId for the given Document
103     * @return list of terminal node instances
104     * @since 2.1
105     */
106    public List<String> getTerminalRouteNodeNames(String documentId);
107    
108    /**
109     * Retrieves the terminal node instances of the given Document.  The terminal node instances
110     * are nodes in the route path which are both inactive and complete and have no next nodes
111     * in their path.  Terminal node instances will typically only exist on documents which are no
112     * longer Enroute.
113     * @param documentId for the given Document
114     * @return list of terminal node instances
115     */
116    public List<RouteNodeInstance> getTerminalNodeInstances(String documentId);
117    
118    /**
119     * Returns the node instances representing the most recent node instances in the document.
120     * The algorithm for locating the current nodes is as follows: If the document has
121     * active node instances, return those, otherwise return it's terminal node instances.
122     */
123    public List<RouteNodeInstance> getCurrentNodeInstances(String documentId);
124
125    public NodeState findNodeState(Long nodeInstanceId, String key);
126    public RouteNode findRouteNodeByName(String documentTypeId, String name);
127    public List<RouteNode> findFinalApprovalRouteNodes(String documentTypeId);
128    public List findNextRouteNodesInPath(RouteNodeInstance nodeInstance, String nodeName);
129    public boolean isNodeInPath(DocumentRouteHeaderValue document, String nodeName);
130    public List findRouteNodeInstances(String documentId);
131    public List findProcessNodeInstances(RouteNodeInstance process);
132    public List<String> findPreviousNodeNames(String documentId);
133    
134    /**
135     * Returns a List of the distinct node names through which this document might pass in it's future 
136     * routing.  In certain cases this will be an approximation based on what the system knows at the
137     * time of execution. 
138     */
139    public List<String> findFutureNodeNames(String documentId);
140    
141    /**
142     * Flatten all the document types route nodes into a single List.  This includes all processes 
143     * on the DocumentType.
144     * 
145     * @param documentType DocumentType who's nodes will be flattened.
146     * @param climbHierarchy whether to include the parents nodes if the passed in DocumentType contains no nodes
147     * @return List or empty List
148     */
149    public List<RouteNode> getFlattenedNodes(DocumentType documentType, boolean climbHierarchy);
150    public List<RouteNode> getFlattenedNodes(ProcessDefinitionBo process);
151    
152    /**
153     * Returns a flattened list of RouteNodeInstances on the given document.  If the includeProcesses flag is
154     * true than this method includes process RouteNodeInstances, otherwise they are excluded.
155     * which are processes.
156     * @param document route header value
157     * @param includeProcesses flag
158     * @return list of routeNodeInstances
159     */
160    public List<RouteNodeInstance> getFlattenedNodeInstances(DocumentRouteHeaderValue document, boolean includeProcesses);
161    
162    public NodeGraphSearchResult searchNodeGraph(NodeGraphSearchCriteria criteria);
163    
164    /**
165     * Returns a list of active node instances associated with the document that are active
166     * @param document
167     * @param nodeName
168     * @return
169     */
170    public List<RouteNodeInstance> getActiveNodeInstances(DocumentRouteHeaderValue document, String nodeName);
171        public void deleteByRouteNodeInstance(RouteNodeInstance routeNodeInstance);
172    public void deleteNodeStateById(Long nodeStateId);
173    public void deleteNodeStates(List statesToBeDeleted);
174    
175    /**
176         * Record that the given RouteNodeInstance on the Document was revoked.  This will happen when an 
177         * action such as Return to Previous or Move Document bypasses the given RouteNodeInstance on it's
178         * path back to a previous point in the history of the document's route path. 
179         */
180    public void revokeNodeInstance(DocumentRouteHeaderValue document, RouteNodeInstance nodeInstance);
181    
182    /**
183     * Returns a List of the revoked RouteNodeInstances on the given Document.
184     * 
185     * @see revokeNodeInstance
186     */
187    public List getRevokedNodeInstances(DocumentRouteHeaderValue document);
188    
189}