com.ibm.itim.apps.search
Class SearchMO

java.lang.Object
  |
  +--com.ibm.itim.apps.search.SearchMO

All Implemented Interfaces:

java.io.Serializable

public class SearchMO

extends java.lang.Object

implements java.io.Serializable

Provides a configurable query facility for DirectoryObject. Like other remoteable API classes, a SearchMO is constructed with a PlatformContext and an authenticated Subject. A SearchMO is configured, then executed to obtain a SearchResultsMO object which represents a result set and provides methods to traverse results page by page. The SearchMO controls search execution in a number of ways, such as through its string based filter (an RFC2254 ldap filter), its scope (ONELEVEL_SCOPE or SUBTREE_SCOPE), and its category. The SearchMO also defines the original sort order for a SearchResultsMO through its setSortOrder() - one of ASCENDING_SORT or DESCENDING_SORT, and setSortAttribute() methods. Taken together, the parameters that control search execution and define the contents of a SearchResultsMO are known as search criteria. Last, a SearchResultsMO returned by SearchMO.execute() always contains objects that are accessible to the Subject (to the SystemUser the Subject represents) consistent with permissions defined in system ACLs so that the SearchMO and the SearchResultsMO (the Search API) impose (but also guarantee) authorized access.

See Also:

Serialized Form

Field Summary

static int	ASCENDING_SORT Constant identifying a low to high sort order.
static int	DESCENDING_SORT Constant identifying a high to low sort order.
static int	ONELEVEL_SCOPE Constant identifying a single level search scope.
static int	SUBTREE_SCOPE Constant identifying a subtree level search scope.

Constructor Summary

SearchMO(PlatformContext platform, javax.security.auth.Subject subject)
Constructs a SearchMO with a platform context and a subject.

Method Summary

SearchResultsMO	execute() Executes the search using the configured parameters.
void	execute(SearchResultsMO resultsMO) Executes the search using the configured parameters.
java.lang.String[]	getAttributes() Returns the set of attributes that will be retrieved for every result returned.
java.lang.String	getCategory() Returns the ObjectProfileCategory for the search.
CompoundDN	getContext() Gets the logicalContext for the search.
java.lang.String	getFilter() Returns the Ldap filter for the search.
java.util.Locale	getLocale() Returns the SearchMO's Locale.
int	getMaxSize() Returns the maximum number of results to be returned from the search.
OrganizationalContainerMO	getOrgContext() Returns the context (base) for the search.
int	getPageLinks() Returns the number of pages to be pre-fetched.
int	getPageSize() Returns the pageSize property.
java.lang.String	getProfileName() Returns the ObjectProfile name for the search.
int	getScope() Returns the scope of the search.
java.lang.String	getSortAttribute() Returns the name of the attribute to sort by.
int	getSortOrder() Returns the sort order for the result set.
boolean	isPaging() Returns true if the result set should be paginated.
void	mapToSearchMO(com.ibm.itim.apps.ejb.search.SearchRequest searchRequest) Copies the parameters in the given SearchRequest into this object.
static com.ibm.itim.apps.ejb.search.SearchRequest	mapToSearchRequest(SearchMO searchMO) Copies the parameters in the given SearchMO into a new SearchRequest.
void	setAttributes(java.lang.String[] attributes) Sets the attributes to retrieve for each result returned.
void	setCategory(java.lang.String category) Sets the Object Profile Category for the search.
void	setContext(CompoundDN logicalContext) Sets the logicalContext for the search, or which node in the OrgChart to start searching from.
void	setContext(OrganizationalContainerMO containerMO) Sets the context (base) for the search, if set, takes precedence over setContext(CompoundDN logicalContext).
void	setFilter(java.lang.String filter) Sets the Ldap filter for the search.
void	setLocale(java.util.Locale locale) Sets the user's Locale.
void	setMaxSize(int max) Sets the maximum number of results to return from the search.
void	setPageLinks(int pageLinks) Sets the number of pages to be pre-fetched on one call to SearchResultsMO.getPage().
void	setPageSize(int pageSize) Sets the number of DirectoryObjects to return in SearchResultsMO.getPage().
void	setPaging(boolean toggle) Toggles pagination on/off for the request.
void	setProfileName(java.lang.String objProfileName) Sets the ObjectProfile name for the search.
void	setScope(int scope) Sets the scope of the search.
void	setSortAttribute(java.lang.String sortAttribute) Sets the name of the attribute to sort by.
void	setSortOrder(int sortOrder) Sets the sort order for the result set.
java.lang.String	toString() Overrides Object implementation.

Methods inherited from class java.lang.Object

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

Field Detail

ASCENDING_SORT

public static int ASCENDING_SORT

Constant identifying a low to high sort order.

DESCENDING_SORT

public static int DESCENDING_SORT

Constant identifying a high to low sort order.

ONELEVEL_SCOPE

public static int ONELEVEL_SCOPE

Constant identifying a single level search scope.

SUBTREE_SCOPE

public static int SUBTREE_SCOPE

Constant identifying a subtree level search scope.

Constructor Detail

SearchMO

public SearchMO(PlatformContext platform,
                javax.security.auth.Subject subject)

Constructs a SearchMO with a platform context and a subject.

Parameters:

platform - PlatformContext holding platform connection information.

subject - Subject representing the authenticated caller.

Method Detail

execute

public SearchResultsMO execute()
                        throws java.rmi.RemoteException,
                               ApplicationException

Executes the search using the configured parameters. Note that not all objects that meet the search criteria will be accessible by the client. Those objects will not placed in the result set and no AuthorizationException will be thrown.

Returns:

SearchResultsMO holding the results of the search.

Throws:

java.rmi.RemoteException - Thrown if unable to communicate with platform.

ApplicationException - Thrown if unable to execute the search. This is most likely caused by an invalid parameter in the SearchRequest.

execute

public void execute(SearchResultsMO resultsMO)
             throws java.rmi.RemoteException,
                    ApplicationException

Executes the search using the configured parameters. Note that not all objects that meet the search criteria will be accessible by the client. Those objects will not placed in the result set and no AuthorizationException will be thrown.

Parameters:

resultsMO - SearchResultsMO to hold the results of the search. Note, if the SearchResultsMO object was constructed using a different user context, that context will be changed to match the context of this object.

Throws:

java.rmi.RemoteException - Thrown if unable to communicate with platform.

ApplicationException - Thrown if unable to execute the search. This is most likely caused by an invalid parameter in the SearchRequest.

setContext

public void setContext(CompoundDN logicalContext)

Sets the logicalContext for the search, or which node in the OrgChart to start searching from.

Parameters:

logicalContext - a CompoundDN containing at least one element.

setContext

public void setContext(OrganizationalContainerMO containerMO)

Sets the context (base) for the search, if set, takes precedence over setContext(CompoundDN logicalContext). Useful in cases where an OrganizationalContainerMO is available to the application (client) executing the search.

Parameters:

containerMO - an OrganizationalContainerMO.

getOrgContext

public OrganizationalContainerMO getOrgContext()

Returns the context (base) for the search.

Returns:

containerMO an OrganizationalContainerMO, if any.

getContext

public CompoundDN getContext()

Gets the logicalContext for the search.

Returns:

The logicalContext of the search.

setLocale

public void setLocale(java.util.Locale locale)

Sets the user's Locale. Used in conjuction with setSortAttribute() to define the order of the resutls in the SearchResultsMO returned by execute().

Parameters:

locale - the user's Locale.

getLocale

public java.util.Locale getLocale()

Returns the SearchMO's Locale.

Returns:

locale the user's Locale.

setCategory

public void setCategory(java.lang.String category)

Sets the Object Profile Category for the search.

Parameters:

category - ObjectProfileCategory for the objects to search for.

May be one of:

Use String Constant	To search for
ManagableCategoryConstant.ACCOUNT	Accounts
ManagableCategoryConstant.BPPERSON	BP Persons
ObjectProfileCategoryConstant.BPUNIT	Business Partner Organizations
ObjectProfileCategoryConstant.CUSTOM_PROCESS	Custom Processes or Workflows
ObjectProfileCategoryConstant.DYNAMIC_ROLE	Dynamic Roles
ObjectProfileCategoryConstant.HOST_SELECTION_POLICY	Host Selection Policies
ObjectProfileCategoryConstant.IDENTITY_POLICY	Identity Policies
ObjectProfileCategoryConstant.LOCATION	Business Units
ObjectProfileCategoryConstant.ORG	Organizations
ObjectProfileCategoryConstant.ORGUNIT	Business Units or Organizational Units
ObjectProfileCategoryConstant.PASSWORD_POLICY	Password Policies
ManagableCategoryConstant.PERSON	Persons or People
ObjectProfileCategoryConstant.PROVISIONING_POLICY	Provisioning Policies
ObjectProfileCategoryConstant.ROLE	Roles
ObjectProfileCategoryConstant.SECURITY_DOMAIN	Admin Domains
ObjectProfileCategoryConstant.SERVICE	Services
ObjectProfileCategoryConstant.SYSTEM_ROLE	System Roles
ObjectProfileCategoryConstant.SYSTEM_USER	System Users
ObjectProfileCategoryConstant.TENANT	Tenants

getCategory

public java.lang.String getCategory()

Returns the ObjectProfileCategory for the search.

Returns:

category ObjectProfileCategory for the objects to search for.

setFilter

public void setFilter(java.lang.String filter)

Sets the Ldap filter for the search. The filter must be in the format specified in RFC2254.

Parameters:

filter - Ldap filter in RFC2254 format for the search.

getFilter

public java.lang.String getFilter()

Returns the Ldap filter for the search.

Returns:

filter Ldap filter for the search.

setProfileName

public void setProfileName(java.lang.String objProfileName)

Sets the ObjectProfile name for the search. Optional parameter for more focused searches where the ObjectProfile name is known. From a performance standpoint, it's important for a SearchMO client to take into account that in the absence of a specific ObjectProfile name, SearchMO.execute() returns a SearchResultsMO that contains all the objects in the category specified by SearchMO.setCategory() - a very broad and potentially long running search in some cases.

Parameters:

objProfileName - ObjectProfile name for the objects to search for.

getProfileName

public java.lang.String getProfileName()

Returns the ObjectProfile name for the search.

Returns:

objProfileName ObjectProfile name for the objects to search for.

setSortAttribute

public void setSortAttribute(java.lang.String sortAttribute)

Sets the name of the attribute to sort by.

Parameters:

sortAttribute - The name of the attribute to sort by.

getSortAttribute

public java.lang.String getSortAttribute()

Returns the name of the attribute to sort by.

Returns:

sortAttribute name of the attribute to sort by; null if it is not set.

setScope

public void setScope(int scope)

Sets the scope of the search.

Parameters:

scope - int representing scope. Value may be ONELEVEL_SCOPE or SUBTREE_SCOPE.

getScope

public int getScope()

Returns the scope of the search.

Returns:

int representing scope. Value may be ONELEVEL_SCOPE or SUBTREE_SCOPE.

setMaxSize

public void setMaxSize(int max)

Sets the maximum number of results to return from the search.

Parameters:

max - Maximum number of results.

getMaxSize

public int getMaxSize()

Returns the maximum number of results to be returned from the search.

Returns:

Maximum number of results.

setPaging

public void setPaging(boolean toggle)

Toggles pagination on/off for the request. Default is true. Used to override the default and obtain an entire result set with this request.

Parameters:

toggle - true/false option to paginate the result set.

isPaging

public boolean isPaging()

Returns true if the result set should be paginated.

Returns:

true if the result set should be paginated.

getSortOrder

public int getSortOrder()

Returns the sort order for the result set. One of: ASCENDING_SORT or DESCENDING_SORT

Returns:

result set sort order.

setSortOrder

public void setSortOrder(int sortOrder)

Sets the sort order for the result set. Must be one of: ASCENDING_SORT or DESCENDING_SORT

Parameters:

sortOrder - result set sort order.

setAttributes

public void setAttributes(java.lang.String[] attributes)

Sets the attributes to retrieve for each result returned. In general, specifying attributes in a SearchMO is more efficient than not because it reduces search time and reduces the overall size of the objects in the SearchResultsMO.

Parameters:

attributes - String[] holding the names of attributes to return with each result. Passing null will be interpreted as all attributes should be returned.

getAttributes

public java.lang.String[] getAttributes()

Returns the set of attributes that will be retrieved for every result returned.

Returns:

String[] array holding the names of attributes to be returned, null if all will be returned.

setPageSize

public void setPageSize(int pageSize)

Sets the number of DirectoryObjects to return in SearchResultsMO.getPage().

Parameters:

pageSize - the number of DirectoryObjects to return in SearchResultsMO.getPage().

getPageSize

public int getPageSize()

Returns the pageSize property.

Returns:

int the number of DirectoryObjects to return in SearchResultsMO.getPage().

setPageLinks

public void setPageLinks(int pageLinks)

Sets the number of pages to be pre-fetched on one call to SearchResultsMO.getPage(). Pre-fetched pages are stored in an internal cache, and will be returned on subsequent calls to getPage(), thereby improving the performance of subsequent function calls at the cost of increased memory consumption. If SearchResultsMO.getPage() is used to retrieve large results , then it is recommended to set this property to 1, to optimize memory consumption.

Parameters:

pageLinks - the number of pages to be pre-fetched on invoking SearchResultsMO.getPage().

getPageLinks

public int getPageLinks()

Returns the number of pages to be pre-fetched.

Returns:

int the number of pages to be pre-fetched.

mapToSearchRequest

public static com.ibm.itim.apps.ejb.search.SearchRequest mapToSearchRequest(SearchMO searchMO)

Copies the parameters in the given SearchMO into a new SearchRequest.

Parameters:

searchMO - a SearchMO to map to a SearchRequest.

Returns:

a SearchRequest object.

mapToSearchMO

public void mapToSearchMO(com.ibm.itim.apps.ejb.search.SearchRequest searchRequest)

Copies the parameters in the given SearchRequest into this object.

Parameters:

searchRequest - a SearchRequest object holding parameters to copy into this SearchMO.

toString

public java.lang.String toString()

Overrides Object implementation.

Overrides:

toString in class java.lang.Object