View Javadoc

1   /**
2    * Copyright 2005-2013 The Kuali Foundation
3    *
4    * Licensed under the Educational Community License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    *
8    * http://www.opensource.org/licenses/ecl2.php
9    *
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  package org.kuali.rice.kew.api.document;
17  
18  import org.joda.time.DateTime;
19  import org.kuali.rice.core.api.exception.RiceIllegalArgumentException;
20  import org.kuali.rice.core.api.exception.RiceIllegalStateException;
21  import org.kuali.rice.core.api.util.jaxb.DateTimeAdapter;
22  import org.kuali.rice.core.api.util.jaxb.MapStringStringAdapter;
23  import org.kuali.rice.kew.api.KewApiConstants;
24  import org.kuali.rice.kew.api.action.ActionRequest;
25  import org.kuali.rice.kew.api.action.ActionTaken;
26  import org.kuali.rice.kew.api.document.search.DocumentSearchCriteria;
27  import org.kuali.rice.kew.api.document.search.DocumentSearchResults;
28  import org.kuali.rice.kew.api.document.node.RouteNodeInstance;
29  
30  import javax.jws.WebMethod;
31  import javax.jws.WebParam;
32  import javax.jws.WebResult;
33  import javax.jws.WebService;
34  import javax.jws.soap.SOAPBinding;
35  import javax.xml.bind.annotation.XmlElement;
36  import javax.xml.bind.annotation.XmlElementWrapper;
37  import javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter;
38  import java.math.BigDecimal;
39  import java.util.List;
40  import java.util.Map;
41  
42  /**
43   * TODO ... annotate for JAX-WS! 
44   * 
45   * @author Kuali Rice Team (rice.collab@kuali.org)
46   */
47  @WebService(name = "workflowDocumentService", targetNamespace = KewApiConstants.Namespaces.KEW_NAMESPACE_2_0)
48  @SOAPBinding(style = SOAPBinding.Style.DOCUMENT, use = SOAPBinding.Use.LITERAL, parameterStyle = SOAPBinding.ParameterStyle.WRAPPED)
49  public interface WorkflowDocumentService {
50  
51      /**
52       * Gets a {@link Document} from a documentId.
53       *
54       * <p>
55       *   This method will return null if the Document does not exist.
56       * </p>
57       *
58       * @param documentId the unique id of the document to return
59       * @return the document with the passed in id value
60       * @throws RiceIllegalArgumentException if {@code documentId} is null
61       */
62      @WebMethod(operationName = "getDocument")
63      @WebResult(name = "document")
64  	Document getDocument(@WebParam(name = "documentId") String documentId) throws RiceIllegalArgumentException;
65  
66      /**
67       * Returns a boolean depending on if a {@link Document} exists with the specified documentId
68       *
69       * <p>
70       *   This method will return false if the responsibility does not exist.
71       * </p>
72       *
73       * @param documentId the unique id of the document to check for existence
74       * @return boolean value representative of whether the document exists
75       * @throws RiceIllegalArgumentException if {@code documentId} is null
76       */
77      @WebMethod(operationName = "doesDocumentExist")
78      @WebResult(name = "document")
79  	boolean doesDocumentExist(@WebParam(name = "documentId") String documentId)
80              throws RiceIllegalArgumentException;
81  
82      /**
83       * Gets {@link DocumentContent} from a documentId.
84       *
85       * <p>
86       *   This method will return null if the document does not exist.
87       * </p>
88       *
89       * @param documentId the unique id of the document content to return
90       * @return the documentContent with the passed in id value
91       * @throws RiceIllegalArgumentException if {@code documentId} is null
92       */
93      @WebMethod(operationName = "getDocumentContent")
94      @WebResult(name = "documentContent")
95  	DocumentContent getDocumentContent(@WebParam(name = "documentId") String documentId)
96              throws RiceIllegalArgumentException;
97  
98      /**
99       * Returns the name of the document type used by the document with the given id.
100      *
101      * @param documentId the id of the document for which to fetch the document type name, must not be null or blank
102      * @return the name of the document type for the document with the given id, will never return a null or blank value
103      * @throws RiceIllegalArgumentException if {@code documentId} is null or if the document id does not resolve to a
104      *         valid document from which a document type name can be fetched
105      *
106      * @since 2.4
107      */
108     @WebMethod(operationName = "getDocumentTypeName")
109     @WebResult(name = "documentTypeName")
110     String getDocumentTypeName(@WebParam(name = "documentId") String documentId) throws RiceIllegalArgumentException;
111 
112     /**
113      * Gets a list of root ActionRequests for a given documentId
114      *
115      * @param documentId the unique id of a document
116      *
117      * @return the list of root ActionRequests for a given documentId
118      *
119      * @throws RiceIllegalArgumentException if {@code documentId} is null
120      */
121     @WebMethod(operationName = "getRootActionRequests")
122     @XmlElementWrapper(name = "rootActionRequests", required = true)
123     @XmlElement(name = "rootActionRequest", required = false)
124     @WebResult(name = "rootActionRequests")
125 	List<ActionRequest> getRootActionRequests(@WebParam(name = "documentId") String documentId)
126             throws RiceIllegalArgumentException;
127     
128     /**
129      * Gets a list of ActionRequests which are pending for a given documentId
130      * 
131      * @since 2.1
132      * @param documentId the unique id of a document
133      * @return the list of pending ActionRequests for a given documentId
134      * @throws RiceIllegalArgumentException if {@code documentId} is null
135      */
136     @WebMethod(operationName = "getPendingActionRequests")
137     @XmlElementWrapper(name = "pendingActionRequests", required = true)
138     @XmlElement(name = "pendingActionRequest", required = false)
139     @WebResult(name = "pendingActionRequests")
140     List<ActionRequest> getPendingActionRequests(String documentId);
141 
142     /**
143      * Gets a list of ActionRequests for a given documentId, nodeName and principalId
144      *
145      * @param documentId the unique id of a document
146      * @param nodeName the name of a RouteNode
147      * @param principalId the unique id of a principal
148      *
149      * @return the list of ActionRequests for a given documentId, nodeName, and principalId
150      *
151      * @throws RiceIllegalArgumentException if {@code documentId} is null
152      */
153     @WebMethod(operationName = "getActionRequestsForPrincipalAtNode")
154     @XmlElementWrapper(name = "actionRequests", required = true)
155     @XmlElement(name = "actionRequests", required = false)
156     @WebResult(name = "actionRequests")
157 	List<ActionRequest> getActionRequestsForPrincipalAtNode(@WebParam(name = "documentId") String documentId,
158             @WebParam(name = "nodeName") String nodeName, @WebParam(name = "principalId") String principalId)
159             throws RiceIllegalArgumentException;
160 
161     /**
162      * Gets a list of past {@link ActionTaken} of a {@link Document} with the given documentId
163      *
164      * @param documentId the unique id of a document
165      *
166      * @return the list of past ActionTakens for a given documentId
167      *
168      * @throws RiceIllegalArgumentException if {@code documentId} is null
169      */
170     @WebMethod(operationName = "getActionsTaken")
171     @XmlElementWrapper(name = "actionsTaken", required = true)
172     @XmlElement(name = "actionTaken", required = false)
173     @WebResult(name = "actionsTaken")
174 	List<ActionTaken> getActionsTaken(@WebParam(name = "documentId") String documentId)
175             throws RiceIllegalArgumentException;
176 
177     /**
178      * @deprecated mistaken operation name...use getActionsTaken instead
179      *
180      * @param documentId the unique id of a document
181      *
182      * @return the list of past ActionTakens for a given documentId
183      *
184      * @throws RiceIllegalArgumentException if {@code documentId} is null
185      */
186     @WebMethod(operationName = "getActionRequests")
187     @XmlElementWrapper(name = "actionsTaken", required = true)
188     @XmlElement(name = "actionTaken", required = false)
189     @WebResult(name = "actionsTaken")
190     @Deprecated
191     List<ActionTaken> _getActionsTaken(@WebParam(name = "documentId") String documentId)
192             throws RiceIllegalArgumentException;
193 
194 
195     /**
196     * Gets a list of all {@link ActionTaken} of a {@link Document} with the given documentId
197     *
198     * @since 2.0.2
199     *
200     * @param documentId the unique id of a document
201     *
202     * @return the list of ActionTakens (both current and not) for a given documentId
203     *
204     * @throws RiceIllegalArgumentException if {@code documentId} is null
205     */
206       @WebMethod(operationName = "getAllActionRequests")
207       @XmlElementWrapper(name = "actionsTaken", required = true)
208       @XmlElement(name = "actionTaken", required = false)
209       @WebResult(name = "actionsTaken")
210       List<ActionTaken> getAllActionsTaken(@WebParam(name = "documentId") String documentId)
211               throws RiceIllegalArgumentException;
212 
213 
214     /**
215      * Gets a {@link DocumentDetail} of a {@link Document} with the given documentTypeName and appId
216      *
217      * @param documentTypeName the name of the DocumentType
218      * @param appId the unique id of the application
219      *
220      * @return a {@link DocumentDetail} for with the given documentTypeName and appId
221      *
222      * @throws RiceIllegalArgumentException if {@code documentTypeName} is null
223      * @throws RiceIllegalArgumentException if {@code appId} is null
224      */
225     @WebMethod(operationName = "getDocumentDetailByAppId")
226     @WebResult(name = "documentDetail")
227     DocumentDetail getDocumentDetailByAppId(@WebParam(name = "documentTypeName") String documentTypeName,
228                                             @WebParam(name = "appId") String appId)
229             throws RiceIllegalArgumentException;
230 
231     /**
232      * Gets a {@link DocumentDetail} of a {@link Document} with the given documentId
233      *
234      * @param documentId the unique id of the Document
235      *
236      * @return a {@link DocumentDetail} for with the given documentId
237      *
238      * @throws RiceIllegalArgumentException if {@code documentId} is null
239      */
240     @WebMethod(operationName = "getDocumentDetail")
241     @WebResult(name = "documentDetail")
242 	DocumentDetail getDocumentDetail(@WebParam(name = "documentId") String documentId);
243 
244 
245     /**
246      * Gets a {@link RouteNodeInstance} with the given nodeInstanceId
247      *
248      * @param routeNodeInstanceId the unique id of the {@link RouteNodeInstance}
249      *
250      * @return a {@link DocumentDetail} for with the given documentId
251      *
252      * @throws RiceIllegalArgumentException if {@code nodeInstanceId} is null
253      */
254     @WebMethod(operationName = "getRouteNodeInstance")
255     @WebResult(name = "routeNodeInstance")
256 	RouteNodeInstance getRouteNodeInstance(@WebParam(name = "routeNodeInstanceId") String routeNodeInstanceId)
257             throws RiceIllegalArgumentException;
258 
259     /**
260      * Gets a value application document id of a {@link Document} with the given documentId
261      *
262      * @param documentId the unique id of the Document
263      *
264      * @return the value of the applicationDocumentId for the {@link Document} with the given documentId
265      *
266      * @throws RiceIllegalArgumentException if {@code documentId} is null
267      */
268     @WebMethod(operationName = "getApplicationDocumentId")
269     @WebResult(name = "applicationDocumentId")
270 	String getApplicationDocumentId(@WebParam(name = "documentId") String documentId)
271             throws RiceIllegalArgumentException;
272 
273     /**
274      * Gets a value application document status of a {@link org.kuali.rice.kew.api.document.Document} with the given documentId
275      *
276      * @param documentId the unique id of the Document
277      *
278      * @return the value of the applicationDocumentStatus for the {@link org.kuali.rice.kew.api.document.Document} with the given documentId
279      *
280      * @throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException if {@code documentId} is null
281      */
282     @WebMethod(operationName = "getApplicationDocumentStatus")
283     @WebResult(name = "applicationDocumentStatus")
284     String getApplicationDocumentStatus(@WebParam(name = "documentId") String documentId)
285             throws RiceIllegalArgumentException;
286 
287     /**
288      * Executes a search for workflow documents using the given criteria and as the principal with the given id.  Since
289      * documents can define security which permits access to view certain search results, the given principal id will
290      * be used when evaluating which documents should be filtered from the results because of lack of access.
291      *
292      * @param principalId the id of the principal to execute the search as, if this value is non-null then security
293      * filtering will be executed against the results, if it is null then no filtering will be performed
294      * @param criteria the criteria to use when executing the search
295      *
296      * @return the results of the search, this will never be null but may contain an empty list of results
297      *
298      * @throws RiceIllegalArgumentException if the given criteria is null
299      */
300     @WebMethod(operationName = "documentSearch")
301     @WebResult(name = "documentSearchResults")
302     DocumentSearchResults documentSearch(
303             @WebParam(name = "principalId") String principalId,
304             @WebParam(name = "criteria") DocumentSearchCriteria criteria)
305         throws RiceIllegalArgumentException;
306 
307     /**
308      * Gets a list of all {@link RouteNodeInstance} for a {@link Document} with the given documentId
309      *
310      * @param documentId the unique id of a Document
311      *
312      * @return the list of {@link RouteNodeInstance}s for the {@link Document} with the given documentId
313      *
314      * @throws RiceIllegalArgumentException if {@code documentId} is null
315      */
316     @WebMethod(operationName = "getRouteNodeInstances")
317     @XmlElementWrapper(name = "routeNodeInstances", required = true)
318     @XmlElement(name = "routeNodeInstance", required = false)
319     @WebResult(name = "routeNodeInstances")
320 	List<RouteNodeInstance> getRouteNodeInstances(@WebParam(name = "documentId") String documentId)
321             throws RiceIllegalArgumentException;
322 
323     /**
324      * Gets a list of active {@link RouteNodeInstance} for a {@link Document} with the given documentId
325      *
326      * @param documentId the unique id of a Document
327      *
328      * @return the list of active {@link RouteNodeInstance}s for the {@link Document} with the given documentId
329      *
330      * @throws RiceIllegalArgumentException if {@code documentId} is null
331      */
332     @WebMethod(operationName = "getActiveRouteNodeInstances")
333     @XmlElementWrapper(name = "routeNodeInstances", required = true)
334     @XmlElement(name = "routeNodeInstance", required = false)
335     @WebResult(name = "routeNodeInstances")
336 	List<RouteNodeInstance> getActiveRouteNodeInstances(@WebParam(name = "documentId") String documentId)
337             throws RiceIllegalArgumentException;
338 
339     /**
340      * Gets a list of terminal {@link RouteNodeInstance}s for a {@link Document} with the given documentId
341      *
342      * @param documentId the unique id of a Document
343      *
344      * @return the list of terminal {@link RouteNodeInstance}s for the {@link Document} with the given documentId
345      *
346      * @throws RiceIllegalArgumentException if {@code documentId} is null
347      */
348     @WebMethod(operationName = "getTerminalRouteNodeInstances")
349     @XmlElementWrapper(name = "routeNodeInstances", required = true)
350     @XmlElement(name = "routeNodeInstance", required = false)
351     @WebResult(name = "routeNodeInstances")
352 	List<RouteNodeInstance> getTerminalRouteNodeInstances(@WebParam(name = "documentId") String documentId)
353             throws RiceIllegalArgumentException;
354 
355     /**
356      * Gets a list of current {@link RouteNodeInstance}s for a {@link Document} with the given documentId
357      *
358      * @param documentId the unique id of a Document
359      *
360      * @return the list of current {@link RouteNodeInstance}s for the {@link Document} with the given documentId
361      *
362      * @throws RiceIllegalArgumentException if {@code documentId} is null
363      */
364     @WebMethod(operationName = "getCurrentRouteNodeInstances")
365     @XmlElementWrapper(name = "routeNodeInstances", required = true)
366     @XmlElement(name = "routeNodeInstance", required = false)
367     @WebResult(name = "routeNodeInstances")
368 	List<RouteNodeInstance> getCurrentRouteNodeInstances(@WebParam(name = "documentId") String documentId)
369             throws RiceIllegalArgumentException;
370 
371     /**
372      * Gets a list of all previous {@link RouteNodeInstance}'s node names for a {@link Document} with the given documentId
373      *
374      * @param documentId the unique id of a Document
375      *
376      * @return the list of all previous {@link RouteNodeInstance}'s node names for the {@link Document} with the
377      * given documentId
378      *
379      * @throws RiceIllegalArgumentException if {@code documentId} is null
380      */
381     @WebMethod(operationName = "getPreviousRouteNodeNames")
382     @XmlElementWrapper(name = "previousRouteNodeNames", required = true)
383     @XmlElement(name = "previousRouteNodeName", required = false)
384     @WebResult(name = "previousRouteNodeNames")
385 	List<String> getPreviousRouteNodeNames(@WebParam(name = "documentId") String documentId)
386             throws RiceIllegalArgumentException;
387 
388 	/**
389      * Gets the status value for a {@link Document} with the given documentId
390      *
391      * @param documentId the unique id of a Document
392      *
393      * @return the current status of the {@link Document} with the
394      * given documentId
395      *
396      * @throws RiceIllegalArgumentException if {@code documentId} is null
397      */
398     @WebMethod(operationName = "getDocumentStatus")
399     @WebResult(name = "documentStatus")
400 	DocumentStatus getDocumentStatus(@WebParam(name = "documentId") String documentId)
401             throws RiceIllegalArgumentException;
402 
403 
404     /**
405      * Gets a list of principalId values for a {@link Document} with the given documentId
406      * and action request code that have pending action requests
407      *
408      * @param actionRequestedCd code for the pending action requested
409      * @param documentId the unique id of a Document
410      *
411      * @return a list of principalIds for the {@link Document} with the
412      * given parameters and have a pending action request
413      *
414      * @throws RiceIllegalArgumentException if {@code documentId} is null
415      * @throws RiceIllegalArgumentException if {@code actionRequestCd} is null
416      */
417     @WebMethod(operationName = "getPrincipalIdsWithPendingActionRequestByActionRequestedAndDocId")
418     @XmlElementWrapper(name = "principalIds", required = true)
419     @XmlElement(name = "principalId", required = false)
420     @WebResult(name = "principalIds")
421 	List<String> getPrincipalIdsWithPendingActionRequestByActionRequestedAndDocId(
422                     @WebParam(name = "actionRequestedCd") String actionRequestedCd,
423 		            @WebParam(name = "documentId") String documentId)
424             throws RiceIllegalArgumentException;
425 
426 
427     /**
428      * Gets the {@link Document} initiator's principalId with the given documentId
429      *
430      * @param documentId the unique id of a Document
431      *
432      * @return the {@link Document} initiator's principalId
433      *
434      * @throws RiceIllegalArgumentException if {@code documentId} is null
435      */
436     @WebMethod(operationName = "getDocumentInitiatorPrincipalId")
437     @WebResult(name = "principalId")
438 	String getDocumentInitiatorPrincipalId(@WebParam(name = "documentId") String documentId)
439             throws RiceIllegalArgumentException;
440 
441     /**
442      * Gets the {@link Document}'s 'routed by' principalId with the given documentId
443      * Returns null if the document is not found
444      *
445      * @param documentId the unique id of a Document
446      *
447      * @return the {@link Document}'s 'routed by' principalId
448      *
449      * @throws RiceIllegalArgumentException if {@code documentId} is null
450      */
451     @WebMethod(operationName = "getRoutedByPrincipalIdByDocumentId")
452     @WebResult(name = "principalId")
453 	String getRoutedByPrincipalIdByDocumentId(@WebParam(name = "documentId") String documentId)
454             throws RiceIllegalArgumentException;
455 
456     /**
457      * Does a direct search for searchableAttributes without going through the document search
458      * This returns a list of String values for String searchableAttributes
459      *
460      * @param documentId the unique id of a Document
461      * @param key the searchableAttributes key value
462      *
463      * @return a list of String values for the {@link Document} with the
464      * given documentId and searchable attribute key
465      *
466      * @throws RiceIllegalArgumentException if {@code documentId} is null
467      * @throws RiceIllegalArgumentException if {@code key} is null
468      */
469     @WebMethod(operationName = "getSearchableAttributeStringValuesByKey")
470     @XmlElementWrapper(name = "searchableAttributeStringValues", required = true)
471     @XmlElement(name = "searchableAttributeStringValue", required = false)
472     @WebResult(name = "searchableAttributeStringValues")
473 	List<String> getSearchableAttributeStringValuesByKey(@WebParam(name = "documentId") String documentId,
474 			                                             @WebParam(name = "key") String key)
475             throws RiceIllegalArgumentException;
476 
477 	/**
478      * Does a direct search for searchableAttributes without going through the document search
479      * This returns a list of DateTime values for date/time searchableAttributes
480      *
481      * @param documentId the unique id of a Document
482      * @param key the searchableAttributes key value
483      *
484      * @return a list of DateTime values for the {@link Document} with the
485      * given documentId and searchable attribute key
486      *
487      * @throws RiceIllegalArgumentException if {@code documentId} is null
488      * @throws RiceIllegalArgumentException if {@code key} is null
489      */
490     @WebMethod(operationName = "getSearchableAttributeDateTimeValuesByKey")
491     @XmlElementWrapper(name = "searchableAttributeDateTimeValues", required = true)
492     @XmlElement(name = "searchableAttributeDateTimeValue", required = false)
493     @WebResult(name = "searchableAttributeDateTimeValues")
494 	@XmlJavaTypeAdapter(value = DateTimeAdapter.class)
495 	List<DateTime> getSearchableAttributeDateTimeValuesByKey(@WebParam(name = "documentId") String documentId,
496 			                                                 @WebParam(name = "key") String key)
497             throws RiceIllegalArgumentException;
498 
499 	/**
500      * Does a direct search for searchableAttributes without going through the document search
501      * This returns a list of BigDecimal values for decimal searchableAttributes
502      *
503      * @param documentId the unique id of a Document
504      * @param key the searchableAttributes key value
505      *
506      * @return a list of BigDecimal values for the {@link Document} with the
507      * given documentId and searchable attribute key
508      *
509      * @throws RiceIllegalArgumentException if {@code documentId} is null
510      * @throws RiceIllegalArgumentException if {@code key} is null
511      */
512     @WebMethod(operationName = "getSearchableAttributeFloatValuesByKey")
513     @XmlElementWrapper(name = "searchableAttributeBigDecimalValues", required = true)
514     @XmlElement(name = "searchableAttributeBigDecimalValue", required = false)
515     @WebResult(name = "searchableAttributeBigDecimalValues")
516 	List<BigDecimal> getSearchableAttributeFloatValuesByKey(@WebParam(name = "documentId") String documentId,
517 			                                                @WebParam(name = "key") String key)
518             throws RiceIllegalArgumentException;
519 
520 	/**
521      * Does a direct search for searchableAttributes without going through the document search
522      * This returns a list of Long values for long searchableAttributes
523      *
524      * @param documentId the unique id of a Document
525      * @param key the searchableAttributes key value
526      *
527      * @return a list of BigDecimal values for the {@link Document} with the
528      * given documentId and searchable attribute key
529      *
530      * @throws RiceIllegalArgumentException if {@code documentId} is null
531      * @throws RiceIllegalArgumentException if {@code key} is null
532      */
533     @WebMethod(operationName = "getSearchableAttributeLongValuesByKey")
534     @XmlElementWrapper(name = "searchableAttributeLongValues", required = true)
535     @XmlElement(name = "searchableAttributeLongValue", required = false)
536     @WebResult(name = "searchableAttributeLongValues")
537 	List<Long> getSearchableAttributeLongValuesByKey(@WebParam(name = "documentId") String documentId,
538 			                                         @WebParam(name = "key") String key)
539             throws RiceIllegalArgumentException;
540 
541     /**
542      * Gets a list of DocumentStatusTransitions for the {@link Document} with the given documentId
543      *
544      * @param documentId the unique id of a Document
545      *
546      * @return a list of DocumentStatusTransitions for the {@link Document} with the
547      * given documentId
548      *
549      * @throws RiceIllegalArgumentException if {@code documentId} is null
550      */
551     @WebMethod(operationName = "getDocumentStatusTransitionHistory")
552     @XmlElementWrapper(name = "documentStatusTransitions", required = true)
553     @XmlElement(name = "documentStatusTransition", required = false)
554     @WebResult(name = "documentStatusTransitions")
555 	List<DocumentStatusTransition> getDocumentStatusTransitionHistory(@WebParam(name = "documentId") String documentId)
556             throws RiceIllegalArgumentException;
557 
558 
559     /**
560      * Saves the passed in {@link DocumentLink}.  If the {@link DocumentLink}'s id field is created.  This method
561      * actually creates two different links in the database (one from the document being
562 	 * linked to the target and vice-versa).  If the links already exist, then the call is ignored.
563      *
564      * @param documentLink the unique id of a Document
565      *
566      * @return the newly saved {@link DocumentLink}
567      *
568      * @throws RiceIllegalArgumentException if {@code documentLink} is null
569      * @throws RiceIllegalArgumentException if {@code documentLink}'s is id value is populated
570      */
571     @WebMethod(operationName = "addDocumentLink")
572     @WebResult(name = "documentLink")
573 	DocumentLink addDocumentLink(@WebParam(name = "documentLink") DocumentLink documentLink) throws RiceIllegalArgumentException;
574 
575     /**
576      * Removes the  {@link DocumentLink} with the given documentLinkId.
577      *
578      * @param documentLinkId the unique id of a Document
579      *
580      * @return the deleted {@link DocumentLink}
581      *
582      * @throws RiceIllegalArgumentException if {@code documentLink} is null
583      * @throws RiceIllegalStateException if no DocumentLink with the passed in{@code documentLink} exist
584      */
585     @WebMethod(operationName = "deleteDocumentLink")
586     @WebResult(name = "documentLink")
587 	DocumentLink deleteDocumentLink(@WebParam(name = "documentLinkId") String documentLinkId) throws RiceIllegalArgumentException;
588 
589 
590     /**
591      * Removes all {@link DocumentLink}s for the given {@link Document} with the given originatingDocumentId.
592      *
593      * @param originatingDocumentId the unique id of the originating Document of the document links to delete
594      *
595      * @return a list of the deleted {@link DocumentLink}s
596      *
597      * @throws RiceIllegalArgumentException if {@code documentLink} is null
598      */
599     @WebMethod(operationName = "deleteDocumentLinksByDocumentId")
600     @XmlElementWrapper(name = "documentLinks", required = true)
601     @XmlElement(name = "documentLink", required = false)
602     @WebResult(name = "documentLinks")
603     List<DocumentLink> deleteDocumentLinksByDocumentId(@WebParam(name = "originatingDocumentId") String originatingDocumentId) throws RiceIllegalArgumentException;
604 
605     /**
606      * Gets a list of all {@link DocumentLink}s for outgoing links from the {@link Document} with the given documentId.
607      *
608      * @param originatingDocumentId the unique id of the originating Document of the document links to retrieve
609      *
610      * @return a list of the outgoing {@link DocumentLink}s for the originating document
611      *
612      * @throws RiceIllegalArgumentException if {@code originatingDocumentId} is null
613      */
614     @WebMethod(operationName = "getOutgoingDocumentLinks")
615     @XmlElementWrapper(name = "documentLinks", required = true)
616     @XmlElement(name = "documentLink", required = false)
617     @WebResult(name = "documentLinks")
618     List<DocumentLink> getOutgoingDocumentLinks(@WebParam(name = "originatingDocumentId") String originatingDocumentId) throws RiceIllegalArgumentException;
619 
620     /**
621      * Gets a list of all {@link DocumentLink}s for incoming links from the {@link Document} with the given documentId.
622      *
623      * @param originatingDocumentId the unique id of the incoming Document of the document links to retrieve
624      *
625      * @return a list of the outgoing {@link DocumentLink}s for the incoming document
626      *
627      * @throws RiceIllegalArgumentException if {@code originatingDocumentId} is null
628      */
629     @WebMethod(operationName = "getIncomingDocumentLinks")
630     @XmlElementWrapper(name = "documentLinks", required = true)
631     @XmlElement(name = "documentLink", required = false)
632     @WebResult(name = "documentLinks")
633     List<DocumentLink> getIncomingDocumentLinks(@WebParam(name = "originatingDocumentId") String originatingDocumentId) throws RiceIllegalArgumentException;
634 
635     /**
636      * Gets the {@link DocumentLink} for  with the given documentLinkId.
637      *
638      * @param documentLinkId the unique id of the {@link DocumentLink} to retrieve
639      *
640      * @return a {@link DocumentLink} with the passed in documentLinkId
641      *
642      * @throws RiceIllegalArgumentException if {@code documentLinkId} is null
643      */
644     @WebMethod(operationName = "getDocumentLink")
645     @WebResult(name = "documentLinks")
646     DocumentLink getDocumentLink(@WebParam(name = "documentLinkId") String documentLinkId) throws RiceIllegalArgumentException;
647     
648     /**
649      * 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.
650      *
651      * @param documentId the unique id of a Document
652      *
653      * @return an unmodifiable list of active route node names for the {@link Document} with the given documentId
654      *
655      * @throws RiceIllegalArgumentException if {@code documentId} is null or blank
656      * 
657      * @since rice 2.2
658      */
659     @WebMethod(operationName = "getActiveRouteNodeNames")
660     @XmlElementWrapper(name = "nodes", required = true)
661     @XmlElement(name = "node", required = false)
662     @WebResult(name = "nodes")
663     List<String> getActiveRouteNodeNames(@WebParam(name = "documentId") String documentId) throws RiceIllegalArgumentException;
664     
665     /**
666      * 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.
667      *
668      * @param documentId the unique id of a Document
669      *
670      * @return an unmodifiable list of terminal route node names for the {@link Document} with the given documentId
671      *
672      * @throws RiceIllegalArgumentException if {@code documentId} is null or blank
673      * 
674      * @since rice 2.2
675      */
676     @WebMethod(operationName = "getTerminalRouteNodeNames")
677     @XmlElementWrapper(name = "nodes", required = true)
678     @XmlElement(name = "node", required = false)
679     @WebResult(name = "nodes")
680     List<String> getTerminalRouteNodeNames(@WebParam(name = "documentId") String documentId) throws RiceIllegalArgumentException;
681 
682     /**
683      * 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.
684      *
685      * @param documentId the unique id of a Document
686      *
687      * @return an unmodifiable list of current route node names for the {@link Document} with the given documentId
688      *
689      * @throws RiceIllegalArgumentException if {@code documentId} is null or blank
690      * 
691      * @since rice 2.2
692      */
693     @WebMethod(operationName = "getCurrentRouteNodeNames")
694     @XmlElementWrapper(name = "nodes", required = true)
695     @XmlElement(name = "node", required = false)
696     @WebResult(name = "nodes")
697     List<String> getCurrentRouteNodeNames(@WebParam(name = "documentId") String documentId) throws RiceIllegalArgumentException;
698 }