# Package com.documentum.fc.client.search

package com.documentum.fc.client.search

Provides classes and interfaces for constructing and running search queries against multiple content repositories as well as external information sources (optional). The classes and intefaces of this package are collectively known as the Search Service. The Search Service provides an advanced facility for creating and managing Documentum queries.

The Search Service is built on top of the Federated Search Services (FS2) framework and hides the complexity of dealing with a variety of sources. It provides a unique view of Documentum content repositories and external repositories. It also supports pass-through queries for executing complex DQL queries across multiple content repositories. To get more information about the search functionality, you can refer to the Search Development Guide written by Lani Hardage-Vergeer. This guide is accessible from http://powerlink.emc.com/ (Search "search development guide").

Note: If your needs are simple or if you need explicit control over all phases of query execution you should use `IDfQuery` directly. If however you want to take advantage of the advanced features of the Search Service you can use the interfaces in this package.

The Search Service provides the following advanced features:

- Support for building full-text queries.
- Integrated data dictionary support for building advanced queries.
- An infrastructure for performing multithreaded, multisource asynchronous queries.
- Manipulation and unification of result sets across sources.
- The ability to load and save Documentum Smartlists.

Query definition:

The definition of a query should be performed through `IDfQueryBuilder`.
Special support for full-text searches is provided:

>             IDfQueryBuilder queryBuilder = <DfQueryManager>.newQueryBuilder();
>             queryBuilder.addSelectedSource("philo_docbase");
>             IDfExpressionSet rootExpressionSet = queryBuilder.getRootExpressionSet();
>             rootExpressionSet.addFullTextExpression("Descartes Nietsche Kant");

Building a more advanced search with multiple clauses can also be performed:

>             IDfQueryBuilder queryBuilder = <DfQueryManager>.newQueryBuilder();
>             queryBuilder.addSelectedSource("philo_docbase");
>             IDfExpressionSet rootExpressionSet = queryBuilder.getRootExpressionSet();
>             rootExpressionSet.addSimpleAttrExpression("authors", IDfValue.DF_STRING,
>             IDfSimpleAttrExpression.SEARCH_OP_CONTAINS, true, true, "Descartes");
>             rootExpressionSet.addSimpleAttrExpression("object_name", IDfValue.DF_STRING,
>             IDfSimpleAttrExpression.SEARCH_OP_DOES_NOT_CONTAIN, true, false, "encyclopedia");

Selection of the sources looks like:

>             IDfQueryBuilder queryBuilder = <DfQueryManager>.newQueryBuilder();
>             queryBuilder.addSelectedSource("philo_docbase"); // a first content repository
>             queryBuilder.addSelectedSource("university_docbase"); // a second content repository
>             queryBuilder.addSelectedSource("library/LoC"); // an external source
>             queryBuilder.addSelectedSource("museum/Smithonian"); // another external source

Query execution

The execution of a query is managed through `IDfQueryProcessor`. It supports two execution modes:

- Synchronous searches: the caller is blocked until all sources have responded. The result set returned by the processor contains results from all sources.
- Asynchronous searches: the caller will be notified asynchronously whenever new results are collected from a source. This allows the caller to display some results as soon as they are available without being blocked by the slowest of the sources.

The Search Service returns only a limited number of results. The maximum number of results can be configured in dfc.properties with a maximum number of results per source and a maximum number of results for a search (applying to the set of results from all the selected sources). You can refer to dfcfull.properties to get a detailed description of these properties.
Synchronous search:

>         // Establish session and get general query manager
>         IDfSearchService searchService = <IDfClient>.newSearchService(<IDfSessionManager>);
>         IDfQueryManager queryManager = searchService.newQueryMgr();

>         // Create a new query builder for each query
>         IDfQueryBuilder queryBuilder = queryManager.newQueryBuilder();
>         IDfQueryProcessor processor = searchService.newQueryProcessor(queryBuilder, true);

>         processor.blockingSearch(SEARCH_TIMEOUT);

>         IDfResultsSet results = processor.getResults() ;
>         IDfQueryStatus status = processor.getQueryStatus() ;

>         while (results.next())
>         {
>         System.out.println("results = " + results.getResult());
>         }
>         System.out.println("status = " + status);

Asynchronous search:

>         // Caller implements IDfQueryListener

>         // Establish session and get general query manager
>         IDfSearchService searchService = <IDfClient>.newSearchService(<IDfSessionManager>);
>         IDfQueryManager queryManager = searchService.newQueryMgr();

>         // Create a new query builder for each query
>         IDfQueryBuilder queryBuilder = queryManager.newQueryBuilder();
>         IDfQueryProcessor processor = searchService.newQueryProcessor(queryBuilder, true);

>         // Register as listener before starting the search
>         processor.addListener(this);

>         // Fire the search
>         processor.search();

>         // Go do some actual work while waiting for notifications:
>         // - onQueryCompleted
>         // - onStatusChange
>         // - onResultChange

>         ...

Result manipulation:

Some utility methods are provided to manipulate the result set in the class `IDfResultsManipulator`. Sort by on a specific attribute or using a custom comparator is possible.
Working with individual results and getting access to content is managed by `IDfResultObjectManager`

External sources attribute mapping:

External sources can be searched using the Federated Search Service option (FS2). These sources are integrated using FS2 Adapter technology. Each source may expose attributes different from regular Documentum type attributes. To provide a consistent view, external sources attributes are mapped into Documentum types attributes. By default, each results from an external source is considered of type "dm_document". This default type can be configured in each Adapter definition.
However, the attributes from external sources that don't match the expected Documentum type are still returned in the results.
The following mapping is performed:

- "title" is mapped to "object_name".
- "author" is mapped to "authors".
- "date" is mapped to "r_modified_date".
- "size" is mapped to "r_full_content_size". The size format from FS2 is in kbytes, it is transformed into bytes.
- "body" is mapped to "summary".
- "keywords" is mapped to "keywords".
- Any attribute ending with the "_date" suffix is mapped to an attribute of type date with the same name.
- "format" is mapped to "a_content_type". The MIME type value is transformed into Documentum type (example: "text/plain" is transformed into "crtext").
- "rank" is mapped to attribute "rank" with type integer.
- Other attributes are mapped to attribute with the same name with type string.

Optional properties can also be sent in the query to FS2 Adapters using `DfApplicationContext`.

To access Java, Visual Basic and C++ DFC sample code, please visit the Documentum Developer Program.

- Related Packages
  Package
  Description
  com.documentum.fc.client
  com.documentum.fc.client.search.filter
  This package contains interfaces to provide search services filters.
  com.documentum.fc.client.acs
  Provides classes and interfaces, related to distributed content transfer.
  com.documentum.fc.client.aspect
  com.documentum.fc.client.content
  com.documentum.fc.client.fulltext
  com.documentum.fc.client.mq
- Class
  Description
  DfApplicationContext
  Using this class, the client application can pass information along with the query.
  DfConfigurationException
  This exception is thrown in case of a possible configuration issue of the ECIS adpaters when doing a search.
  DfExpressionFactory
  Factory to create search expressions
  DfExpressionVisitor
  Abstract visitor used to visit an IDfExpression.
  DfFacetDefinition
  This class define a facet to be computed by the search service.
  DfFacetDefinition.ORDER
  Define the order of the facet value in the returned facets.
  DfFacetFactory
  Factory to create facets and facet values.
  DfGenericQueryListener
  Empty implementation of IDfQueryListener.
  DfQueryFormatException
  This exception is thrown when format of a stored query cannot be recognized.
  DfQueryGenerationException
  This exception is thrown when unexpected condition is discovered during query generation process.
  DfResultContentException
  This exception is thrown during the retrieval of a result content.
  DfResultEntryFactory
  Factory to create IDfResultEntry.
  DfSearchException
  This exception is a base exception for the `com.documentum.fc.client.search` package.
  DfSearchLoginException
  This exception is thrown when credentials are invalid.
  DfUnreachableLocationException
  This exception is thrown when the target location is unreachable.
  IDfAttrExpression
  Defines a base interface for the attribute search expression.
  IDfExpression
  Defines a search expression.
  IDfExpressionScope
  Defines a specific expression within a searched source.
  IDfExpressionSet
  Defines a set of search expressions.
  IDfFacet
  Represents a facet that has been computed by the Indexer.
  IDfFacetValue
  Represents a facet value.
  IDfFullTextExpression
  Defines a full-text expression for the search expression tree.
  IDfLocationQueryScope
  Defines a specific location within a searched source.
  IDfMltExpression
  Defines a more-like-this expression for the search expression tree with the given object id.
  IDfModifiableFacet
  A modifiable facet.
  IDfModifiableFacetValue
  A modifiable facet value.
  IDfModifiableResultEntry
  Represents a single result entry from a query execution and defines the methods necessary to modify and manipulate it.
  IDfModifiableResultsSet
  Represents a list of results and defines the methods necessary to modify and manipulate it.
  IDfOrderConstraint
  Interface used to express a sorting constraint on query results.
  IDfPartitionScope
  Defines a specific partition within a searched source.
  IDfPassThroughQuery
  Provides a container for passing a query string directly to the search source.
  IDfPerceptualRaterConfig
  Configures criteria factors for the IPR algorithm (Incremental Perceptual Ranking).
  IDfQueryBuilder
  This is a primary interface for building a query that can be executed against sources of different type.
  IDfQueryDefinition
  This is a base interface for the query that can be executed by the `IDfQueryProcessor`.
  IDfQueryEvent
  Provides status information about the execution of a query.
  IDfQueryListener
  Has to be implemented by an IDfQueryProcessor client to be asynchronously notified of new results and events during the query execution.
  IDfQueryManager
  Provides factory methods for query and interfaces for persistent query management.
  IDfQueryProcessor
  Manages the execution of a query accross multiple sources.
  IDfQueryScope
  This is a base interface for the query scope.
  IDfQueryStatus
  Represents the status of a search execution at a given point in time.
  IDfRelativeDateExpression
  Defines an expression on a date that is relative to the actual date when the query is executed.
  IDfResultContent
  Represents the actual content corresponding to a result.
  IDfResultEntry
  Represents a single result entry from a query execution.
  IDfResultMetadataHighlightEntry
  Defines an interface for the metadata highlight in search results.
  IDfResultObjectManager
  Manages result content access.
  IDfResultRater
  Rates results depending on their relevancy to a query definition.
  IDfResultRaterConfig
  Configures factors used by raters when computing results rating.
  IDfResultRaterFactory
  Creates ResultRater instances.
  IDfResultsManipulator
  Performs manipulation of results.
  IDfResultsSet
  Represents a list of results.
  IDfSearchMetadataManager
  Provides a facade to search metadata.
  IDfSearchOperation
  This interface defines the set of operations available for a search
  IDfSearchResults
  Represents the search results.
  IDfSearchService
  This interface is the factory for search objects.
  IDfSearchSource
  Represents a source for executing a query.
  IDfSearchSourceContainer
  Base interface for the classes that manage a list of selected sources.
  IDfSearchSourceMap
  Provides a facade to search source discovery.
  IDfSearchStoreService
  Provides access to services for search storage.
  IDfSearchTypeAssistant
  Provides a facade to search metadata for a given value.
  IDfSimpleAttrExpression
  Defines a simple search expression on an attribute.
  IDfSmartList
  An IDfSmartList is the BOF object representing a saved search.
  IDfSmartListDefinition
  Defines a smart list.
  IDfSourceStatus
  Represents the status of a query for a specific source.
  IDfValueListAttrExpression
  Defines a search expression that requires the attribute value to be included in a list of values.
  IDfValueRangeAttrExpression
  Defines a search expression that requires the attribute value to be greater than a minimum value and less than a maximum value (or equal).
  IExtendedObjectMappingDefinition
  Deprecated.
  The preferred way is now to deploy the full-text mapping file directly in the Docbase in folder /System/Search/EOS
  PositionalOperator
  This operator can be set on a IDfExpressionSet object.