001 /**
002 * Copyright 2005-2011 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 */
016 package org.kuali.rice.kew.framework.document.attribute;
017
018 import org.kuali.rice.core.api.uif.RemotableAttributeError;
019 import org.kuali.rice.core.api.uif.RemotableAttributeField;
020 import org.kuali.rice.kew.api.KewApiConstants;
021 import org.kuali.rice.kew.api.document.DocumentWithContent;
022 import org.kuali.rice.kew.api.document.attribute.DocumentAttribute;
023 import org.kuali.rice.kew.api.document.attribute.WorkflowAttributeDefinition;
024 import org.kuali.rice.kew.api.document.search.DocumentSearchCriteria;
025 import org.kuali.rice.kew.api.extension.ExtensionDefinition;
026
027 import javax.jws.WebMethod;
028 import javax.jws.WebParam;
029 import javax.jws.WebResult;
030 import javax.jws.WebService;
031 import javax.jws.soap.SOAPBinding;
032 import javax.xml.bind.annotation.XmlElement;
033 import javax.xml.bind.annotation.XmlElementWrapper;
034 import java.util.List;
035
036 /**
037 * Allows for definition of custom attributes on a document that should be indexed along with that document and made
038 * searchable when performing document searches. Applications who want to index and expose these custom attributes on
039 * their documents can implement this interface and configure their document type to point to the searchable attributes
040 * that it should use.
041 *
042 * <p>A searchable attribute provides the following basic functions:</p>
043 *
044 * <ul>
045 * <li>The ability to generate XML content that can be associated with the document and used for indexing purposes.</li>
046 * <li>The ability to extract attribute values from the document and supply them to the indexer for indexing.</li>
047 * <li>The ability to define how custom search attributes will be presented in the document search user interface.</li>
048 * <li>The ability to define validation for custom search attribute criteria which is executed from the document search user interface.</li>
049 * </ul>
050 *
051 * <p>Searchable attributes are mapped to document types via the KEW extension framework (see
052 * {@link org.kuali.rice.kew.api.extension.ExtensionRepositoryService}).
053 *
054 * <p>Through this extension mechanism, searchable attributes are designed to allow for re-use if desired. To
055 * facilitate this, the name of the document type for which the operation is being performed is included for all such
056 * methods which might make use of it. Additionally, all of the operations on a searchable attribute are passed the
057 * {@link ExtensionDefinition} which was used to define the instance of the searchable attribute and link it to the
058 * document type. The extension definition can be defined to include additional configuration which can be used by the
059 * various methods on the searchable attribute implementation. This allows for creating a single
060 * {@code SearchableAttribute} implementation which can then be parameterized externally by reusing the implementation
061 * in the extension repository, but parameterizing it via one ore more extension definitions.</p>
062 *
063 * <p>This interface is annotated to allow for it to be exposed as a JAXWS web service, so client applications
064 * wanting to publish their own searchable attribute implementations may do so by publishing their search attribute
065 * implementations on the bus. However, this is optional as it is possible to declare an extension definition for a searchable
066 * attribute which uses the class name instead of a service name. In these cases, searchable attribute implementations
067 * will be located and invoked via an application's
068 * {@link org.kuali.rice.kew.framework.document.search.DocumentSearchCustomizationHandlerService} endpoint assuming that
069 * the proper application id is associated with the extension definition.</p>
070 *
071 * @see org.kuali.rice.kew.framework.document.search.DocumentSearchCustomizationHandlerService
072 * @see org.kuali.rice.kew.api.extension.ExtensionRepositoryService
073 * @see ExtensionDefinition
074 * @see WorkflowAttributeDefinition
075 *
076 * @author Kuali Rice Team (rice.collab@kuali.org)
077 */
078 @WebService(name = "searchableAttributeService", targetNamespace = KewApiConstants.Namespaces.KEW_NAMESPACE_2_0)
079 @SOAPBinding(style = SOAPBinding.Style.DOCUMENT, use = SOAPBinding.Use.LITERAL, parameterStyle = SOAPBinding.ParameterStyle.WRAPPED)
080 public interface SearchableAttribute {
081
082 /**
083 * Allows for generation of custom XML for this searchable attribute. The trigger for invocation of custom XML
084 * generation happens via the workflow API whenever a document action is taken and a request is submitted to update
085 * document XML based on searchable attribute definitions (see
086 * {@link org.kuali.rice.kew.api.document.DocumentContentUpdate}). This XML is ultimately included as part of the
087 * document's content.
088 *
089 * <p>It is intended that this XML can be used by the {@code extractDocumentAttributes} method in order to pull
090 * values out for indexing, though this method is free to use any source available to it for extracting data for
091 * indexing alongside a document.</p>
092 *
093 * <p>A null or blank value may be returned from this method to indicate that no XML was generated.</p>
094 *
095 * @param extensionDefinition the extension definition which was used to locate and load this searchable attribute
096 * implementation
097 * @param documentTypeName the name of the document type for which this method is being invoked
098 * @param attributeDefinition contains parameters and properties that can be used to inform generation of the XML,
099 * 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 }