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


IBM Tivoli Identity Manager 4.6
© Copyright International Business Machines Corporation 2005. All rights reserved. US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.