Package org.kuali.rice.kew.framework.document.search

Interface DocumentSearchCustomizer

All Known Implementing Classes:
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 Details

    • 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