com.filenet.api.query

Class SearchScope

java.lang.Object

com.filenet.api.query.SearchScope

public final class SearchScope
extends java.lang.Object

Determines which repository or repositories are to be searched, and supplies methods to execute searches for properties, objects, and class metadata (class descriptions).

When multiple repositories are to be searched, use the SearchScope(ObjectStore[], MergeMode) constructor to specify whether the scope is the union or intersection of the object stores.

See Also:

MergeMode, SearchSQL, PropertyFilter, StoredSearch

Constructor Summary

Constructors

Constructor and Description
SearchScope(ObjectStore objectStore) Use this when the scope is a single object store.
SearchScope(ObjectStore[] objectStores, MergeMode mergeMode) Use this when the scope is multiple object stores.

Method Summary

Methods

Modifier and Type	Method and Description
IndependentObjectSet	fetchObjects(SearchSQL searchSQL, java.lang.Integer pageSize, PropertyFilter filter, java.lang.Boolean continuable) Retrieves IndependentObject objects from the repository or repositories specified for this instance.
IndependentObjectSet	fetchObjects(StoredSearch storedSearch, java.lang.String searchClauseFromClass, SearchTemplateParameters templateData, java.lang.Integer pageSize, PropertyFilter filter, java.lang.Boolean continuable) Retrieves IndependentObject objects from the repository or repositories specified for this instance based on a query generated from the XML for a StoredSearch instance.
RepositoryRowSet	fetchRows(SearchSQL searchSQL, java.lang.Integer pageSize, PropertyFilter filter, java.lang.Boolean continuable) Retrieves rows of properties (Properties objects) from the repository or repositories specified for this instance.
RepositoryRowSet	fetchRows(StoredSearch storedSearch, java.lang.String searchClauseFromClass, SearchTemplateParameters templateData, java.lang.Integer pageSize, PropertyFilter filter, java.lang.Boolean continuable) Retrieves rows of properties (Properties objects) from the repository or repositories specified for this instance based on a query generated from the XML for a StoredSearch instance.
ClassDescriptionSet	fetchSearchableClassDescriptions(java.lang.String[] classNames, PropertyFilter filter) Retrieves ClassDescription objects from the repository or repositories specified for this instance.
MergeMode	getMergeMode() Returns the merge mode used for this instance.
ObjectStore[]	getObjectStores() Returns the repositories used as the scope for this instance.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SearchScope

public SearchScope(ObjectStore objectStore)

Use this when the scope is a single object store.

Parameters:

objectStore - An ObjectStore instance for the repository to be searched.

SearchScope

public SearchScope(ObjectStore[] objectStores,
           MergeMode mergeMode)

Use this when the scope is multiple object stores. The MergeMode object specifies whether to use the union or intersection of the object stores.

Parameters:

objectStores - An array of ObjectStore instances for the repositories to be searched.

mergeMode - A MergeMode instance containing the mode (union or intersection) to use.

Method Detail

fetchRows

public RepositoryRowSet fetchRows(SearchSQL searchSQL,
                         java.lang.Integer pageSize,
                         PropertyFilter filter,
                         java.lang.Boolean continuable)

Retrieves rows of properties (Properties objects) from the repository or repositories specified for this instance.

The following property settings can affect this method:

• ObjectStore.DefaultQueryTimeLimit
• ObjectStore.MaxQueryTimeLimit
• ObjectStore.QueryDatabaseTimeout
• ServerCacheCofiguration.QueryPageMaxSize
• ServerCacheCofiguration.QueryPageDefaultSize
• ServerCacheCofiguration.NonPagedQueryMaxSize
• ServerCacheConfiguration.QueryCountDefaultSize
• ServerCacheConfiguration.QueryCountMaxSize

You can optionally include a filter to control which properties to return with the object. If you pass in null for the filter parameter, this method returns values for all non-object properties and returns placeholders for all object-valued properties. For more information, see the description of the filter parameter.

Parameters:

searchSQL - A SearchSQL instance containing the SQL statement to use for the search.

pageSize - An integer indicating the maximum number of Properties objects per page to retrieve. This can be null. When unspecified, the default page size (ServerCacheCofiguration.QueryPageDefaultSize) is used.

Note: If the continuable parameter is false or null, this pageSize value is ignored.

The number you specify here determines what constitutes a page of query result data. This value, in conjunction with the (Boolean) value you specify for the continuable parameter, can impact retrieval performance.

filter - A PropertyFilter object that represents information for controlling which property values (and with what level of detail and recursion) to return. If null, this method returns values for all non-object properties and returns placeholders for all object-valued properties (PropertyEngineObject properties with a state of PropertyState.UNEVALUATED or PropertyState.REFERENCE); any subsequent attempts to access an object-valued property will cause an automatic round-trip to the server to fetch its value.

The selection list in the searchSQL parameter determines which top-level properties are returned. The property filter specified here determines the subproperties: the properties returned for the applicable top-level properties. For example, if a top-level property specified in the selection list (searchSQL parameter) is of type Object, the filter parameter will determine which properties are returned in that object.

continuable - A Boolean value. If false or null, the query is not paged, the pageSize parameter and the default page size in ServerCacheCofiguration.QueryPageDefaultSize are ignored, and the query will return a number of rows limited by the following values:

• The "TOP" value (if specified) in the selection list.
• The value of ServerCacheCofiguration.NonPagedQueryMaxSize.

If this continuable value is true, the query can be continued. In this case, when the end of the first page is reached, a request for the next page of Properties objects is issued. Page requests iterate until all of the Properties objects satisfying the query are retrieved.

Queries using continuation use ORDER BY in their implementation. If an ORDER BY clause is not specified in the SQL statement (the searchSQL parameter), an ORDER BY Id clause is used. If an ORDER BY clause is specified in the SQL statement, but does not contain the Id property, the Id property (having a unique value) is appended to the end of the ORDER BY clause. You should consider to what extent adding the Id property to the ORDER BY clause increases resource consumption for your application. Do not use a continuable query if it would cause a severe performance degradation.

Returns:

A RepositoryRowSet collection object containing RepositoryRow objects for each row of properties retrieved. All properties returned will have the names as specified in the SQL statement used for the query. Any properties that are not defined in a particular repository, will be returned with null values.

When the properties are retrieved from multiple repositories, the returned properties can be different than these same properties returned by other methods. This is because the same properties can exist on multiple repositories, yet have different values on each. When such properties are returned by a query across repositories, the property values are aggregated.

See Also:

SQL Syntax Reference

fetchObjects

public IndependentObjectSet fetchObjects(SearchSQL searchSQL,
                                java.lang.Integer pageSize,
                                PropertyFilter filter,
                                java.lang.Boolean continuable)

Retrieves IndependentObject objects from the repository or repositories specified for this instance.

The following property settings can affect this method:

• ObjectStore.DefaultQueryTimeLimit
• ObjectStore.MaxQueryTimeLimit
• ObjectStore.QueryDatabaseTimeout
• ServerCacheCofiguration.QueryPageMaxSize
• ServerCacheCofiguration.QueryPageDefaultSize
• ServerCacheCofiguration.NonPagedQueryMaxSize
• ServerCacheConfiguration.QueryCountDefaultSize
• ServerCacheConfiguration.QueryCountMaxSize

Parameters:

searchSQL - A SearchSQL instance containing the SQL statement to use for the search.

pageSize - An integer indicating the maximum number of objects per page to retrieve. This can be null. When unspecified, the default page size (ServerCacheCofiguration.QueryPageDefaultSize) is used.

Note: If the continuable parameter is false or null, this pageSize value is ignored.

The number you specify here determines what constitutes a page of query result data. This value, in conjunction with the (Boolean) value you specify for the continuable parameter, can impact retrieval performance.

filter - A PropertyFilter object that represents information for controlling which property values (and with what level of detail and recursion) to return. If null, this method returns values for all non-object properties and returns placeholders for all object-valued properties (PropertyEngineObject properties with a state of PropertyState.UNEVALUATED or PropertyState.REFERENCE); any subsequent attempts to access an object-valued property will cause an automatic round-trip to the server to fetch its value.

The selection list in the searchSQL parameter determines which top-level properties are returned. The property filter specified here determines the subproperties: the properties returned for the applicable top-level properties. For example, if a top-level property specified in the selection list (searchSQL parameter) is of type Object, the filter parameter will determine which properties are returned in that object.

continuable - A Boolean value. If false or null, the query is not paged, the pageSize parameter and the default page size in ServerCacheCofiguration.QueryPageDefaultSize are ignored, and the query will return a number of objects limited by the following values:

• The "TOP" value (if specified) in the selection list.
• The value of ServerCacheCofiguration.NonPagedQueryMaxSize.

If this continuable value is true, the query can be continued. In this case, when the end of the first page is reached, a request for the next page of EngineObject objects is issued. Page requests iterate until all of the EngineObject objects satisfying the query are retrieved.

Queries using continuation use ORDER BY in their implementation. If an ORDER BY clause is not specified in the SQL statement (the searchSQL parameter), an ORDER BY Id clause is used. If an ORDER BY clause is specified in the SQL statement, but does not contain the Id property, the Id property (having a unique value) is appended to the end of the ORDER BY clause. You should to what extent adding the Id property to the ORDER BY clause increases resource consumption for your application. Do not use a continuable query if it would cause a severe performance degradation.

Returns:

An IndependentObjectSet collection object containing the IndependentObject objects retrieved.

See Also:

SQL Syntax Reference

fetchRows

public RepositoryRowSet fetchRows(StoredSearch storedSearch,
                         java.lang.String searchClauseFromClass,
                         SearchTemplateParameters templateData,
                         java.lang.Integer pageSize,
                         PropertyFilter filter,
                         java.lang.Boolean continuable)

Retrieves rows of properties (Properties objects) from the repository or repositories specified for this instance based on a query generated from the XML for a StoredSearch instance.

The following property settings can affect this method:

• ObjectStore.DefaultQueryTimeLimit
• ObjectStore.MaxQueryTimeLimit
• ObjectStore.QueryDatabaseTimeout
• ServerCacheCofiguration.QueryPageMaxSize
• ServerCacheCofiguration.QueryPageDefaultSize
• ServerCacheCofiguration.NonPagedQueryMaxSize
• ServerCacheConfiguration.QueryCountDefaultSize
• ServerCacheConfiguration.QueryCountMaxSize

Parameters:

storedSearch - A StoredSearch instance containing the XML used to generate a query.

searchClauseFromClass - A String indicating the class for the FROM clause of the query. The supported values are document, folder or customobject.

templateData - A SearchTemplateParameters object. Refer to the SearchTemplateParameters documentation for a description of this parameter. This value may be null.

pageSize - An integer indicating the maximum number of objects per page to retrieve. This can be null. When unspecified, the default page size (ServerCacheCofiguration.QueryPageDefaultSize) is used.

Note: If the continuable parameter is false or null, this pageSize value is ignored.

The number you specify here determines what constitutes a page of query result data. This value, in conjunction with the (Boolean) value you specify for the continuable parameter, can impact retrieval performance.

filter - A PropertyFilter object that represents information for controlling which property values (and with what level of detail and recursion) to return. If null, this method returns values for all non-object properties and returns placeholders for all object-valued properties (PropertyEngineObject properties with a state of PropertyState.UNEVALUATED or PropertyState.REFERENCE); any subsequent attempts to access an object-valued property will cause an automatic round-trip to the server to fetch its value.

If a selection list is specified in either the StoredSearch XML passed in the storedSearch parameter or in the SearchTemplateParameters instance passed in the templateData parameter, that selection list determines which top-level properties are returned. The property filter specified here determines the subproperties: the properties returned for the applicable top-level properties. For example, if a top-level property specified in the selection list is of type Object, the filter parameter will determine which properties are returned in that object.

continuable - A Boolean value. If false or null, the query is not paged, the pageSize parameter and the default page size in ServerCacheCofiguration.QueryPageDefaultSize are ignored, and the query will return a number of objects limited by the following values:

• The "TOP" value (if specified) in the selection list.
• The value of ServerCacheCofiguration.NonPagedQueryMaxSize.

If this continuable value is true, the query can be continued. In this case, when the end of the first page is reached, a request for the next page of EngineObject objects is issued. Page requests iterate until all of the EngineObject objects satisfying the query are retrieved.

Queries using continuation use the sort order specified in either the StoredSearch XML passed in the storedSearch parameter or in the SearchTemplateParameters instance passed in the templateData parameter. If the sort order is not specified, the results are ordered by Id. If the sort order is specified, but does not contain the Id property, the Id property (having a unique value) is appended to the end of the sort order clause. You should consider to what extent adding the Id property to the sort order clause increases resource consumption for your application. Do not use a continuable query if it would cause a severe performance degradation.

Returns:

A RepositoryRowSet collection object containing RepositoryRow objects for each row of properties retrieved. All properties returned will have the names as specified in the SQL statement used for the query. Any properties that are not defined in a particular repository, will be returned with null values.

When the properties are retrieved from multiple repositories, the returned properties can be different than these same properties returned by other methods. This is because the same properties can exist on multiple repositories, yet have different values on each. When such properties are returned by a query across repositories, the property values are aggregated.

See Also:

SQL Syntax Reference

fetchObjects

public IndependentObjectSet fetchObjects(StoredSearch storedSearch,
                                java.lang.String searchClauseFromClass,
                                SearchTemplateParameters templateData,
                                java.lang.Integer pageSize,
                                PropertyFilter filter,
                                java.lang.Boolean continuable)

Retrieves IndependentObject objects from the repository or repositories specified for this instance based on a query generated from the XML for a StoredSearch instance.

The following property settings can affect this method:

• ObjectStore.DefaultQueryTimeLimit
• ObjectStore.MaxQueryTimeLimit
• ObjectStore.QueryDatabaseTimeout
• ServerCacheCofiguration.QueryPageMaxSize
• ServerCacheCofiguration.QueryPageDefaultSize
• ServerCacheCofiguration.NonPagedQueryMaxSize
• ServerCacheConfiguration.QueryCountDefaultSize
• ServerCacheConfiguration.QueryCountMaxSize

You can optionally include a filter to control which properties to return with the object. If you pass in null for the filter parameter, this method returns values for all non-object properties and returns placeholders for all object-valued properties. For more information, see the description of the filter parameter.

Parameters:

storedSearch - A StoredSearch instance containing the XML used to generate a query.

searchClauseFromClass - A String indicating the class for the FROM clause of the query. The supported values are document, folder or customobject.

templateData - A SearchTemplateParameters object. Refer to the SearchTemplateParameters documentation for a description of this parameter. This value may be null.

pageSize - An integer indicating the maximum number of objects per page to retrieve. This can be null. When unspecified, the default page size (ServerCacheCofiguration.QueryPageDefaultSize) is used.

Note: If the continuable parameter is false or null, this pageSize value is ignored.

The number you specify here determines what constitutes a page of query result data. This value, in conjunction with the (Boolean) value you specify for the continuable parameter, can impact retrieval performance.

filter - A PropertyFilter object that represents information for controlling which property values (and with what level of detail and recursion) to return. If null, this method returns values for all non-object properties and returns placeholders for all object-valued properties (PropertyEngineObject properties with a state of PropertyState.UNEVALUATED or PropertyState.REFERENCE); any subsequent attempts to access an object-valued property will cause an automatic round-trip to the server to fetch its value.

If a selection list is specified in either the StoredSearch XML passed in the storedSearch parameter or in the SearchTemplateParameters instance passed in the templateData parameter, that selection list determines which top-level properties are returned. The property filter specified here determines the subproperties: the properties returned for the applicable top-level properties. For example, if a top-level property specified in the selection list is of type Object, the filter parameter will determine which properties are returned in that object.

continuable - A Boolean value. If false or null, the query is not paged, the pageSize parameter and the default page size in ServerCacheCofiguration.QueryPageDefaultSize are ignored, and the query will return a number of objects limited by the following values:

• The "TOP" value (if specified) in the selection list.
• The value of ServerCacheCofiguration.NonPagedQueryMaxSize.

If this continuable value is true, the query can be continued. In this case, when the end of the first page is reached, a request for the next page of EngineObject objects is issued. Page requests iterate until all of the EngineObject objects satisfying the query are retrieved.

Queries using continuation use the sort order specified in either the StoredSearch XML passed in the storedSearch parameter or in the SearchTemplateParameters instance passed in the templateData parameter. If the sort order is not specified, the results are ordered by Id. If the sort order is specified, but does not contain the Id property, the Id property (having a unique value) is appended to the end of the sort order clause. You should consider to what extent adding the Id property to the sort order clause increases resource consumption for your application. Do not use a continuable query if it would cause a severe performance degradation.

Returns:

An IndependentObjectSet collection object containing the IndependentObject objects retrieved.

See Also:

SQL Syntax Reference

fetchSearchableClassDescriptions

public ClassDescriptionSet fetchSearchableClassDescriptions(java.lang.String[] classNames,
                                                   PropertyFilter filter)

Retrieves ClassDescription objects from the repository or repositories specified for this instance.

You can optionally include a filter to control which properties to return with the object. If you pass in null for the filter parameter, this method returns values for all non-object properties and returns placeholders for all object-valued properties. For more information, see the description of the filter parameter.

Parameters:

classNames - A String array of the names of the classes to retrieve. The class names can be the symbolic name, the display name, or the object ID for the class (in String format).

filter - A PropertyFilter object that represents information for controlling which property values (and with what level of detail and recursion) to return. If null, this method returns values for all non-object properties and returns placeholders for all object-valued properties (PropertyEngineObject properties with a state of PropertyState.UNEVALUATED or PropertyState.REFERENCE); any subsequent attempts to access an object-valued property will cause an automatic round-trip to the server to fetch its value.

Returns:

A ClassDescriptionSet collection object containing ClassDescription objects for the metadata retrieved.

If the SearchScope instance references multiple repositories, properties that are not applicable to multiple repositories will not be present in the ClassDescription objects returned, nor in the PropertyDescription objects contained in these ClassDescription objects.

For the ClassDescription objects returned, these properties are:

• SuperclassDescription
• SuperclassPropertyCount
• ImmediateSubclassDescriptions
• NamePropertyIndex
• AllowsInstances
• PermissionDescriptions
• DefaultInstancePermissions

For the PropertyDescription objects contained in the ClassDescription objects, these properties are:

• IsSystemGenerated
• IsReadOnly
• IsHidden
• PropertyDefaultObject
• PropertySelectionsObject
• RequiredClass
• ReflectivePropertyId

getMergeMode

public MergeMode getMergeMode()

Returns the merge mode used for this instance. The merge mode defaults to UNION when unspecified.

Returns:

A MergeMode instance containing the mode (union or intersection) used.

getObjectStores

public ObjectStore[] getObjectStores()

Returns the repositories used as the scope for this instance.

Returns:

The array of ObjectStore instances for the repositories used as the search scope.