001 /**
002 * Copyright 2005-2012 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.docsearch;
017
018 import org.kuali.rice.core.api.uif.RemotableAttributeError;
019 import org.kuali.rice.kew.api.document.search.DocumentSearchCriteria;
020 import org.kuali.rice.kew.api.document.search.DocumentSearchResults;
021 import org.kuali.rice.kew.framework.document.search.DocumentSearchCriteriaConfiguration;
022 import org.kuali.rice.kew.framework.document.search.DocumentSearchResultSetConfiguration;
023 import org.kuali.rice.kew.framework.document.search.DocumentSearchResultValues;
024 import org.kuali.rice.kew.doctype.bo.DocumentType;
025
026 import java.util.List;
027
028 /**
029 * Handles communication between {@link org.kuali.rice.kew.framework.document.search.DocumentSearchCustomizationHandlerService}
030 * endpoints in order to invoke document search customizations which might be hosted from various applications.
031 *
032 * @author Kuali Rice Team (rice.collab@kuali.org)
033 */
034 public interface DocumentSearchCustomizationMediator {
035
036 /**
037 * Retrieves the document search criteria configuration for the given document type. This should include attribute
038 * fields that should be included in the document search user interface when displaying criteria by which a user
039 * can search for documents. If this method returns null then no additional criteria should be presented on the
040 * search screen.
041 *
042 * @param documentType the document type for which to find document search criteria configuration, must not be null
043 *
044 * @return configuration information containing additional criteria (beyond the default set) which should be
045 * displayed to the user when performing a search against documents of the given type, if null is returned this
046 * indicates that the default document search criteria configuration should be used
047 */
048 DocumentSearchCriteriaConfiguration getDocumentSearchCriteriaConfiguration(DocumentType documentType);
049
050 /**
051 * Performs optional validation of document search criteria prior to execution of the search.
052 *
053 * @param documentType the document type against which the lookup is being performed
054 * @param documentSearchCriteria the criteria representing the submission of the document search
055 *
056 * @return a list of error messages generated by the validation, may an empty list in which case the calling code
057 * may safely ignore the response and assume that the given criteria validated successfully
058 */
059 List<RemotableAttributeError> validateLookupFieldParameters(DocumentType documentType,
060 DocumentSearchCriteria documentSearchCriteria);
061
062 /**
063 * Optionally performs customization of the given document search criteria in the cases where the document type
064 * implements criteria customization. If this method returns a non-null value, then the calling code should use
065 * the returned criteria in order to execute the search. If this method returns a null value, it means the criteria
066 * that was given did not require any customization. In this case, the calling code should proceed with search
067 * execution using the originally provided criteria.
068 *
069 * @param documentType the document type against which to perform the criteria customization, should never be null
070 * @param documentSearchCriteria the criteria to use as the starting point for customization
071 *
072 * @return a customized version of the given criteria, or null if the criteria was not customized
073 */
074 DocumentSearchCriteria customizeCriteria(DocumentType documentType, DocumentSearchCriteria documentSearchCriteria);
075
076 /**
077 * Optionally performs a custom clearing of the given document search criteria if the given document type
078 * implements a customized clear algorithm. If this method returns a non-null value, then the value returned
079 * should be instated by the calling code as the "cleared" version of the criteria. If null is returned, then the
080 * default implementation of criteria clearing should be used.
081 *
082 * @param documentType the document type against which to check for a custom implementation of criteria clearing
083 * @param documentSearchCriteria the current criteria of the document search prior to being cleared
084 *
085 * @return the result of clearing the criteria, if this returns null it means the given document type does not
086 * implement custom clearing and the default behavior should be used
087 */
088 DocumentSearchCriteria customizeClearCriteria(DocumentType documentType,
089 DocumentSearchCriteria documentSearchCriteria);
090
091 /**
092 * Optionally performs customization on the given set of document search results. This could include changing
093 * existing document values or synthesizing new ones. The results of this method include a list of
094 * {@link org.kuali.rice.kew.framework.document.search.DocumentSearchResultValue} objects, each of which are mapped to a
095 * specific document id from the results and include additional key-value pairs for customized or synthesized
096 * values for that document. This method can return a null value if no customization was performed.
097 *
098 * @param documentType the document type to use when determining what customization logic (if any) should be invoked
099 * @param documentSearchCriteria the criteria of the document search which produced the supplied results
100 * @param results the results of the document search which are being considered for customization
101 *
102 * @return the customized result values, or null if not result customization was performed
103 */
104 DocumentSearchResultValues customizeResults(DocumentType documentType,
105 DocumentSearchCriteria documentSearchCriteria,
106 DocumentSearchResults results);
107
108 /**
109 * Optionally provides configuration information that allows for document search result set customization to occur.
110 * The resulting {@code DocumentSearchResultSetConfiguration} can be used by the calling code to determine how best
111 * to render the lookup results.
112 *
113 * @param documentType the document type for which to customize result set configuration
114 * @param documentSearchCriteria the criteria that was used to perform the lookup
115 *
116 * @return the customized document search result set configuration, or null if no result set customization was
117 * performed
118 */
119 DocumentSearchResultSetConfiguration customizeResultSetConfiguration(DocumentType documentType,
120 DocumentSearchCriteria documentSearchCriteria);
121
122 }
123
124