org.kuali.rice.kew.framework.document.attribute
Interface SearchableAttribute

All Known Implementing Classes:

BookPriceSearchableAttribute, BookPublicationDateSearchableAttribute, BookRatingSearchableAttribute, BookTitleSearchableAttribute, BookTypeSearchableAttribute, DataDictionaryDocumentSearchCustomizer, DataDictionarySearchableAttribute, KualiXMLBooleanTranslatorSearchableAttributeImpl, KualiXmlSearchableAttributeImpl, StandardGenericXMLSearchableAttribute, XPathSearchableAttribute

public interface SearchableAttribute

Allows for definition of custom attributes on a document that should be indexed along with that document and made searchable when performing document searches. Applications who want to index and expose these custom attributes on their documents can implement this interface and configure their document type to point to the searchable attributes that it should use.

A searchable attribute provides the following basic functions:

• The ability to generate XML content that can be associated with the document and used for indexing purposes.
• The ability to extract attribute values from the document and supply them to the indexer for indexing.
• The ability to define how custom search attributes will be presented in the document search user interface.
• The ability to define validation for custom search attribute criteria which is executed from the document search user interface.

Searchable attributes are mapped to document types via the KEW extension framework (see ExtensionRepositoryService).

Through this extension mechanism, searchable attributes are designed to allow for re-use if desired. To facilitate this, the name of the document type for which the operation is being performed is included for all such methods which might make use of it. Additionally, all of the operations on a searchable attribute are passed the ExtensionDefinition which was used to define the instance of the searchable attribute and link it to the document type. The extension definition can be defined to include additional configuration which can be used by the various methods on the searchable attribute implementation. This allows for creating a single SearchableAttribute implementation which can then be parameterized externally by reusing the implementation in the extension repository, but parameterizing it via one ore more extension definitions.

This interface is annotated to allow for it to be exposed as a JAXWS web service, so client applications wanting to publish their own searchable attribute implementations may do so by publishing their search attribute implementations on the bus. However, this is optional as it is possible to declare an extension definition for a searchable attribute which uses the class name instead of a service name. In these cases, searchable attribute implementations will be located and invoked via an application's DocumentSearchCustomizationHandlerService endpoint assuming that the proper application id is associated with the extension definition.

Author:

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

See Also:

DocumentSearchCustomizationHandlerService, ExtensionRepositoryService, ExtensionDefinition, WorkflowAttributeDefinition

Method Summary

List<DocumentAttribute>	extractDocumentAttributes(ExtensionDefinition extensionDefinition, DocumentWithContent documentWithContent) Extracts and returns document attributes for the given document in order to allow indexing of those values for association with the document and use in document searches.
String	generateSearchContent(ExtensionDefinition extensionDefinition, String documentTypeName, WorkflowAttributeDefinition attributeDefinition) Allows for generation of custom XML for this searchable attribute.
List<RemotableAttributeField>	getSearchFields(ExtensionDefinition extensionDefinition, String documentTypeName) Returns a list of RemotableAttributeField objects which define which searchable attribute criteria fields should be included in the criteria section of the document search user interface for this searchable attribute.
List<RemotableAttributeError>	validateDocumentAttributeCriteria(ExtensionDefinition extensionDefinition, DocumentSearchCriteria documentSearchCriteria) Performs custom validation of document attribute values that come from this searchable attribute whenever a document search is performed against a document type which uses this searchable attribute.

Method Detail

generateSearchContent

String generateSearchContent(ExtensionDefinition extensionDefinition,
                             String documentTypeName,
                             WorkflowAttributeDefinition attributeDefinition)

Allows for generation of custom XML for this searchable attribute. The trigger for invocation of custom XML generation happens via the workflow API whenever a document action is taken and a request is submitted to update document XML based on searchable attribute definitions (see DocumentContentUpdate). This XML is ultimately included as part of the document's content.

It is intended that this XML can be used by the extractDocumentAttributes method in order to pull values out for indexing, though this method is free to use any source available to it for extracting data for indexing alongside a document.

A null or blank value may be returned from this method to indicate that no XML was generated.

Parameters:

extensionDefinition - the extension definition which was used to locate and load this searchable attribute implementation

documentTypeName - the name of the document type for which this method is being invoked

attributeDefinition - contains parameters and properties that can be used to inform generation of the XML, these are supplied by the user of the workflow API when the document's searchable XML content is requested to be updated

Returns:

a String containing valid XML that should be included in the searchable attribute XML section of the document's XML content

extractDocumentAttributes

List<DocumentAttribute> extractDocumentAttributes(ExtensionDefinition extensionDefinition,
                                                  DocumentWithContent documentWithContent)

Extracts and returns document attributes for the given document in order to allow indexing of those values for association with the document and use in document searches. The document and it's XML content is passed to this method as that is a common source of data for indexing purposes, though implementations are free to pull data for indexing from any readily accessible source.

There are a finite set of DocumentAttribute implementations which can be returned and interpreted correctly. Client application's should not create custom extensions of the DocumentAttribute abstract class but should preferably use the DocumentAttributeFactory to construct strongly-typed document attribute instances for indexing.

Parameters:

extensionDefinition - the extension definition which was used to locate and load this searchable attribute implementation

documentWithContent - the workflow document and it's XML content

Returns:

a list of document attribute values that should be indexed for the given document, or a null or empty list if no attributes should be indexed

See Also:

DocumentAttributeFactory

getSearchFields

List<RemotableAttributeField> getSearchFields(ExtensionDefinition extensionDefinition,
                                              String documentTypeName)

Returns a list of RemotableAttributeField objects which define which searchable attribute criteria fields should be included in the criteria section of the document search user interface for this searchable attribute.

Parameters:

extensionDefinition - the extension definition which was used to locate and load this searchable attribute implementation

documentTypeName - the name of the document type for which this method is being invoked

Returns:

a list of remotable attribute fields which define the search fields that should be included in the document search criteria, or a null or empty list if no criteria should be included for this searchable attribute

validateDocumentAttributeCriteria

List<RemotableAttributeError> validateDocumentAttributeCriteria(ExtensionDefinition extensionDefinition,
                                                                DocumentSearchCriteria documentSearchCriteria)

Performs custom validation of document attribute values that come from this searchable attribute whenever a document search is performed against a document type which uses this searchable attribute. This hook allows for any desired validation of this searchable attributes custom document attribute values to be performed prior to the execution of the document search.

The entire DocumentSearchCriteria is passed to this method, though it's intended that implementing code will pull out the document attribute values on the criteria which are managed by this searchable attribute and perform any desired validation. However, there are certainly no restrictions on this method that would prevent it from performing validations outside of this scope and in relation to other portions of the criteria, though this is certainly not the intent of this validation hook.

Note that this method is invoked when performing a document search from the user interface as well as via the WorkflowDocumentService api.

Parameters:

extensionDefinition - the extension definition which was used to locate and load this searchable attribute implementation

documentSearchCriteria - the criteria that was submitted to the document search and against which validation is requested

Returns:

a list of attribute errors containing and validation failure errors messages for the relevant document attributes, if this returns a null or empty list it means that validation was successful