001/**
002 * Copyright 2005-2017 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 the simple route node instances where the document is currently located
086     * for the document with the given id. This could be active nodes in the document if it is
087     * in the middle of the routing process or it could be the names of the terminal nodes if
088     * the document has completed routing.
089     *
090     * @param documentId of the document
091     * @return list of names of the current simple route node instances
092     * @since 2.6
093     */
094    public List<String> getCurrentSimpleRouteNodeNames(String documentId);
095
096
097    /**
098     * Retrieves the names of active node instances for the document with the
099     * given id.  The active node instances represent where in the route path
100     * the document is currently located.
101     * @param documentId of the document
102     * @return list of names of route node instances
103     * @since 2.1
104     */
105    public List<String> getActiveRouteNodeNames(String documentId);
106
107    /**
108     * Retrieves the names of active node instances for simple nodes for the document with the
109     * given id.  The active node instances represent where in the route path
110     * the document is currently located, and simple nodes are only those nodes whose type
111     * extend from {@link org.kuali.rice.kew.engine.node.SimpleNode}.
112     *
113     * @param documentId of the document
114     * @return list of names of the active simple route node instances
115     * @since 2.1
116     */
117    public List<String> getActiveSimpleRouteNodeNames(String documentId);
118
119
120    public List<RouteNodeInstance> getActiveNodeInstances(DocumentRouteHeaderValue document);
121    
122    /**
123     * Retrieves the names of terminal node instances for the document with the
124     * given id. The terminal node instances are nodes in the route path which
125     * are both inactive and complete and have no next nodes in their path.
126     * Terminal node instances will typically only exist on documents which are
127     * no longer enroute.
128     * @param documentId for the given Document
129     * @return list of terminal node instances
130     * @since 2.1
131     */
132    public List<String> getTerminalRouteNodeNames(String documentId);
133    
134    /**
135     * Retrieves the terminal node instances of the given Document.  The terminal node instances
136     * are nodes in the route path which are both inactive and complete and have no next nodes
137     * in their path.  Terminal node instances will typically only exist on documents which are no
138     * longer Enroute.
139     * @param documentId for the given Document
140     * @return list of terminal node instances
141     */
142    public List<RouteNodeInstance> getTerminalNodeInstances(String documentId);
143    
144    /**
145     * Returns the node instances representing the most recent node instances in the document.
146     * The algorithm for locating the current nodes is as follows: If the document has
147     * active node instances, return those, otherwise return it's terminal node instances.
148     */
149    public List<RouteNodeInstance> getCurrentNodeInstances(String documentId);
150
151    public NodeState findNodeState(Long nodeInstanceId, String key);
152    public RouteNode findRouteNodeByName(String documentTypeId, String name);
153    public List<RouteNode> findFinalApprovalRouteNodes(String documentTypeId);
154    public List findNextRouteNodesInPath(RouteNodeInstance nodeInstance, String nodeName);
155    public boolean isNodeInPath(DocumentRouteHeaderValue document, String nodeName);
156    public List findRouteNodeInstances(String documentId);
157    public List findProcessNodeInstances(RouteNodeInstance process);
158    public List<String> findPreviousNodeNames(String documentId);
159    
160    /**
161     * Returns a List of the distinct node names through which this document might pass in it's future 
162     * routing.  In certain cases this will be an approximation based on what the system knows at the
163     * time of execution. 
164     */
165    public List<String> findFutureNodeNames(String documentId);
166    
167    /**
168     * Flatten all the document types route nodes into a single List.  This includes all processes 
169     * on the DocumentType.
170     * 
171     * @param documentType DocumentType who's nodes will be flattened.
172     * @param climbHierarchy whether to include the parents nodes if the passed in DocumentType contains no nodes
173     * @return List or empty List
174     */
175    public List<RouteNode> getFlattenedNodes(DocumentType documentType, boolean climbHierarchy);
176    public List<RouteNode> getFlattenedNodes(ProcessDefinitionBo process);
177    
178    /**
179     * Returns a flattened list of RouteNodeInstances on the given document.  If the includeProcesses flag is
180     * true than this method includes process RouteNodeInstances, otherwise they are excluded.
181     * which are processes.
182     * @param document route header value
183     * @param includeProcesses flag
184     * @return list of routeNodeInstances
185     */
186    public List<RouteNodeInstance> getFlattenedNodeInstances(DocumentRouteHeaderValue document, boolean includeProcesses);
187    
188    public NodeGraphSearchResult searchNodeGraph(NodeGraphSearchCriteria criteria);
189    
190    /**
191     * Returns a list of active node instances associated with the document that are active
192     * @param document
193     * @param nodeName
194     * @return
195     */
196    public List<RouteNodeInstance> getActiveNodeInstances(DocumentRouteHeaderValue document, String nodeName);
197        public void deleteByRouteNodeInstance(RouteNodeInstance routeNodeInstance);
198    public void deleteNodeStateById(Long nodeStateId);
199    public void deleteNodeStates(List statesToBeDeleted);
200    
201    /**
202         * Record that the given RouteNodeInstance on the Document was revoked.  This will happen when an 
203         * action such as Return to Previous or Move Document bypasses the given RouteNodeInstance on it's
204         * path back to a previous point in the history of the document's route path. 
205         */
206    public void revokeNodeInstance(DocumentRouteHeaderValue document, RouteNodeInstance nodeInstance);
207    
208    /**
209     * Returns a List of the revoked RouteNodeInstances on the given Document.
210     * 
211     * @see revokeNodeInstance
212     */
213    public List getRevokedNodeInstances(DocumentRouteHeaderValue document);
214    
215}