oracle.search.query.qta
Interface QueryTimeFilter

public interface QueryTimeFilter

An interface to filter search results and other access to document information at query time. If an object implementing this interface has been assigned to a source, any search results or other retrieval of documents belonging to the source will be passed through this filter before being presented to the end user.

The implementation of QueryTimeFilter must not rely on the pruneSource method to secure access to documents or folders. The pruneSource method is strictly an optimization feature. There is no guarantee that it will ever be invoked for any particular search request or document access. The filterDocuments and filterBrowseFolders methods must be implemented to provide full security in the absence of pruning.

Thread-safety: Classes that implement the QueryTimeFilter interface should be designed to persist for the lifetime of a running Oracle Secure Enterprise Search query application. A single instance of QueryTimeFilter will generally handle multiple concurrent requests from different search end users. Therefore, the filterDocuments, pruneSource, filterBrowseFolders, and getCurrentUserName methods must be thread safe.

See Also:

RequestInfo, DocumentInfo, FolderInfo

Field Summary

static int	FULL_AUTH Result value indicating that the user is authorized to view the corresponding document, folder, or source.
static int	NO_AUTH Result value indicating that the user is not authorized to view the corresponding document, folder, or source.
static int	NO_PRUNE Result value indicating that source-level authorization cannot be determined for this user.

Method Summary

void	close() Closes this QueryTimeFilter object and frees up any resources.
int[]	filterBrowseFolders(RequestInfo req, FolderInfo[] fldrs) Filters one or more folders for the Browse pages.
int[]	filterDocuments(RequestInfo req, DocumentInfo[] docs) Filters one or more documents for a search query request.
java.lang.String	getCurrentUserName(RequestInfo req) Returns the user name of the current user from the request information object.
int	pruneSource(RequestInfo req) Prunes the entire source from the query results, if possible.

Field Detail

NO_AUTH

public static final int NO_AUTH

Result value indicating that the user is not authorized to view the corresponding document, folder, or source.

See Also:

Constant Field Values

FULL_AUTH

public static final int FULL_AUTH

Result value indicating that the user is authorized to view the corresponding document, folder, or source.

See Also:

Constant Field Values

NO_PRUNE

public static final int NO_PRUNE

Result value indicating that source-level authorization cannot be determined for this user. Determination will fall back to document or folder-level filtering.

See Also:

Constant Field Values

Method Detail

filterDocuments

public int[] filterDocuments(RequestInfo req,
                             DocumentInfo[] docs)
                      throws QueryTimeFilterException

Filters one or more documents for a search query request. Based on the values returned by this method, all, some, or none of the documents from the source protected by this QueryTimeFilter may be filtered from the search results returned to the user.

Parameters:

req - the request information. Generally includes information to identify the current search user.

docs - array of documents to be processed

Returns:

an array of integer values. Array size should match size of the input docs argument. Each integer value must be either NO_AUTH if the corresponding document in the docs array is to be filtered out or FULL_AUTH if the corresponding document is to be included in the search results.

Throws:

QueryTimeFilterException - if an error occurs. This will be logged in the error log and all documents passed in to this method will be filtered out.

pruneSource

public int pruneSource(RequestInfo req)
                throws QueryTimeFilterException

Prunes the entire source from the query results, if possible. Otherwise, indicates that either no pruning should occur or that the entire source should be fully authorized for the current search user.

This method may be called in situations where there are a large number of documents or folders to be filtered. Authorizing or unauthorizing the entire source for a given user could provide a large performance gain over filtering each document individually.

The implementation of QueryTimeFilter must not rely on this method to secure access to documents or folders. This method is strictly an optimization feature. There is no guarantee that this will ever be invoked for any particular search request or document access. For example, when performing authorization for a single document, Oracle Secure Enterprise Search may call the filterDocuments method directly without invoking this method at all. Therefore, the filterDocuments and filterBrowseFolders methods must be implemented to provide full security in the absence of pruning.

Note: The minimal behavior for this method is to return NO_PRUNE. In this case, document or folder-level filtering will be utilized.

Parameters:

req - the request information. Generally includes information to identify the current search user.

Returns:

NO_AUTH if the source can be pruned, FULL_AUTH if the entire source can be authorized for the current search user, or NO_PRUNE if source-level authorization cannot be determined

Throws:

QueryTimeFilterException - if an error occurs. This will be logged in the error log and all documents from this source will be pruned from the result. Equivalent to returning NO_AUTH.

filterBrowseFolders

public int[] filterBrowseFolders(RequestInfo req,
                                 FolderInfo[] fldrs)
                          throws QueryTimeFilterException

Filters one or more folders for the Browse pages. Based on the values returned by this method, all, some, or none of the folders from the source protected by this QueryTimeFilter may be removed from the Browse page returned to the current search user.

This method is strictly used to control folder access in the Browse pages. If a folder is authorized by this method, the folder name will be displayed in the Browse application. The list of documents displayed within a folder is still filtered by the filterDocuments method.

If a folder is filtered out by this method, the folder name will not be displayed in the Browse pages for the current user. In addition, the Browse page that lists the documents within the unauthorized folder will not be available to the current user.

Limitations:

1. This method does not implicitly restrict access to subfolders. For example, if folder /Miscellaneous/www.company.com/private is filtered out for a search user, it is still possible for that user to view any subfolder, such as /Miscellaneous/www.company.com/private/a/b, if that subfolder is not also explicitly filtered out by this method. This would be possible if the user followed a bookmark or outside link directly to the authorized subfolder in the Browse application.
2. This method does not affect functionality outside of the Browse application. This is not a generic folder pruning method. Search queries and document retrieval outside of the Browse application are only affected by the filterDocuments and pruneSource methods.

Parameters:

req - the request information. Generally includes information to identify the current search user.

fldrs - array of folders to be processed

Returns:

an array of integer values. Array size should match size of the input fldrs argument. Each integer value must be either NO_AUTH if the corresponding folder in the fldrs array is to be hidden in the Browse pages or FULL_AUTH if the corresponding folder is to be accessible in the Browse pages.

Throws:

QueryTimeFilterException - if an error occurs. This will be logged in the error log and all folders passed in to this method will be removed from the Browse page returned to the current search user.

getCurrentUserName

public java.lang.String getCurrentUserName(RequestInfo req)
                                    throws QueryTimeFilterException

Returns the user name of the current user from the request information object. This user name is used for log messages to denote which user's documents were filtered.

For performance reasons, the implementation of this method should not need a network round trip to resolve the user name. Rather, it should be able to extract the user name directly from the request object.

Parameters:

req - the request information. Generally includes information to identify the current search user.

Returns:

the user name obtained from the request object argument

Throws:

QueryTimeFilterException - if an error occurs. This will be logged in the error log and otherwise not reported to the end user. Any documents or folders currently being filtered will be filtered out.

close

public void close()
           throws QueryTimeFilterException

Closes this QueryTimeFilter object and frees up any resources.

Note: This method may not be called if the Oracle Secure Enterprise Search query application does not shut down normally.

Throws:

QueryTimeFilterException - if any error occurs. This will be logged in the error log and otherwise not reported to the end user.