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.api.document;
017
018import org.joda.time.DateTime;
019import org.kuali.rice.core.api.exception.RiceIllegalArgumentException;
020import org.kuali.rice.core.api.exception.RiceIllegalStateException;
021import org.kuali.rice.core.api.util.jaxb.DateTimeAdapter;
022import org.kuali.rice.core.api.util.jaxb.MapStringStringAdapter;
023import org.kuali.rice.kew.api.KewApiConstants;
024import org.kuali.rice.kew.api.action.ActionRequest;
025import org.kuali.rice.kew.api.action.ActionTaken;
026import org.kuali.rice.kew.api.document.search.DocumentSearchCriteria;
027import org.kuali.rice.kew.api.document.search.DocumentSearchResults;
028import org.kuali.rice.kew.api.document.node.RouteNodeInstance;
029
030import javax.jws.WebMethod;
031import javax.jws.WebParam;
032import javax.jws.WebResult;
033import javax.jws.WebService;
034import javax.jws.soap.SOAPBinding;
035import javax.xml.bind.annotation.XmlElement;
036import javax.xml.bind.annotation.XmlElementWrapper;
037import javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter;
038import java.math.BigDecimal;
039import java.util.List;
040import java.util.Map;
041
042/**
043 * TODO ... annotate for JAX-WS! 
044 * 
045 * @author Kuali Rice Team (rice.collab@kuali.org)
046 */
047@WebService(name = "workflowDocumentService", targetNamespace = KewApiConstants.Namespaces.KEW_NAMESPACE_2_0)
048@SOAPBinding(style = SOAPBinding.Style.DOCUMENT, use = SOAPBinding.Use.LITERAL, parameterStyle = SOAPBinding.ParameterStyle.WRAPPED)
049public interface WorkflowDocumentService {
050
051    /**
052     * Gets a {@link Document} from a documentId.
053     *
054     * <p>
055     *   This method will return null if the Document does not exist.
056     * </p>
057     *
058     * @param documentId the unique id of the document to return
059     * @return the document with the passed in id value
060     * @throws RiceIllegalArgumentException if {@code documentId} is null
061     */
062    @WebMethod(operationName = "getDocument")
063    @WebResult(name = "document")
064        Document getDocument(@WebParam(name = "documentId") String documentId) throws RiceIllegalArgumentException;
065
066    /**
067     * Returns a boolean depending on if a {@link Document} exists with the specified documentId
068     *
069     * <p>
070     *   This method will return false if the responsibility does not exist.
071     * </p>
072     *
073     * @param documentId the unique id of the document to check for existence
074     * @return boolean value representative of whether the document exists
075     * @throws RiceIllegalArgumentException if {@code documentId} is null
076     */
077    @WebMethod(operationName = "doesDocumentExist")
078    @WebResult(name = "document")
079        boolean doesDocumentExist(@WebParam(name = "documentId") String documentId)
080            throws RiceIllegalArgumentException;
081
082    /**
083     * Gets {@link DocumentContent} from a documentId.
084     *
085     * <p>
086     *   This method will return null if the document does not exist.
087     * </p>
088     *
089     * @param documentId the unique id of the document content to return
090     * @return the documentContent with the passed in id value
091     * @throws RiceIllegalArgumentException if {@code documentId} is null
092     */
093    @WebMethod(operationName = "getDocumentContent")
094    @WebResult(name = "documentContent")
095        DocumentContent getDocumentContent(@WebParam(name = "documentId") String documentId)
096            throws RiceIllegalArgumentException;
097
098    /**
099     * Gets a list of root ActionRequests for a given documentId
100     *
101     * @param documentId the unique id of a document
102     *
103     * @return the list of root ActionRequests for a given documentId
104     *
105     * @throws RiceIllegalArgumentException if {@code documentId} is null
106     */
107    @WebMethod(operationName = "getRootActionRequests")
108    @XmlElementWrapper(name = "rootActionRequests", required = true)
109    @XmlElement(name = "rootActionRequest", required = false)
110    @WebResult(name = "rootActionRequests")
111        List<ActionRequest> getRootActionRequests(@WebParam(name = "documentId") String documentId)
112            throws RiceIllegalArgumentException;
113    
114    /**
115     * Gets a list of ActionRequests which are pending for a given documentId
116     * 
117     * @since 2.1
118     * @param documentId the unique id of a document
119     * @return the list of pending ActionRequests for a given documentId
120     * @throws RiceIllegalArgumentException if {@code documentId} is null
121     */
122    @WebMethod(operationName = "getPendingActionRequests")
123    @XmlElementWrapper(name = "pendingActionRequests", required = true)
124    @XmlElement(name = "pendingActionRequest", required = false)
125    @WebResult(name = "pendingActionRequests")
126    List<ActionRequest> getPendingActionRequests(String documentId);
127
128    /**
129     * Gets a list of ActionRequests for a given documentId, nodeName and principalId
130     *
131     * @param documentId the unique id of a document
132     * @param nodeName the name of a RouteNode
133     * @param principalId the unique id of a principal
134     *
135     * @return the list of ActionRequests for a given documentId, nodeName, and principalId
136     *
137     * @throws RiceIllegalArgumentException if {@code documentId} is null
138     */
139    @WebMethod(operationName = "getActionRequestsForPrincipalAtNode")
140    @XmlElementWrapper(name = "actionRequests", required = true)
141    @XmlElement(name = "actionRequests", required = false)
142    @WebResult(name = "actionRequests")
143        List<ActionRequest> getActionRequestsForPrincipalAtNode(@WebParam(name = "documentId") String documentId,
144            @WebParam(name = "nodeName") String nodeName, @WebParam(name = "principalId") String principalId)
145            throws RiceIllegalArgumentException;
146
147    /**
148     * Gets a list of past {@link ActionTaken} of a {@link Document} with the given documentId
149     *
150     * @param documentId the unique id of a document
151     *
152     * @return the list of past ActionTakens for a given documentId
153     *
154     * @throws RiceIllegalArgumentException if {@code documentId} is null
155     */
156    @WebMethod(operationName = "getActionsTaken")
157    @XmlElementWrapper(name = "actionsTaken", required = true)
158    @XmlElement(name = "actionTaken", required = false)
159    @WebResult(name = "actionsTaken")
160        List<ActionTaken> getActionsTaken(@WebParam(name = "documentId") String documentId)
161            throws RiceIllegalArgumentException;
162
163    /**
164     * @deprecated mistaken operation name...use getActionsTaken instead
165     *
166     * @param documentId the unique id of a document
167     *
168     * @return the list of past ActionTakens for a given documentId
169     *
170     * @throws RiceIllegalArgumentException if {@code documentId} is null
171     */
172    @WebMethod(operationName = "getActionRequests")
173    @XmlElementWrapper(name = "actionsTaken", required = true)
174    @XmlElement(name = "actionTaken", required = false)
175    @WebResult(name = "actionsTaken")
176    @Deprecated
177    List<ActionTaken> _getActionsTaken(@WebParam(name = "documentId") String documentId)
178            throws RiceIllegalArgumentException;
179
180
181    /**
182    * Gets a list of all {@link ActionTaken} of a {@link Document} with the given documentId
183    *
184    * @since 2.0.2
185    *
186    * @param documentId the unique id of a document
187    *
188    * @return the list of ActionTakens (both current and not) for a given documentId
189    *
190    * @throws RiceIllegalArgumentException if {@code documentId} is null
191    */
192      @WebMethod(operationName = "getAllActionRequests")
193      @XmlElementWrapper(name = "actionsTaken", required = true)
194      @XmlElement(name = "actionTaken", required = false)
195      @WebResult(name = "actionsTaken")
196      List<ActionTaken> getAllActionsTaken(@WebParam(name = "documentId") String documentId)
197              throws RiceIllegalArgumentException;
198
199
200    /**
201     * Gets a {@link DocumentDetail} of a {@link Document} with the given documentTypeName and appId
202     *
203     * @param documentTypeName the name of the DocumentType
204     * @param appId the unique id of the application
205     *
206     * @return a {@link DocumentDetail} for with the given documentTypeName and appId
207     *
208     * @throws RiceIllegalArgumentException if {@code documentTypeName} is null
209     * @throws RiceIllegalArgumentException if {@code appId} is null
210     */
211    @WebMethod(operationName = "getDocumentDetailByAppId")
212    @WebResult(name = "documentDetail")
213    DocumentDetail getDocumentDetailByAppId(@WebParam(name = "documentTypeName") String documentTypeName,
214                                            @WebParam(name = "appId") String appId)
215            throws RiceIllegalArgumentException;
216
217    /**
218     * Gets a {@link DocumentDetail} of a {@link Document} with the given documentId
219     *
220     * @param documentId the unique id of the Document
221     *
222     * @return a {@link DocumentDetail} for with the given documentId
223     *
224     * @throws RiceIllegalArgumentException if {@code documentId} is null
225     */
226    @WebMethod(operationName = "getDocumentDetail")
227    @WebResult(name = "documentDetail")
228        DocumentDetail getDocumentDetail(@WebParam(name = "documentId") String documentId);
229
230
231    /**
232     * Gets a {@link RouteNodeInstance} with the given nodeInstanceId
233     *
234     * @param routeNodeInstanceId the unique id of the {@link RouteNodeInstance}
235     *
236     * @return a {@link DocumentDetail} for with the given documentId
237     *
238     * @throws RiceIllegalArgumentException if {@code nodeInstanceId} is null
239     */
240    @WebMethod(operationName = "getRouteNodeInstance")
241    @WebResult(name = "routeNodeInstance")
242        RouteNodeInstance getRouteNodeInstance(@WebParam(name = "routeNodeInstanceId") String routeNodeInstanceId)
243            throws RiceIllegalArgumentException;
244
245    /**
246     * Gets a value application document id of a {@link Document} with the given documentId
247     *
248     * @param documentId the unique id of the Document
249     *
250     * @return the value of the applicationDocumentId for the {@link Document} with the given documentId
251     *
252     * @throws RiceIllegalArgumentException if {@code documentId} is null
253     */
254    @WebMethod(operationName = "getApplicationDocumentId")
255    @WebResult(name = "applicationDocumentId")
256        String getApplicationDocumentId(@WebParam(name = "documentId") String documentId)
257            throws RiceIllegalArgumentException;
258
259    /**
260     * Gets a value application document status of a {@link org.kuali.rice.kew.api.document.Document} with the given documentId
261     *
262     * @param documentId the unique id of the Document
263     *
264     * @return the value of the applicationDocumentStatus for the {@link org.kuali.rice.kew.api.document.Document} with the given documentId
265     *
266     * @throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException if {@code documentId} is null
267     */
268    @WebMethod(operationName = "getApplicationDocumentStatus")
269    @WebResult(name = "applicationDocumentStatus")
270    String getApplicationDocumentStatus(@WebParam(name = "documentId") String documentId)
271            throws RiceIllegalArgumentException;
272
273    /**
274     * Executes a search for workflow documents using the given criteria and as the principal with the given id.  Since
275     * documents can define security which permits access to view certain search results, the given principal id will
276     * be used when evaluating which documents should be filtered from the results because of lack of access.
277     *
278     * @param principalId the id of the principal to execute the search as, if this value is non-null then security
279     * filtering will be executed against the results, if it is null then no filtering will be performed
280     * @param criteria the criteria to use when executing the search
281     *
282     * @return the results of the search, this will never be null but may contain an empty list of results
283     *
284     * @throws RiceIllegalArgumentException if the given criteria is null
285     */
286    @WebMethod(operationName = "documentSearch")
287    @WebResult(name = "documentSearchResults")
288    DocumentSearchResults documentSearch(
289            @WebParam(name = "principalId") String principalId,
290            @WebParam(name = "criteria") DocumentSearchCriteria criteria)
291        throws RiceIllegalArgumentException;
292
293    /**
294     * Gets a list of all {@link RouteNodeInstance} for a {@link Document} with the given documentId
295     *
296     * @param documentId the unique id of a Document
297     *
298     * @return the list of {@link RouteNodeInstance}s for the {@link Document} with the given documentId
299     *
300     * @throws RiceIllegalArgumentException if {@code documentId} is null
301     */
302    @WebMethod(operationName = "getRouteNodeInstances")
303    @XmlElementWrapper(name = "routeNodeInstances", required = true)
304    @XmlElement(name = "routeNodeInstance", required = false)
305    @WebResult(name = "routeNodeInstances")
306        List<RouteNodeInstance> getRouteNodeInstances(@WebParam(name = "documentId") String documentId)
307            throws RiceIllegalArgumentException;
308
309    /**
310     * Gets a list of active {@link RouteNodeInstance} for a {@link Document} with the given documentId
311     *
312     * @param documentId the unique id of a Document
313     *
314     * @return the list of active {@link RouteNodeInstance}s for the {@link Document} with the given documentId
315     *
316     * @throws RiceIllegalArgumentException if {@code documentId} is null
317     */
318    @WebMethod(operationName = "getActiveRouteNodeInstances")
319    @XmlElementWrapper(name = "routeNodeInstances", required = true)
320    @XmlElement(name = "routeNodeInstance", required = false)
321    @WebResult(name = "routeNodeInstances")
322        List<RouteNodeInstance> getActiveRouteNodeInstances(@WebParam(name = "documentId") String documentId)
323            throws RiceIllegalArgumentException;
324
325    /**
326     * Gets a list of terminal {@link RouteNodeInstance}s for a {@link Document} with the given documentId
327     *
328     * @param documentId the unique id of a Document
329     *
330     * @return the list of terminal {@link RouteNodeInstance}s for the {@link Document} with the given documentId
331     *
332     * @throws RiceIllegalArgumentException if {@code documentId} is null
333     */
334    @WebMethod(operationName = "getTerminalRouteNodeInstances")
335    @XmlElementWrapper(name = "routeNodeInstances", required = true)
336    @XmlElement(name = "routeNodeInstance", required = false)
337    @WebResult(name = "routeNodeInstances")
338        List<RouteNodeInstance> getTerminalRouteNodeInstances(@WebParam(name = "documentId") String documentId)
339            throws RiceIllegalArgumentException;
340
341    /**
342     * Gets a list of current {@link RouteNodeInstance}s for a {@link Document} with the given documentId
343     *
344     * @param documentId the unique id of a Document
345     *
346     * @return the list of current {@link RouteNodeInstance}s for the {@link Document} with the given documentId
347     *
348     * @throws RiceIllegalArgumentException if {@code documentId} is null
349     */
350    @WebMethod(operationName = "getCurrentRouteNodeInstances")
351    @XmlElementWrapper(name = "routeNodeInstances", required = true)
352    @XmlElement(name = "routeNodeInstance", required = false)
353    @WebResult(name = "routeNodeInstances")
354        List<RouteNodeInstance> getCurrentRouteNodeInstances(@WebParam(name = "documentId") String documentId)
355            throws RiceIllegalArgumentException;
356
357    /**
358     * Gets a list of all previous {@link RouteNodeInstance}'s node names for a {@link Document} with the given documentId
359     *
360     * @param documentId the unique id of a Document
361     *
362     * @return the list of all previous {@link RouteNodeInstance}'s node names for the {@link Document} with the
363     * given documentId
364     *
365     * @throws RiceIllegalArgumentException if {@code documentId} is null
366     */
367    @WebMethod(operationName = "getPreviousRouteNodeNames")
368    @XmlElementWrapper(name = "previousRouteNodeNames", required = true)
369    @XmlElement(name = "previousRouteNodeName", required = false)
370    @WebResult(name = "previousRouteNodeNames")
371        List<String> getPreviousRouteNodeNames(@WebParam(name = "documentId") String documentId)
372            throws RiceIllegalArgumentException;
373
374        /**
375     * Gets the status value for a {@link Document} with the given documentId
376     *
377     * @param documentId the unique id of a Document
378     *
379     * @return the current status of the {@link Document} with the
380     * given documentId
381     *
382     * @throws RiceIllegalArgumentException if {@code documentId} is null
383     */
384    @WebMethod(operationName = "getDocumentStatus")
385    @WebResult(name = "documentStatus")
386        DocumentStatus getDocumentStatus(@WebParam(name = "documentId") String documentId)
387            throws RiceIllegalArgumentException;
388
389
390    /**
391     * Gets a list of principalId values for a {@link Document} with the given documentId
392     * and action request code that have pending action requests
393     *
394     * @param actionRequestedCd code for the pending action requested
395     * @param documentId the unique id of a Document
396     *
397     * @return a list of principalIds for the {@link Document} with the
398     * given parameters and have a pending action request
399     *
400     * @throws RiceIllegalArgumentException if {@code documentId} is null
401     * @throws RiceIllegalArgumentException if {@code actionRequestCd} is null
402     */
403    @WebMethod(operationName = "getPrincipalIdsWithPendingActionRequestByActionRequestedAndDocId")
404    @XmlElementWrapper(name = "principalIds", required = true)
405    @XmlElement(name = "principalId", required = false)
406    @WebResult(name = "principalIds")
407        List<String> getPrincipalIdsWithPendingActionRequestByActionRequestedAndDocId(
408                    @WebParam(name = "actionRequestedCd") String actionRequestedCd,
409                            @WebParam(name = "documentId") String documentId)
410            throws RiceIllegalArgumentException;
411
412
413    /**
414     * Gets the {@link Document} initiator's principalId with the given documentId
415     *
416     * @param documentId the unique id of a Document
417     *
418     * @return the {@link Document} initiator's principalId
419     *
420     * @throws RiceIllegalArgumentException if {@code documentId} is null
421     */
422    @WebMethod(operationName = "getDocumentInitiatorPrincipalId")
423    @WebResult(name = "principalId")
424        String getDocumentInitiatorPrincipalId(@WebParam(name = "documentId") String documentId)
425            throws RiceIllegalArgumentException;
426
427    /**
428     * Gets the {@link Document}'s 'routed by' principalId with the given documentId
429     * Returns null if the document is not found
430     *
431     * @param documentId the unique id of a Document
432     *
433     * @return the {@link Document}'s 'routed by' principalId
434     *
435     * @throws RiceIllegalArgumentException if {@code documentId} is null
436     */
437    @WebMethod(operationName = "getRoutedByPrincipalIdByDocumentId")
438    @WebResult(name = "principalId")
439        String getRoutedByPrincipalIdByDocumentId(@WebParam(name = "documentId") String documentId)
440            throws RiceIllegalArgumentException;
441
442    /**
443     * Does a direct search for searchableAttributes without going through the document search
444     * This returns a list of String values for String searchableAttributes
445     *
446     * @param documentId the unique id of a Document
447     * @param key the searchableAttributes key value
448     *
449     * @return a list of String values for the {@link Document} with the
450     * given documentId and searchable attribute key
451     *
452     * @throws RiceIllegalArgumentException if {@code documentId} is null
453     * @throws RiceIllegalArgumentException if {@code key} is null
454     */
455    @WebMethod(operationName = "getSearchableAttributeStringValuesByKey")
456    @XmlElementWrapper(name = "searchableAttributeStringValues", required = true)
457    @XmlElement(name = "searchableAttributeStringValue", required = false)
458    @WebResult(name = "searchableAttributeStringValues")
459        List<String> getSearchableAttributeStringValuesByKey(@WebParam(name = "documentId") String documentId,
460                                                                     @WebParam(name = "key") String key)
461            throws RiceIllegalArgumentException;
462
463        /**
464     * Does a direct search for searchableAttributes without going through the document search
465     * This returns a list of DateTime values for date/time searchableAttributes
466     *
467     * @param documentId the unique id of a Document
468     * @param key the searchableAttributes key value
469     *
470     * @return a list of DateTime values for the {@link Document} with the
471     * given documentId and searchable attribute key
472     *
473     * @throws RiceIllegalArgumentException if {@code documentId} is null
474     * @throws RiceIllegalArgumentException if {@code key} is null
475     */
476    @WebMethod(operationName = "getSearchableAttributeDateTimeValuesByKey")
477    @XmlElementWrapper(name = "searchableAttributeDateTimeValues", required = true)
478    @XmlElement(name = "searchableAttributeDateTimeValue", required = false)
479    @WebResult(name = "searchableAttributeDateTimeValues")
480        @XmlJavaTypeAdapter(value = DateTimeAdapter.class)
481        List<DateTime> getSearchableAttributeDateTimeValuesByKey(@WebParam(name = "documentId") String documentId,
482                                                                         @WebParam(name = "key") String key)
483            throws RiceIllegalArgumentException;
484
485        /**
486     * Does a direct search for searchableAttributes without going through the document search
487     * This returns a list of BigDecimal values for decimal searchableAttributes
488     *
489     * @param documentId the unique id of a Document
490     * @param key the searchableAttributes key value
491     *
492     * @return a list of BigDecimal values for the {@link Document} with the
493     * given documentId and searchable attribute key
494     *
495     * @throws RiceIllegalArgumentException if {@code documentId} is null
496     * @throws RiceIllegalArgumentException if {@code key} is null
497     */
498    @WebMethod(operationName = "getSearchableAttributeFloatValuesByKey")
499    @XmlElementWrapper(name = "searchableAttributeBigDecimalValues", required = true)
500    @XmlElement(name = "searchableAttributeBigDecimalValue", required = false)
501    @WebResult(name = "searchableAttributeBigDecimalValues")
502        List<BigDecimal> getSearchableAttributeFloatValuesByKey(@WebParam(name = "documentId") String documentId,
503                                                                        @WebParam(name = "key") String key)
504            throws RiceIllegalArgumentException;
505
506        /**
507     * Does a direct search for searchableAttributes without going through the document search
508     * This returns a list of Long values for long searchableAttributes
509     *
510     * @param documentId the unique id of a Document
511     * @param key the searchableAttributes key value
512     *
513     * @return a list of BigDecimal values for the {@link Document} with the
514     * given documentId and searchable attribute key
515     *
516     * @throws RiceIllegalArgumentException if {@code documentId} is null
517     * @throws RiceIllegalArgumentException if {@code key} is null
518     */
519    @WebMethod(operationName = "getSearchableAttributeLongValuesByKey")
520    @XmlElementWrapper(name = "searchableAttributeLongValues", required = true)
521    @XmlElement(name = "searchableAttributeLongValue", required = false)
522    @WebResult(name = "searchableAttributeLongValues")
523        List<Long> getSearchableAttributeLongValuesByKey(@WebParam(name = "documentId") String documentId,
524                                                                 @WebParam(name = "key") String key)
525            throws RiceIllegalArgumentException;
526
527    /**
528     * Gets a list of DocumentStatusTransitions for the {@link Document} with the given documentId
529     *
530     * @param documentId the unique id of a Document
531     *
532     * @return a list of DocumentStatusTransitions for the {@link Document} with the
533     * given documentId
534     *
535     * @throws RiceIllegalArgumentException if {@code documentId} is null
536     */
537    @WebMethod(operationName = "getDocumentStatusTransitionHistory")
538    @XmlElementWrapper(name = "documentStatusTransitions", required = true)
539    @XmlElement(name = "documentStatusTransition", required = false)
540    @WebResult(name = "documentStatusTransitions")
541        List<DocumentStatusTransition> getDocumentStatusTransitionHistory(@WebParam(name = "documentId") String documentId)
542            throws RiceIllegalArgumentException;
543
544
545    /**
546     * Saves the passed in {@link DocumentLink}.  If the {@link DocumentLink}'s id field is created.  This method
547     * actually creates two different links in the database (one from the document being
548         * linked to the target and vice-versa).  If the links already exist, then the call is ignored.
549     *
550     * @param documentLink the unique id of a Document
551     *
552     * @return the newly saved {@link DocumentLink}
553     *
554     * @throws RiceIllegalArgumentException if {@code documentLink} is null
555     * @throws RiceIllegalArgumentException if {@code documentLink}'s is id value is populated
556     */
557    @WebMethod(operationName = "addDocumentLink")
558    @WebResult(name = "documentLink")
559        DocumentLink addDocumentLink(@WebParam(name = "documentLink") DocumentLink documentLink) throws RiceIllegalArgumentException;
560
561    /**
562     * Removes the  {@link DocumentLink} with the given documentLinkId.
563     *
564     * @param documentLinkId the unique id of a Document
565     *
566     * @return the deleted {@link DocumentLink}
567     *
568     * @throws RiceIllegalArgumentException if {@code documentLink} is null
569     * @throws RiceIllegalStateException if no DocumentLink with the passed in{@code documentLink} exist
570     */
571    @WebMethod(operationName = "deleteDocumentLink")
572    @WebResult(name = "documentLink")
573        DocumentLink deleteDocumentLink(@WebParam(name = "documentLinkId") String documentLinkId) throws RiceIllegalArgumentException;
574
575
576    /**
577     * Removes all {@link DocumentLink}s for the given {@link Document} with the given originatingDocumentId.
578     *
579     * @param originatingDocumentId the unique id of the originating Document of the document links to delete
580     *
581     * @return a list of the deleted {@link DocumentLink}s
582     *
583     * @throws RiceIllegalArgumentException if {@code documentLink} is null
584     */
585    @WebMethod(operationName = "deleteDocumentLinksByDocumentId")
586    @XmlElementWrapper(name = "documentLinks", required = true)
587    @XmlElement(name = "documentLink", required = false)
588    @WebResult(name = "documentLinks")
589    List<DocumentLink> deleteDocumentLinksByDocumentId(@WebParam(name = "originatingDocumentId") String originatingDocumentId) throws RiceIllegalArgumentException;
590
591    /**
592     * Gets a list of all {@link DocumentLink}s for outgoing links from the {@link Document} with the given documentId.
593     *
594     * @param originatingDocumentId the unique id of the originating Document of the document links to retrieve
595     *
596     * @return a list of the outgoing {@link DocumentLink}s for the originating document
597     *
598     * @throws RiceIllegalArgumentException if {@code originatingDocumentId} is null
599     */
600    @WebMethod(operationName = "getOutgoingDocumentLinks")
601    @XmlElementWrapper(name = "documentLinks", required = true)
602    @XmlElement(name = "documentLink", required = false)
603    @WebResult(name = "documentLinks")
604    List<DocumentLink> getOutgoingDocumentLinks(@WebParam(name = "originatingDocumentId") String originatingDocumentId) throws RiceIllegalArgumentException;
605
606    /**
607     * Gets a list of all {@link DocumentLink}s for incoming links from the {@link Document} with the given documentId.
608     *
609     * @param originatingDocumentId the unique id of the incoming Document of the document links to retrieve
610     *
611     * @return a list of the outgoing {@link DocumentLink}s for the incoming document
612     *
613     * @throws RiceIllegalArgumentException if {@code originatingDocumentId} is null
614     */
615    @WebMethod(operationName = "getIncomingDocumentLinks")
616    @XmlElementWrapper(name = "documentLinks", required = true)
617    @XmlElement(name = "documentLink", required = false)
618    @WebResult(name = "documentLinks")
619    List<DocumentLink> getIncomingDocumentLinks(@WebParam(name = "originatingDocumentId") String originatingDocumentId) throws RiceIllegalArgumentException;
620
621    /**
622     * Gets the {@link DocumentLink} for  with the given documentLinkId.
623     *
624     * @param documentLinkId the unique id of the {@link DocumentLink} to retrieve
625     *
626     * @return a {@link DocumentLink} with the passed in documentLinkId
627     *
628     * @throws RiceIllegalArgumentException if {@code documentLinkId} is null
629     */
630    @WebMethod(operationName = "getDocumentLink")
631    @WebResult(name = "documentLinks")
632    DocumentLink getDocumentLink(@WebParam(name = "documentLinkId") String documentLinkId) throws RiceIllegalArgumentException;
633    
634    /**
635     * Gets a list of active route node names for a {@link Document} with the given documentId.   Will never return null but an empty collection to indicate no results.
636     *
637     * @param documentId the unique id of a Document
638     *
639     * @return an unmodifiable list of active route node names for the {@link Document} with the given documentId
640     *
641     * @throws RiceIllegalArgumentException if {@code documentId} is null or blank
642     * 
643     * @since rice 2.2
644     */
645    @WebMethod(operationName = "getActiveRouteNodeNames")
646    @XmlElementWrapper(name = "nodes", required = true)
647    @XmlElement(name = "node", required = false)
648    @WebResult(name = "nodes")
649    List<String> getActiveRouteNodeNames(@WebParam(name = "documentId") String documentId) throws RiceIllegalArgumentException;
650    
651    /**
652     * Gets a list of terminal route node names for a {@link Document} with the given documentId.   Will never return null but an empty collection to indicate no results.
653     *
654     * @param documentId the unique id of a Document
655     *
656     * @return an unmodifiable list of terminal route node names for the {@link Document} with the given documentId
657     *
658     * @throws RiceIllegalArgumentException if {@code documentId} is null or blank
659     * 
660     * @since rice 2.2
661     */
662    @WebMethod(operationName = "getTerminalRouteNodeNames")
663    @XmlElementWrapper(name = "nodes", required = true)
664    @XmlElement(name = "node", required = false)
665    @WebResult(name = "nodes")
666    List<String> getTerminalRouteNodeNames(@WebParam(name = "documentId") String documentId) throws RiceIllegalArgumentException;
667
668    /**
669     * Gets a list of current route node names for a {@link Document} with the given documentId.  Will never return null but an empty collection to indicate no results.
670     *
671     * @param documentId the unique id of a Document
672     *
673     * @return an unmodifiable list of current route node names for the {@link Document} with the given documentId
674     *
675     * @throws RiceIllegalArgumentException if {@code documentId} is null or blank
676     * 
677     * @since rice 2.2
678     */
679    @WebMethod(operationName = "getCurrentRouteNodeNames")
680    @XmlElementWrapper(name = "nodes", required = true)
681    @XmlElement(name = "node", required = false)
682    @WebResult(name = "nodes")
683    List<String> getCurrentRouteNodeNames(@WebParam(name = "documentId") String documentId) throws RiceIllegalArgumentException;
684}