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.framework.document.attribute;
17
18 import org.kuali.rice.core.api.uif.RemotableAttributeError;
19 import org.kuali.rice.core.api.uif.RemotableAttributeField;
20 import org.kuali.rice.kew.api.KewApiConstants;
21 import org.kuali.rice.kew.api.document.DocumentWithContent;
22 import org.kuali.rice.kew.api.document.attribute.DocumentAttribute;
23 import org.kuali.rice.kew.api.document.attribute.WorkflowAttributeDefinition;
24 import org.kuali.rice.kew.api.document.search.DocumentSearchCriteria;
25 import org.kuali.rice.kew.api.extension.ExtensionDefinition;
26
27 import javax.jws.WebMethod;
28 import javax.jws.WebParam;
29 import javax.jws.WebResult;
30 import javax.jws.WebService;
31 import javax.jws.soap.SOAPBinding;
32 import javax.xml.bind.annotation.XmlElement;
33 import javax.xml.bind.annotation.XmlElementWrapper;
34 import java.util.List;
35
36 /**
37 * Allows for definition of custom attributes on a document that should be indexed along with that document and made
38 * searchable when performing document searches. Applications who want to index and expose these custom attributes on
39 * their documents can implement this interface and configure their document type to point to the searchable attributes
40 * that it should use.
41 *
42 * <p>A searchable attribute provides the following basic functions:</p>
43 *
44 * <ul>
45 * <li>The ability to generate XML content that can be associated with the document and used for indexing purposes.</li>
46 * <li>The ability to extract attribute values from the document and supply them to the indexer for indexing.</li>
47 * <li>The ability to define how custom search attributes will be presented in the document search user interface.</li>
48 * <li>The ability to define validation for custom search attribute criteria which is executed from the document search user interface.</li>
49 * </ul>
50 *
51 * <p>Searchable attributes are mapped to document types via the KEW extension framework (see
52 * {@link org.kuali.rice.kew.api.extension.ExtensionRepositoryService}).
53 *
54 * <p>Through this extension mechanism, searchable attributes are designed to allow for re-use if desired. To
55 * facilitate this, the name of the document type for which the operation is being performed is included for all such
56 * methods which might make use of it. Additionally, all of the operations on a searchable attribute are passed the
57 * {@link ExtensionDefinition} which was used to define the instance of the searchable attribute and link it to the
58 * document type. The extension definition can be defined to include additional configuration which can be used by the
59 * various methods on the searchable attribute implementation. This allows for creating a single
60 * {@code SearchableAttribute} implementation which can then be parameterized externally by reusing the implementation
61 * in the extension repository, but parameterizing it via one ore more extension definitions.</p>
62 *
63 * <p>This interface is annotated to allow for it to be exposed as a JAXWS web service, so client applications
64 * wanting to publish their own searchable attribute implementations may do so by publishing their search attribute
65 * implementations on the bus. However, this is optional as it is possible to declare an extension definition for a searchable
66 * attribute which uses the class name instead of a service name. In these cases, searchable attribute implementations
67 * will be located and invoked via an application's
68 * {@link org.kuali.rice.kew.framework.document.search.DocumentSearchCustomizationHandlerService} endpoint assuming that
69 * the proper application id is associated with the extension definition.</p>
70 *
71 * @see org.kuali.rice.kew.framework.document.search.DocumentSearchCustomizationHandlerService
72 * @see org.kuali.rice.kew.api.extension.ExtensionRepositoryService
73 * @see ExtensionDefinition
74 * @see WorkflowAttributeDefinition
75 *
76 * @author Kuali Rice Team (rice.collab@kuali.org)
77 */
78 @WebService(name = "searchableAttributeService", targetNamespace = KewApiConstants.Namespaces.KEW_NAMESPACE_2_0)
79 @SOAPBinding(style = SOAPBinding.Style.DOCUMENT, use = SOAPBinding.Use.LITERAL, parameterStyle = SOAPBinding.ParameterStyle.WRAPPED)
80 public interface SearchableAttribute {
81
82 /**
83 * Allows for generation of custom XML for this searchable attribute. The trigger for invocation of custom XML
84 * generation happens via the workflow API whenever a document action is taken and a request is submitted to update
85 * document XML based on searchable attribute definitions (see
86 * {@link org.kuali.rice.kew.api.document.DocumentContentUpdate}). This XML is ultimately included as part of the
87 * document's content.
88 *
89 * <p>It is intended that this XML can be used by the {@code extractDocumentAttributes} method in order to pull
90 * values out for indexing, though this method is free to use any source available to it for extracting data for
91 * indexing alongside a document.</p>
92 *
93 * <p>A null or blank value may be returned from this method to indicate that no XML was generated.</p>
94 *
95 * @param extensionDefinition the extension definition which was used to locate and load this searchable attribute
96 * implementation
97 * @param documentTypeName the name of the document type for which this method is being invoked
98 * @param attributeDefinition contains parameters and properties that can be used to inform generation of the XML,
99 * these are supplied by the user of the workflow API when the document's searchable XML content is requested to be
100 * updated
101 *
102 * @return a String containing valid XML that should be included in the searchable attribute XML section of the
103 * document's XML content
104 */
105 @WebMethod(operationName = "generateSearchContent")
106 @WebResult(name = "searchContent")
107 public String generateSearchContent(
108 @WebParam(name = "extensionDefinition") ExtensionDefinition extensionDefinition,
109 @WebParam(name = "documentTypeName") String documentTypeName,
110 @WebParam(name = "attributeDefinition") WorkflowAttributeDefinition attributeDefinition
111 );
112
113 /**
114 * Extracts and returns document attributes for the given document in order to allow indexing of those values for
115 * association with the document and use in document searches. The document and it's XML content is passed to this
116 * method as that is a common source of data for indexing purposes, though implementations are free to pull data for
117 * indexing from any readily accessible source.
118 *
119 * <p>There are a finite set of {@link DocumentAttribute} implementations which can be returned and interpreted
120 * correctly. Client application's should <strong>not</strong> create custom extensions of the
121 * {@code DocumentAttribute} abstract class but should preferably use the
122 * {@link org.kuali.rice.kew.api.document.attribute.DocumentAttributeFactory} to construct strongly-typed document
123 * attribute instances for indexing.</p>
124 *
125 * @param extensionDefinition the extension definition which was used to locate and load this searchable attribute
126 * implementation
127 * @param documentWithContent the workflow document and it's XML content
128 *
129 * @return a list of document attribute values that should be indexed for the given document, or a null or empty
130 * list if no attributes should be indexed
131 *
132 * @see org.kuali.rice.kew.api.document.attribute.DocumentAttributeFactory
133 */
134 @WebMethod(operationName = "extractDocumentAttributes")
135 @WebResult(name = "documentAttributes")
136 @XmlElementWrapper(name = "documentAttributes", required = false)
137 @XmlElement(name = "documentAttribute", required = false)
138 public List<DocumentAttribute> extractDocumentAttributes(
139 @WebParam(name = "extensionDefinition") ExtensionDefinition extensionDefinition,
140 @WebParam(name = "documentWithContent") DocumentWithContent documentWithContent);
141
142 /**
143 * Returns a list of {@link RemotableAttributeField} objects which define which searchable attribute criteria fields
144 * should be included in the criteria section of the document search user interface for this searchable attribute.
145 *
146 * @param extensionDefinition the extension definition which was used to locate and load this searchable attribute
147 * implementation
148 * @param documentTypeName the name of the document type for which this method is being invoked
149 *
150 * @return a list of remotable attribute fields which define the search fields that should be included in the
151 * document search criteria, or a null or empty list if no criteria should be included for this searchable attribute
152 */
153 @WebMethod(operationName = "getSearchFields")
154 @WebResult(name = "searchFields")
155 @XmlElementWrapper(name = "searchFields", required = false)
156 @XmlElement(name = "searchField", required = false)
157 public List<RemotableAttributeField> getSearchFields(
158 @WebParam(name = "extensionDefinition") ExtensionDefinition extensionDefinition,
159 @WebParam(name = "documentTypeName") String documentTypeName
160 );
161
162 /**
163 * Performs custom validation of document attribute values that come from this searchable attribute whenever a
164 * document search is performed against a document type which uses this searchable attribute. This hook allows for
165 * any desired validation of this searchable attributes custom document attribute values to be performed prior to
166 * the execution of the document search.
167 *
168 * <p>The entire {@link org.kuali.rice.kew.api.document.search.DocumentSearchCriteria} is passed to this method, though it's intended that implementing
169 * code will pull out the document attribute values on the criteria which are managed by this searchable attribute
170 * and perform any desired validation. However, there are certainly no restrictions on this method that would
171 * prevent it from performing validations outside of this scope and in relation to other portions of the criteria,
172 * though this is certainly not the intent of this validation hook.</p>
173 *
174 * <p>Note that this method is invoked when performing a document search from the user interface as well as via
175 * the {@link org.kuali.rice.kew.api.document.WorkflowDocumentService} api.</p>
176 *
177 * @param extensionDefinition the extension definition which was used to locate and load this searchable attribute
178 * implementation
179 * @param documentSearchCriteria the criteria that was submitted to the document search and against which validation
180 * is requested
181 *
182 * @return a list of attribute errors containing and validation failure errors messages for the relevant document
183 * attributes, if this returns a null or empty list it means that validation was successful
184 */
185 @WebMethod(operationName = "validateSearchParameters")
186 @WebResult(name = "validationErrors")
187 @XmlElementWrapper(name = "validationErrors", required = false)
188 @XmlElement(name = "validationError", required = false)
189 public List<RemotableAttributeError> validateDocumentAttributeCriteria(
190 @WebParam(name = "extensionDefinition") ExtensionDefinition extensionDefinition,
191 @WebParam(name = "documentSearchCriteria") DocumentSearchCriteria documentSearchCriteria
192 );
193
194 }