001 /**
002 * Copyright 2005-2013 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.search;
017
018 import org.kuali.rice.core.api.exception.RiceIllegalArgumentException;
019 import org.kuali.rice.core.api.uif.RemotableAttributeError;
020 import org.kuali.rice.kew.api.KewApiConstants;
021 import org.kuali.rice.kew.api.document.search.DocumentSearchCriteria;
022 import org.kuali.rice.kew.api.document.search.DocumentSearchResult;
023 import org.kuali.rice.kew.framework.KewFrameworkServiceLocator;
024
025 import javax.jws.WebMethod;
026 import javax.jws.WebParam;
027 import javax.jws.WebResult;
028 import javax.jws.WebService;
029 import javax.jws.soap.SOAPBinding;
030 import javax.xml.bind.annotation.XmlElement;
031 import javax.xml.bind.annotation.XmlElementWrapper;
032 import java.util.List;
033 import java.util.Set;
034
035 /**
036 * A remotable service which handles processing of a client application's document search customizations.
037 *
038 * @author Kuali Rice Team (rice.collab@kuali.org)
039 */
040 @WebService(name = KewFrameworkServiceLocator.DOCUMENT_SEARCH_CUSTOMIZATION_HANDLER_SERVICE, targetNamespace = KewApiConstants.Namespaces.KEW_NAMESPACE_2_0)
041 @SOAPBinding(style = SOAPBinding.Style.DOCUMENT, use = SOAPBinding.Use.LITERAL, parameterStyle = SOAPBinding.ParameterStyle.WRAPPED)
042 public interface DocumentSearchCustomizationHandlerService {
043
044 /**
045 * Retrieves the custom {@code DocumentSearchCriteriaConfiguration} to use for the document type with the given name
046 * and for the given list of searchable attributes. This method is invoked by the document search implementation in
047 * order to help assemble the final criteria attribute fields (which includes configuration for all searchable
048 * attributes on the document type).
049 *
050 * <p>The given list of searchable attribute names may not necessary include all searchable attribute on the
051 * document type, only those which need to be handled by the client application hosting this service. This
052 * determination is made based on the applicationId which is associated with the searchable attribute.
053 * Implementations of this method will assemble this information by invoking the
054 * {@link org.kuali.rice.kew.framework.document.attribute.SearchableAttribute#getSearchFields(org.kuali.rice.kew.api.extension.ExtensionDefinition, String)}
055 * methods on each of the requested searchable attributes.</p>
056 *
057 * @param documentTypeName the document type name for which to retrieve the configuration
058 * @param searchableAttributeNames the names of the searchable attributes from which to assemble criteria
059 * configuration which are owned by the application hosting this service
060 *
061 * @return the custom document search criteria configuration for the given searchable attribute, or null if no
062 * custom configuration is needed
063 *
064 * @throws RiceIllegalArgumentException if documentTypeName is a null or blank value
065 */
066 @WebMethod(operationName = "getDocumentSearchConfiguration")
067 @WebResult(name = "documentSearchConfiguration")
068 @XmlElement(name = "documentSearchConfiguration", required = false)
069 DocumentSearchCriteriaConfiguration getDocumentSearchConfiguration(
070 @WebParam(name = "documentTypeName") String documentTypeName,
071 @WebParam(name = "searchableAttributeNames") List<String> searchableAttributeNames) throws RiceIllegalArgumentException;
072
073 /**
074 * Executes validation of the given {@code DocumentSearchCriteria} against the searchable attributes with the given
075 * names.. This method is invoked by the document search implementation in order to allow for validation to be
076 * customized via custom searchable attribute implementations.
077 *
078 * <p>The given list of searchable attribute names may not necessary include all searchable attribute on the
079 * document type, only those which need to be handled by the client application hosting this service. This
080 * determination is made based on the applicationId which is associated with the searchable attribute.
081 * Implementations of this method execute this validationby invoking the
082 * {@link org.kuali.rice.kew.framework.document.attribute.SearchableAttribute#validateDocumentAttributeCriteria(org.kuali.rice.kew.api.extension.ExtensionDefinition, org.kuali.rice.kew.api.document.search.DocumentSearchCriteria)}
083 * methods on each of the requested searchable attributes.</p>
084 *
085 * @param documentSearchCriteria the criteria against which to perform the validation
086 * @param searchableAttributeNames the names of the searchable attributes against which to execute validation which
087 * are owned by the application hosting this service
088 *
089 * @return a list or remotable attribute errors in the case that any validation errors were raised by the
090 * requested searchable attributes
091 *
092 * @throws RiceIllegalArgumentException if documentTypeName is a null or blank value
093 */
094 @WebMethod(operationName = "validateCriteria")
095 @WebResult(name = "errors")
096 @XmlElementWrapper(name = "errors", required = true)
097 @XmlElement(name = "errors", required = false)
098 List<RemotableAttributeError> validateCriteria(@WebParam(name = "documentSearchCriteria") DocumentSearchCriteria documentSearchCriteria,
099 @WebParam(name = "searchableAttributeNames") List<String> searchableAttributeNames
100 ) throws RiceIllegalArgumentException;
101
102 /**
103 * Executes criteria customization against the given criteria using the {@link DocumentSearchCustomizer} with the
104 * given customizer name. This name is the name of the {@code ExtensionDefinition} that defines the customizer
105 * where the customizer extension's applicationId is the same as the application hosting this service.
106 *
107 * <p>This method effectively invokes the {@link DocumentSearchCustomizer#customizeCriteria(org.kuali.rice.kew.api.document.search.DocumentSearchCriteria)}
108 * on the requested customizer which is owned by this application.
109 *
110 * @param documentSearchCriteria the criteria to customize
111 * @param customizerName the name of the extension definition for the {@code DocumentSearchCustomizer} which should
112 * be used in order to execute the customization
113 *
114 * @return the customized criteria, or null if no customization was performed
115 *
116 * @throws RiceIllegalArgumentException if documentSearchCriteria is null
117 * @throws RiceIllegalArgumentException if customizerName is a null or blank value
118 */
119 @WebMethod(operationName = "customizeCriteria")
120 @WebResult(name = "documentSearchCriteria")
121 @XmlElement(name = "documentSearchCriteria", required = false)
122 DocumentSearchCriteria customizeCriteria(
123 @WebParam(name = "documentSearchCriteria") DocumentSearchCriteria documentSearchCriteria,
124 @WebParam(name = "customizerName") String customizerName
125 ) throws RiceIllegalArgumentException;
126
127 /**
128 * Executes custom criteria clearing against the given criteria using the {@link DocumentSearchCustomizer} with the
129 * given customizer name. This name is the name of the {@code ExtensionDefinition} that defines the customizer
130 * where the customizer extension's applicationId is the same as the application hosting this service.
131 *
132 * <p>This method effectively invokes the {@link DocumentSearchCustomizer#customizeClearCriteria(org.kuali.rice.kew.api.document.search.DocumentSearchCriteria)}
133 * on the requested customizer which is owned by this application.
134 *
135 * @param documentSearchCriteria the criteria on which to perform custom clearing
136 * @param customizerName the name of the extension definition for the {@code DocumentSearchCustomizer} which should
137 * be used in order to execute the customization
138 *
139 * @return the cleared criteria, or null if no custom clear was performed
140 *
141 * @throws RiceIllegalArgumentException if documentSearchCriteria is null
142 * @throws RiceIllegalArgumentException if customizerName is a null or blank value
143 */
144 @WebMethod(operationName = "customizeClearCriteria")
145 @WebResult(name = "documentSearchCriteria")
146 @XmlElement(name = "documentSearchCriteria", required = false)
147 DocumentSearchCriteria customizeClearCriteria(
148 @WebParam(name = "documentSearchCriteria") DocumentSearchCriteria documentSearchCriteria,
149 @WebParam(name = "customizerName") String customizerName
150 ) throws RiceIllegalArgumentException;
151
152 /**
153 * Executes customization of document search results using the {@link DocumentSearchCustomizer} with the
154 * given customizer name. This name is the name of the {@code ExtensionDefinition} that defines the customizer
155 * where the customizer extension's applicationId is the same as the application hosting this service.
156 *
157 * <p>This method effectively invokes the {@link DocumentSearchCustomizer#customizeResults(org.kuali.rice.kew.api.document.search.DocumentSearchCriteria, java.util.List)}
158 * on the requested customizer which is owned by this application.
159 *
160 * @param documentSearchCriteria the criteria that was used to perform the lookup
161 * @param results the results that were returned from the lookup
162 * @param customizerName the name of the extension definition for the {@code DocumentSearchCustomizer} which should
163 * be used in order to execute the customization
164 *
165 * @return the customized document search results values, or null if no customization was performed
166 *
167 * @throws RiceIllegalArgumentException if documentSearchCriteria is null
168 * @throws RiceIllegalArgumentException if results is null
169 * @throws RiceIllegalArgumentException if customizerName is a null or blank value
170 */
171 @WebMethod(operationName = "customizeResults")
172 @WebResult(name = "resultValues")
173 @XmlElement(name = "resultValues", required = false)
174 DocumentSearchResultValues customizeResults(
175 @WebParam(name = "documentSearchCriteria") DocumentSearchCriteria documentSearchCriteria,
176 @WebParam(name = "results") List<DocumentSearchResult> results,
177 @WebParam(name = "customizerName") String customizerName
178 ) throws RiceIllegalArgumentException;
179
180 /**
181 * Executes customization of document search result set configuration using the {@link DocumentSearchCustomizer}
182 * with the given customizer name. This name is the name of the {@code ExtensionDefinition} that defines the
183 * customizer where the customizer extension's applicationId is the same as the application hosting this service.
184 *
185 * <p>This method effectively invokes the {@link DocumentSearchCustomizer#customizeResultSetConfiguration(org.kuali.rice.kew.api.document.search.DocumentSearchCriteria)}
186 * on the requested customizer which is owned by this application.
187 *
188 * @param documentSearchCriteria the criteria that was used to perform the lookup
189 * @param customizerName the name of the extension definition for the {@code DocumentSearchCustomizer} which should
190 * be used in order to execute the customization
191 *
192 * @return the customized document search result configuration, or null if no customization was performed
193 *
194 * @throws RiceIllegalArgumentException if documentSearchCriteria is null
195 * @throws RiceIllegalArgumentException if customizerName is a null or blank value
196 */
197 @WebMethod(operationName = "customizeResultSetConfiguration")
198 @WebResult(name = "resultSetConfiguration")
199 @XmlElement(name = "resultSetConfiguration", required = false)
200 DocumentSearchResultSetConfiguration customizeResultSetConfiguration(
201 @WebParam(name = "documentSearchCriteria") DocumentSearchCriteria documentSearchCriteria,
202 @WebParam(name = "customizerName") String customizerName) throws RiceIllegalArgumentException;
203
204 /**
205 * Returns the set of customizations that are enabled and should be executed for the {@link DocumentSearchCustomizer}
206 * with the given customizer name. This name is the name of the {@code ExtensionDefinition} that defines the
207 * customizer where the customizer extension's applicationId is the same as the application hosting this service.
208 *
209 * <p>This method essentially invokes the various boolean methods on the {@code DocumentSearchCustomizer} which
210 * indicate which customizations the implementation provides. This primarily serves as a means of optimization to
211 * reduce the number of remote callbacks that the document search implementation needs to make to the various
212 * customizations provided by this service and the customizers it delegates too.</p>
213 *
214 * @param documentTypeName the name of the document type against which to check for enabled customizations on the
215 * specified customizer
216 * @param customizerName the name of the extension definition for the {@code DocumentSearchCustomizer} which should
217 * be used in order to check for enabled customizations
218 *
219 * @return the set of customizations that are enabled
220 *
221 * @throws RiceIllegalArgumentException if documentTypeName is a null or blank value
222 * @throws RiceIllegalArgumentException if customizerName is a null or blank value
223 */
224 @WebMethod(operationName = "getEnabledCustomizations")
225 @WebResult(name = "enabledCustomizations")
226 @XmlElementWrapper(name = "enabledCustomizations", required = true)
227 @XmlElement(name = "enabledCustomization", required = false)
228 Set<DocumentSearchCustomization> getEnabledCustomizations(
229 @WebParam(name = "documentTypeName") String documentTypeName,
230 @WebParam(name = "customizerName") String customizerName
231 ) throws RiceIllegalArgumentException;
232
233 }