org.kuali.rice.kew.framework.document.search
Interface DocumentSearchCustomizer

All Known Implementing Classes:

DataDictionaryDocumentSearchCustomizer, DocumentSearchCustomizerBase, NullDocumentSearchCustomizer

public interface DocumentSearchCustomizer

Provides various mechanisms for an application to customize the behavior of the Document Search functionality for their document types. Client applications should provide implementations of this interface if they need to enact some of these customizations on document searches. These customizers then get mapped to the appropriate document types via the KEW extension framework (see ExtensionRepositoryService).

The customization functionality provided by this interface includes:

• The ability to customize document search criteria before it gets submitted.
• The ability to customize how document search criteria is cleared.
• The ability to customize how result data is processed and presented.

Only one DocumentSearchCustomizer is supported for a given document type. It is important to note however that it is permitted that an implementation of this interface could be tied to more than one document type via the extension framework. This is why information about the specific document type for which the customizations is being applied is passed to all methods on this interface (note that the document type information is available from the DocumentSearchCriteria as well.

Furthermore, the customization hooks afforded by this interface will only be executed when a valid document type has been specified as input to the document search. This is because the customizer is tied to the document type and the document search must therefore be able to resolve a valid document type from the user-supplied criteria in order to perform these customizations.

Since some of the operations on this component could potentially add expense to the overall search process in the cases where customization is only done on certain document types or only certain customization features are being utilized, this interface provides for a set of boolean operations which indicate which customization features should be activated by the document search framework for a given document type. It's expected that KEW will check each of these flags prior to invoking the corresponding method that it "gaurds" and, if the customization flag is disabled, it should refrain from executing that method.

Implementations of this interface are expected to return "true" for any of these operations for which they provide a custom implementation. It is important to note that callers are permitted to cache the results returned from these boolean methods for an unspecified length of time. So if there is any possibility that, for a given document type, the implementation might perform a particular customization, then "true" should be returned from the appropriate boolean method.

Author:

Kuali Rice Team (rice.collab@kuali.org)

Method Summary

DocumentSearchCriteria	customizeClearCriteria(DocumentSearchCriteria documentSearchCriteria) Performs a customized "clear" of the given document search criteria.
DocumentSearchCriteria	customizeCriteria(DocumentSearchCriteria documentSearchCriteria) Performs customization on the given document search criteria.
DocumentSearchResultValues	customizeResults(DocumentSearchCriteria documentSearchCriteria, List<DocumentSearchResult> defaultResults) Performs customization of the given list of document search results.
DocumentSearchResultSetConfiguration	customizeResultSetConfiguration(DocumentSearchCriteria documentSearchCriteria) Performs customization of what result fields should be displayed in the result set.
boolean	isCustomizeClearCriteriaEnabled(String documentTypeName) Indicates if the customizeClearCriteria(org.kuali.rice.kew.api.document.search.DocumentSearchCriteria) on this customizer should be invoked for the document type with the given name.
boolean	isCustomizeCriteriaEnabled(String documentTypeName) Indicates if the customizeCriteria(org.kuali.rice.kew.api.document.search.DocumentSearchCriteria) on this customizer should be invoked for the document type with the given name.
boolean	isCustomizeResultsEnabled(String documentTypeName) Indicates if the customizeResults(org.kuali.rice.kew.api.document.search.DocumentSearchCriteria, java.util.List) on this customizer should be invoked for the document type with the given name.
boolean	isCustomizeResultSetFieldsEnabled(String documentTypeName) Indicates if the customizeResultSetConfiguration(org.kuali.rice.kew.api.document.search.DocumentSearchCriteria) on this customizer should be invoked for the document type with the given name.

Method Detail

customizeCriteria

DocumentSearchCriteria customizeCriteria(DocumentSearchCriteria documentSearchCriteria)

Performs customization on the given document search criteria. This method should return the customized version of the criteria, or null if no customizations were performed. This customization is invoked prior the actual search being executed, and the resulting customized criteria is what gets passed to the search implementation. It is also invoked in situtations where the document search is performed via the api or via the user interface.

It is guaranteed that the document type name on the given criteria will never be null and will always represent a valid document type.

Parameters:

documentSearchCriteria - the original criteria against which to perform customization, will never be null

Returns:

the customized criteria, or null if no customization was performed

customizeClearCriteria

DocumentSearchCriteria customizeClearCriteria(DocumentSearchCriteria documentSearchCriteria)

Performs a customized "clear" of the given document search criteria. Clearing of the criteria is typically invoked whenever the user of the document search user interface clicks the "clear" button. By default all of the search criteria is cleared, but this method allows for certain criteria data to be preserved on a clear if desired.

A common use of this feature is to preserve the document type that has been selected when clearing criteria for a customized document search.

It is guaranteed that the document type name on the given criteria will never be null and will always represent a valid document type.

Parameters:

documentSearchCriteria - the criteria to clear

Returns:

the cleared criteria, or null if no custom criteria clearing was performed

customizeResults

DocumentSearchResultValues customizeResults(DocumentSearchCriteria documentSearchCriteria,
                                            List<DocumentSearchResult> defaultResults)

Performs customization of the given list of document search results. This method is invoked after the search is executed but before results are returned to the caller. It is executed when a document search is executed via the api or from the document search user interface.

This method returns a DocumentSearchResultValues object which contains a list of DocumentSearchResultValue objects. Each of these result values maps to a specific document id and contains a list of DocumentAttribute values which can be used to modify existing document attributes or create new ones that are included as part of the search results. It is important to note that in order for these custom attribute values to be displayed in the result set in the document search user interface, there must be a corresponding entry in the DocumentSearchResultSetConfiguration returned by the customizeResultSetConfiguration(org.kuali.rice.kew.api.document.search.DocumentSearchCriteria) method on this customizer implementation.

It is permissible that implementations of this method may not return result values for all of the document provided in the given list of document search results. It is important to note however that ommision from the returned result values does not filter or remove the result from the search results. Generally speaking, this method cannot be used to remove results from the result set.

It is guaranteed that the document type name on the given criteria will never be null and will always represent a valid document type.

Parameters:

documentSearchCriteria - the criteria against which the document search was executed

defaultResults - the results that were returned by the execution of the document search

Returns:

customized search result values for any of the document results requiring custom values, or null if no customization was performed

customizeResultSetConfiguration

DocumentSearchResultSetConfiguration customizeResultSetConfiguration(DocumentSearchCriteria documentSearchCriteria)

Performs customization of what result fields should be displayed in the result set. Allows for hiding of standard fields, addition of custom fields, and the ability to override the default behavior of searchable attributes that are defined for the document type. Generally speaking, this controls which "columns" of data are displayed in the document search results.

This method is only invoked by the document search user interface whenever it is rendering document search results. It is not invoked when invoking document search using only the api.

It is guaranteed that the document type name on the given criteria will never be null and will always represent a valid document type.

Parameters:

documentSearchCriteria - the criteria against which the document search was executed

Returns:

the customized result set configuration, or null if no customization was performed

isCustomizeCriteriaEnabled

boolean isCustomizeCriteriaEnabled(String documentTypeName)

Indicates if the customizeCriteria(org.kuali.rice.kew.api.document.search.DocumentSearchCriteria) on this customizer should be invoked for the document type with the given name. The caller of this method is permitted to cache the return value for a length of time of their choosing.

Parameters:

documentTypeName - the name of the document type against which this customizer is being applied

Returns:

true if the customization method should be executed, false otherwise

isCustomizeClearCriteriaEnabled

boolean isCustomizeClearCriteriaEnabled(String documentTypeName)

Indicates if the customizeClearCriteria(org.kuali.rice.kew.api.document.search.DocumentSearchCriteria) on this customizer should be invoked for the document type with the given name. The caller of this method is permitted to cache the return value for a length of time of their choosing.

Parameters:

documentTypeName - the name of the document type against which this customizer is being applied

Returns:

true if the customization method should be executed, false otherwise

isCustomizeResultsEnabled

boolean isCustomizeResultsEnabled(String documentTypeName)

Indicates if the customizeResults(org.kuali.rice.kew.api.document.search.DocumentSearchCriteria, java.util.List) on this customizer should be invoked for the document type with the given name. The caller of this method is permitted to cache the return value for a length of time of their choosing.

Parameters:

documentTypeName - the name of the document type against which this customizer is being applied

Returns:

true if the customization method should be executed, false otherwise

isCustomizeResultSetFieldsEnabled

boolean isCustomizeResultSetFieldsEnabled(String documentTypeName)

Indicates if the customizeResultSetConfiguration(org.kuali.rice.kew.api.document.search.DocumentSearchCriteria) on this customizer should be invoked for the document type with the given name. The caller of this method is permitted to cache the return value for a length of time of their choosing.

Parameters:

documentTypeName - the name of the document type against which this customizer is being applied

Returns:

true if the customization method should be executed, false otherwise