View Javadoc
1   /**
2    * Copyright 2005-2016 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.krms.api.repository.term;
17  
18  import org.kuali.rice.core.api.exception.RiceIllegalArgumentException;
19  import org.kuali.rice.krms.api.KrmsConstants;
20  import org.springframework.cache.annotation.Cacheable;
21  
22  import javax.jws.WebMethod;
23  import javax.jws.WebParam;
24  import javax.jws.WebResult;
25  import javax.jws.WebService;
26  import javax.jws.soap.SOAPBinding;
27  import javax.xml.bind.annotation.XmlElement;
28  import javax.xml.bind.annotation.XmlElementWrapper;
29  import java.util.List;
30  import org.springframework.cache.annotation.CacheEvict;
31  
32  /**
33   * The TermRepositoryService provides the basic access to terms and term resolvers in the repository needed
34   * for executing rules.
35   *
36   * @author Kuali Rice Team (rice.collab@kuali.org)
37   *
38   */
39  @WebService(name = "termRepositoryService", targetNamespace = KrmsConstants.Namespaces.KRMS_NAMESPACE_2_0)
40  @SOAPBinding(style = SOAPBinding.Style.DOCUMENT, use = SOAPBinding.Use.LITERAL, parameterStyle = SOAPBinding.ParameterStyle.WRAPPED)
41  public interface TermRepositoryService {
42  
43  
44      /**
45       * Retrieves all {@link TermResolverDefinition}s for the given namespace.
46       *
47       * @since 2.1.1
48       * @param namespace the namespace for which to get all term resolvers.
49       * @return the List of {@link TermResolverDefinition}s for the given namespace. May be empty, but never null.
50       *
51       * @throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException if the namespace is null or blank.
52       */
53      @WebMethod(operationName = "findTermResolversByNamespace")
54      @XmlElementWrapper(name = "termResolvers", required = true)
55      @XmlElement(name = "termResolver", required = false)
56      @WebResult(name = "termResolvers")
57      @Cacheable(value = TermResolverDefinition.Cache.NAME, key = "'namespace=' + #p0")
58      List<TermResolverDefinition> findTermResolversByNamespace(@WebParam(name = "namespace") String namespace) throws RiceIllegalArgumentException;
59  
60      /**
61       * Retrieves the {@link TermDefinition} with the given termId.
62       *
63       * @since 2.1.1
64       * @param termId the identifier of the term to retrieve.
65       * @return the {@link TermDefinition} with the given termId.  May be null if there is no term with the given termId
66       * in the repository.
67       *
68       * @throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException if the termId is null or blank.
69       */
70      @WebMethod(operationName = "getTerm")
71      @WebResult(name = "term")
72      @Cacheable(value= TermDefinition.Cache.NAME, key="'id=' + #p0")
73      TermDefinition getTerm(@WebParam(name = "termId") String termId) throws RiceIllegalArgumentException;;
74  
75      /**
76       * Retrieves the {@link TermSpecificationDefinition} with the given TermSpecificationId.
77       *
78       * @since 2.2.1
79       * @param id the identifier of the term specification to retrieve.
80       * @return the {@link TermSpecificationDefinition} with the given id.  May be null if there is no term specification 
81       * with the given id in the repository.
82       *
83       * @throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException if the id is null or blank.
84       */
85      @WebMethod(operationName = "getTermSpecificationById")
86      @WebResult(name = "termSpecification")
87      @Cacheable(value = TermSpecificationDefinition.Cache.NAME, key = "'id=' + #p0")
88      TermSpecificationDefinition getTermSpecificationById(@WebParam(name = "id") String id)
89              throws RiceIllegalArgumentException;
90  
91      /**
92       * Creates a {@link TermSpecificationDefinition}
93       *
94       * @since 2.2.1
95       * @param termSpec the term specification to be created
96       * @return the {@link TermSpecificationDefinition} after it has been created
97       * in the repository.
98       *
99       * @throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException
100      * termSpec is null or invalid
101      */
102     @WebMethod(operationName = "createTermSpecification")
103     @WebResult(name = "termSpecification")
104     @CacheEvict(value = {TermSpecificationDefinition.Cache.NAME, TermDefinition.Cache.NAME}, allEntries = true)
105     TermSpecificationDefinition createTermSpecification(@WebParam(name = "termSpec") TermSpecificationDefinition termSpec)
106             throws RiceIllegalArgumentException;
107 
108     /**
109      * Updates a {@link TermSpecificationDefinition}
110      *
111      * @since 2.2.1
112      * @param termSpec the term specification to be updated
113      *
114      * @throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException
115      * termSpec is null or invalid
116      */
117     @WebMethod(operationName = "updateTermSpecification")
118     @CacheEvict(value = {TermSpecificationDefinition.Cache.NAME, TermDefinition.Cache.NAME}, allEntries = true)
119     void updateTermSpecification(@WebParam(name = "termSpec") TermSpecificationDefinition termSpec)
120             throws RiceIllegalArgumentException;
121 
122     /**
123      * Deletes a {@link TermSpecificationDefinition}
124      *
125      * @since 2.2.1
126      * @param id the id of the term specification to be deleted
127      *
128      * @throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException
129      * id is null or invalid
130      */
131     @WebMethod(operationName = "deleteTermSpecification")
132     @CacheEvict(value = {TermSpecificationDefinition.Cache.NAME, TermDefinition.Cache.NAME}, allEntries = true)
133     void deleteTermSpecification(@WebParam(name = "id") String id)
134             throws RiceIllegalArgumentException;
135 
136 
137     /**
138      * Create a {@link TermDefinition}
139      *
140      * @since 2.2.1
141      * @param termDef to be created
142      * @return the {@link TermDefinition} term definition after it has been
143      * created in the repository.
144      *
145      * @throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException if
146      * the termDef is null or blank.
147      */
148     @WebMethod(operationName = "createTerm")
149     @WebResult(name = "term")
150     @CacheEvict(value = {TermDefinition.Cache.NAME}, allEntries = true)
151     TermDefinition createTerm(@WebParam(name = "termDef") TermDefinition termDef)
152             throws RiceIllegalArgumentException;
153 
154     /**
155      * Update a {@link TermDefinition}
156      *
157      * @since 2.2.1
158      * @param termDef to be updated
159      *
160      * @throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException if
161      * the termDef is null or blank.
162      */
163     @WebMethod(operationName = "updateTerm")
164     @WebResult(name = "term")
165     @CacheEvict(value = {TermDefinition.Cache.NAME}, allEntries = true)
166     void updateTerm(@WebParam(name = "termDef") TermDefinition termDef)
167             throws RiceIllegalArgumentException;
168 
169 
170     /**
171      * Delete a {@link TermDefinition}
172      *
173      * @since 2.2.1
174      * @param id of the termDefinition to be deleted
175      *
176      * @throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException if
177      * the id is null or blank.
178      */
179     @WebMethod(operationName = "deleteTerm")
180     @WebResult(name = "term")
181     @CacheEvict(value = {TermDefinition.Cache.NAME}, allEntries = true)
182     void deleteTerm(@WebParam(name = "id") String id)
183             throws RiceIllegalArgumentException;
184 
185 
186     /**
187      * Retrieves the {@link TermResolverDefinition} with the given id.
188      *
189      * @since 2.2.1
190      * @param id the identifier of the term to retrieve.
191      * @return the {@link TermResolverDefinition} with the given id. May be null
192      * if there is no term with the given id in the repository.
193      *
194      * @throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException if
195      * the id is null or blank.
196      */
197     @WebMethod(operationName = "getTermResolverById")
198     @WebResult(name = "termResolver")
199     @Cacheable(value = TermResolverDefinition.Cache.NAME, key = "'id=' + #p0")
200     TermResolverDefinition getTermResolverById(@WebParam(name = "id") String id)
201             throws RiceIllegalArgumentException;
202 
203     /**
204      * Get the {@link TermResolverDefinition}s for any term resolvers in the
205      * specified namespace that have the given term specification as their
206      * output.
207      *
208      * @param id the id for the term specification
209      * @param namespace the namespace to search
210      * @return the List of term resolvers found. If none are found, an empty
211      * list will be returned.
212      */
213     @WebMethod(operationName = "findTermResolversByOutputId")
214     @XmlElementWrapper(name = "termResolvers", required = true)
215     @XmlElement(name = "termResolver", required = false)
216     @WebResult(name = "termResolvers")
217     @Cacheable(value = TermResolverDefinition.Cache.NAME, key = "'id=' + #p0 + '|' + 'namespace=' + #p1")
218     List<TermResolverDefinition> findTermResolversByOutputId(@WebParam(name = "id") String id,
219             @WebParam(name = "namespace") String namespace)
220             throws RiceIllegalArgumentException;
221 
222     /**
223      * Creates the {@link TermResolverDefinition}.
224      *
225      * @since 2.1.1
226      * @param termResolver to be created
227      * @return the {@link TermResolver} after it has been created in the
228      * repository.
229      *
230      * @throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException if
231      * the termResolver is null or blank.
232      */
233     @WebMethod(operationName = "createTermResolver")
234     @WebResult(name = "termResolver")
235     @CacheEvict(value = {TermResolverDefinition.Cache.NAME, TermDefinition.Cache.NAME}, allEntries = true)
236     TermResolverDefinition createTermResolver(@WebParam(name = "termResolver") TermResolverDefinition termResolver)
237             throws RiceIllegalArgumentException;
238 
239 
240     /**
241      * Updates the {@link TermResolverDefinition}.
242      *
243      * @since 2.1.1
244      * @param termResolver to be created
245      * @return the {@link TermResolverDefinition} after it has been created in the
246      * repository.
247      *
248      * @throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException if
249      * the termResolver is null or blank.
250      */
251     @WebMethod(operationName = "updateTermResolver")
252     @CacheEvict(value = {TermResolverDefinition.Cache.NAME, TermDefinition.Cache.NAME}, allEntries = true)
253     void updateTermResolver(@WebParam(name = "termResolver") TermResolverDefinition termResolver)
254             throws RiceIllegalArgumentException;
255 
256 
257     /**
258      * deletes the {@link TermResolverDefinition} with the given id
259      *
260      * @since 2.1.1
261      * @param id of the term resolver to be deleted
262      *
263      * @throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException if
264      * the termResolver is null or blank.
265      */
266     @WebMethod(operationName = "deleteTermResolver")
267     @CacheEvict(value = {TermResolverDefinition.Cache.NAME, TermDefinition.Cache.NAME}, allEntries = true)
268     void deleteTermResolver(@WebParam(name = "id") String id)
269             throws RiceIllegalArgumentException;
270 
271 
272     /**
273      * Retrieves the {@link TermResolverDefinition} for the given name and namespace
274      *
275      * @param name the name for which to get term resolver
276      * @param namespace the namespace for which to get term resolver
277      * @return the {@link TermResolverDefinition} for the given name and namespace, null if none exist.
278      *
279      * @throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException if the name or namespace is null or blank.
280      */
281     @WebMethod(operationName = "getTermResolverByNameAndNamespace")
282     @WebResult(name = "termResolver")
283     // TODO: set the cache right
284     //    @Cacheable(value = TermResolverDefinition.Cache.NAME, key = "'namespace=' + #p0")
285     TermResolverDefinition getTermResolverByNameAndNamespace(@WebParam(name = "name") String name,
286             @WebParam(name = "namespace") String namespace) throws RiceIllegalArgumentException;
287 
288 
289     /**
290      * Retrieves the {@link TermSpecificationDefinition} for the given name and namespace
291      *
292      * @param name the name for which to get term specification
293      * @param namespace the namespace for which to get term resolver
294      * @return the {@link TermSpecificationDefinition} for the given name and namespace, null if none exist.
295      *
296      * @throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException if the name or namespace is null or blank.
297      */
298     @WebMethod(operationName = "getTermSpecificationByNameAndNamespace")
299     @WebResult(name = "termSpecification")
300     // TODO: set the cache right
301     //    @Cacheable(value = TermSpecificationDefinition.Cache.NAME, key = "'namespace=' + #p0")
302     TermSpecificationDefinition getTermSpecificationByNameAndNamespace(@WebParam(name = "name") String name,
303             @WebParam(name = "namespace") String namespace) throws RiceIllegalArgumentException;
304 
305 
306     /**
307      * Retrieves all the {@link TermSpecificationDefinition}s that are valid for the context with the given contextId.
308      *
309      * @since 2.1.4
310      * @param contextId the identifier for the context whose valid {@link TermSpecificationDefinition}s are to be retrieved. 
311      * @return all the {@link TermSpecificationDefinition}s that are valid for the context with the given contextId. May be empty but never null
312      *
313      * @throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException if the contextId is null or blank.
314      */
315     @WebMethod(operationName = "findAllTermSpecificationsByContextId")
316     @XmlElementWrapper(name = "termSpecifications", required = true)
317     @XmlElement(name = "termSpecification", required = false)
318     @WebResult(name = "termSpecifications")
319     @Cacheable(value= TermSpecificationDefinition.Cache.NAME, key="'id=' + #p0")
320     List<TermSpecificationDefinition> findAllTermSpecificationsByContextId(@WebParam(name = "contextId") String contextId) throws RiceIllegalArgumentException;;
321 
322 }