Skip navigation links

oracle.search.sdk.security
Interface ResultFilterPlugin

public interface ResultFilterPlugin

An interface to filter search results and other access to document information at query time. An AuthorizationManager provides a ResultFilterPlugin by implementing the getResultFilterPlugin method and returning true from isResultFilterAvailable. If an AuthorizationManager assigned to a source does provide a ResultFilterPlugin, then 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.

This interface does not directly take in any initialization parameters. However, as the AuthorizationManager acts as a factory for ResultFilterPlugins, is is responsible for constructing these objects and can therefore pass in parameters provided to its init method.

The implementation of ResultFilterPlugin 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 ResultFilterPlugin interface should be designed to persist for the lifetime of a running Oracle Secure Enterprise Search query application. A single instance of ResultFilterPlugin 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:

AuthorizationManager, RequestInfo, DocumentInfo, FolderInfo

Field Summary

static int	DENY Decision value indicating that the user is not authorized to view the corresponding document, folder, or source.
static int	FULL_AUTH Deprecated. As of release 10.1.8, replaced by ResultFilterPlugin.PERMIT
static int	INDETERMINATE Decision value indicating that source-level authorization cannot be determined for this user.
static int	NO_AUTH Deprecated. As of release 10.1.8, replaced by ResultFilterPlugin.DENY
static int	NO_PRUNE Deprecated. As of release 10.1.8, replaced by ResultFilterPlugin.INDETERMINATE
static int	PERMIT Decision value indicating that the user is authorized to view the corresponding document, folder, or source.

Method Summary

void	close() Closes this ResultFilterPlugin 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.
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

PERMIT

static final int PERMIT

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

See Also:

Constant Field Values

DENY

static final int DENY

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

See Also:

Constant Field Values

INDETERMINATE

static final int INDETERMINATE

Decision value indicating that source-level authorization cannot be determined for this user. Determination will fall back to document or folder-level filtering. This value is only used as a return value for the pruneSource method.

See Also:

Constant Field Values

NO_AUTH

static final int NO_AUTH

Deprecated. As of release 10.1.8, replaced by ResultFilterPlugin.DENY

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

See Also:

Constant Field Values

FULL_AUTH

static final int FULL_AUTH

Deprecated. As of release 10.1.8, replaced by ResultFilterPlugin.PERMIT

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

See Also:

Constant Field Values

NO_PRUNE

static final int NO_PRUNE

Deprecated. As of release 10.1.8, replaced by ResultFilterPlugin.INDETERMINATE

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

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

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 ResultFilterPlugin 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 DENY if the corresponding document in the docs array is to be filtered out or PERMIT if the corresponding document is to be included in the search results.

Throws:

PluginException - 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

int pruneSource(RequestInfo req)
                throws PluginException

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 ResultFilterPlugin 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 INDETERMINATE. 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:

DENY if the source can be pruned, PERMIT if the entire source can be authorized for the current search user, or INDETERMINATE if source-level authorization cannot be determined

Throws:

PluginException - 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 DENY.

filterBrowseFolders

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

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 ResultFilterPlugin 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 DENY if the corresponding folder in the fldrs array is to be hidden in the Browse pages or PERMIT if the corresponding folder is to be accessible in the Browse pages.

Throws:

PluginException - 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

String getCurrentUserName(RequestInfo req)
                          throws PluginException

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:

PluginException - 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

void close()
           throws PluginException

Closes this ResultFilterPlugin 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:

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

Skip navigation links