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.Object[]	getAdditionalMethodParams() Returns the additional parameters accepted by backend.
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	setAdditionalMethodParams(java.lang.Object[] additionalParams) Sets the additional parameters accepted by backend.
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. Refer to setCatgeory(String category) for a list of supported category.

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 that defines the base of the search. At least one (1) element and at most three (3) are expected:

• The first element of compoundDN is required and must contain the tenant's DistinguishedName.
• The second element of compoundDN is optional and if specified, it must contain organization's DistinguishedName.
• The third element of compoundDN is optional and if specified, it must contain parent's DistinguishedName. For the ManagableCategoryConstant.ACCOUNT object profile category, Parent's DistinguishedName is the DistinguishedName of the account's Service.

An element cannot be skipped. For example, you can not pass the parent DN without passing the organization DN. For ObjectProfileCategoryConstant.ORG and ObjectProfileCategoryConstant.SYSTEM_USER object profile categories, the CompoundDN should contain only one DistinguishedName identifying the tenant to use as the base of the search.

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
ObjectProfileCategory.ACCOUNT	Accounts
ObjectProfileCategory.ADOPTION_POLICY	AdoptionPolicy
ObjectProfileCategory.BPPERSON	BP Persons
ObjectProfileCategory.BPUNIT	Business Partner Organizations
ObjectProfileCategory.CONTAINER	OrganizationalContainer
ObjectProfileCategory.CUSTOM_PROCESS	Custom Processes or Workflows
ObjectProfileCategory.DYNAMIC_ROLE	Dynamic Roles
ObjectProfileCategory.HOST_SELECTION_POLICY	Host Selection Policies
ObjectProfileCategory.IDENTITY_POLICY	Identity Policies
ObjectProfileCategory.LOCATION	Business Units
ObjectProfileCategory.ORG	Organizations
ObjectProfileCategory.ORGUNIT	Business Units or Organizational Units
ObjectProfileCategory.PASSWORD_POLICY	Password Policies
ObjectProfileCategory.PERSON	Persons or People
ObjectProfileCategory.PROVISIONING_POLICY	Provisioning Policies
ObjectProfileCategory.RECERTIFICATION_POLICY	Recertification Policies
ObjectProfileCategory.ROLE	Roles
ObjectProfileCategory.SECURITY_DOMAIN	Admin Domains
ObjectProfileCategory.SEPARATION_OF_DUTY_POLICY	Separation of Duties Policies
ObjectProfileCategory.SERVICE	Services
ObjectProfileCategory.SYSTEM_ROLE	System Roles
ObjectProfileCategory.SYSTEM_USER	System Users
ObjectProfileCategory.TENANT	Tenants
ObjectProfileCategory.GROUP	Service Group
ObjectProfileCategory.ACCOUNT_TEMPLATE	Account Template
ObjectProfileCategory.CREDENTIAL	Credential
ObjectProfileCategory.CREDENTIAL_POOL	Credential Pool
ObjectProfileCategory.CREDENTIAL_LEASE	Credential Lease
ObjectProfileCategory.SHARED_ACCESS_POLICY	Shared Access Policy

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.

setAdditionalMethodParams

public void setAdditionalMethodParams(java.lang.Object[] additionalParams)

Sets the additional parameters accepted by backend.

Parameters:

additionalParams - is a list of objects accepted by backend

getAdditionalMethodParams

public java.lang.Object[] getAdditionalMethodParams()

Returns the additional parameters accepted by backend.

Returns:

Object[] a list of objects accepted by backend.

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