com.ibm.itim.dataservices.model.domain
Class PersonSearch

java.lang.Object
  com.ibm.itim.dataservices.model.domain.PersonSearch

public class PersonSearch
extends java.lang.Object

Provides an interface for searching for people. This interface is supplied to clients so that they can search in a more direct manner without having to traverse data model relationships to retrieve people. It should be noted that, like all other classes in the com.ibm.itim.dataservices package and its sub-packages, this class is not remote able. It should be used from local customization code such as JavaScript extensions, but not from code deployed outside the platform. It should also be noted that, like all other search classes in the com.ibm.itim.dataservices package and its sub-packages, this search class does not check ACIs to filter out results. A remote able equivalent that performs ACI checking is available in the com.ibm.itim.apps.identity.PersonManager class.

See Also:

PersonEntity

Field Summary

static java.lang.String

NAME

Constructor Summary

PersonSearch()
Default constructor.

Method Summary

PersonEntity	lookup(DistinguishedName dn) Retrieves the person from the data store with the given distinguished name.
PersonEntity	lookup(DistinguishedName dn, boolean disableCache) Retrieves the person from the data store with the given distinguished name.
SearchResults	searchByAlias(CompoundDN searchContext, java.lang.String alias, SearchParameters params) Returns all people with the given alias.
SearchResults	searchByAlias(OrganizationalContainerEntity searchContext, java.lang.String alias, SearchParameters params) Returns all people with the given alias.
SearchResults	searchByAuthorizedRole(DistinguishedName roleDN, SearchParameters params) Returns all people who are members of a given role or members of a child role of the given role in the role hierarchy
SearchResults	searchByAuthorizedRoles(java.util.Collection<DistinguishedName> roleCol, SearchParameters params) Returns all people who are members of any one of the roles in the given collection or members of a child role of any of the roles in the given collection
SearchResults	searchByFilter(CompoundDN searchContext, SearchParameters params, java.lang.String filter, java.lang.String categoryName) Searches for people in a given category that meet the criteria defined within the given filter .
SearchResults	searchByFilter(CompoundDN searchContext, SearchParameters params, java.lang.String filter, java.lang.String categoryName, java.lang.Comparable clientSideFilter) Searches for people in a given category that meet the criteria defined within the given filter .
SearchResults	searchByFilter(CompoundDN searchContext, java.lang.String filter, SearchParameters params) Searches for people that meet the criteria defined within the given filter.
SearchResults	searchByFilter(CompoundDN searchContext, java.lang.String filter, SearchParameters params, java.lang.Comparable clientSideFilter) Searches for people that meet the criteria defined within the given filter.
SearchResults	searchByFilter(CompoundDN searchContext, java.lang.String profileName, java.lang.String filter, SearchParameters params) Searches for people that meet the criteria defined within the given filter.
SearchResults	searchByFilter(CompoundDN searchContext, java.lang.String profileName, java.lang.String filter, SearchParameters params, java.lang.Comparable clientSideFilter) Searches for people that meet the criteria defined within the given filter.
SearchResults	searchByFilter(OrganizationalContainerEntity searchContext, java.lang.String filter, SearchParameters params) Searches for people that meet the criteria defined within the given filter.
SearchResults	searchByFilter(OrganizationalContainerEntity searchContext, java.lang.String profileName, java.lang.String filter, SearchParameters params) Searches for people that meet the criteria defined within the given filter.
SearchResults	searchByName(CompoundDN searchContext, java.lang.String profileName, java.lang.String name) Searches for people for a given name.
SearchResults	searchByName(CompoundDN searchContext, java.lang.String profileName, java.lang.String name, SearchParameters params) Searches for people for a given name.
SearchResults	searchByProfile(CompoundDN searchContext, SearchParameters params, java.lang.String profileName, java.lang.String value) Searches for people in a given category that meet the criteria defined within the given filter .
SearchResults	searchByRole(DistinguishedName roleDN, SearchParameters params) Returns all people who are members of a given role.
PersonEntity	searchByURI(OrganizationalContainerEntity searchContext, java.lang.String uri) Find the person for a specific URI.

Methods inherited from class java.lang.Object

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

Field Detail

NAME

public static final java.lang.String NAME

See Also:

Constant Field Values

Constructor Detail

PersonSearch

public PersonSearch()

Default constructor.

Method Detail

lookup

public PersonEntity lookup(DistinguishedName dn,
                           boolean disableCache)
                    throws ModelCommunicationException,
                           ObjectNotFoundException

Retrieves the person from the data store with the given distinguished name.

Parameters:

dn - DistinguishedName of the person.

disableCache - Bypasses the cache

Returns:

PersonEntity with the corresponding distinguished name.

Throws:

ModelCommunicationException - Thrown if unable to communicate with the data store.

ObjectNotFoundException - Thrown if unable to locate the entity in the data store. This may be due to an invalid distinguished name, or the entity may have been removed by another client.

lookup

public PersonEntity lookup(DistinguishedName dn)
                    throws ModelCommunicationException,
                           ObjectNotFoundException

Retrieves the person from the data store with the given distinguished name.

Parameters:

dn - DistinguishedName of the person.

Returns:

PersonEntity with the corresponding distinguished name.

Throws:

ModelCommunicationException - Thrown if unable to communicate with the data store.

ObjectNotFoundException - Thrown if unable to locate the entity in the data store. This may be due to an invalid distinguished name, or the entity may have been removed by another client.

searchByFilter

public SearchResults searchByFilter(OrganizationalContainerEntity searchContext,
                                    java.lang.String filter,
                                    SearchParameters params)
                             throws ModelCommunicationException,
                                    ObjectNotFoundException

Searches for people that meet the criteria defined within the given filter. This search is performed as a raw search against the data store without any semantic mapping. People of all types will be returned.

Parameters:

searchContext - OrganizationalContainerEntity which is to be used as the base context to search from.

filter - Filter that defines the criteria for returned business units to meet. The filter must be in the format defined by RFC2254.

params - SearchParameters that provide additional context for how the search should be performed. If the search scope is ONELEVEL_SCOPE, the search is limited only to the people belong to the given parent (searchContext.last()). Otherwise, the whole organizational logical subtree will be searched.

Returns:

SearchResults holding PersonEntities for all people that meet the search criteria.

Throws:

ModelCommunicationException - Thrown if unable to communicate with the data store.

ObjectNotFoundException - Thrown if unable to locate the container specified in the searchContext. This may be due to the container being removed by another client.

searchByFilter

public SearchResults searchByFilter(CompoundDN searchContext,
                                    java.lang.String filter,
                                    SearchParameters params)
                             throws ModelCommunicationException,
                                    ObjectNotFoundException

Searches for people that meet the criteria defined within the given filter. This search is performed as a raw search against the data store without any semantic mapping. People of all types will be returned.

Parameters:

searchContext - CompoundDN that defines the base of the search. At least one (1) element and at most three (3) are expected:

• searchContext.elements[0] must contain the tenant DN
• searchContext.elements[1] may contain the organization DN
• searchContext.elements[2] may contain the parent DN (optional)

An element cannot be skipped. For example, you can not pass the parent DN without passing the organization DN.

filter - Filter that defines the criteria for returned people to meet. The filter must be in the format defined by RFC2254.

params - SearchParameters that provide additional context for how the search should be performed. If the search scope is ONELEVEL_SCOPE, the search is limited only to the people that belong to the given parent (searchContext.last()). Otherwise, the whole organizational logical subtree will be searched.

Returns:

SearchResults holding PersonEntities for all people that meet the search criteria.

Throws:

ModelCommunicationException - Thrown if unable to communicate with the data store.

ObjectNotFoundException - Thrown if unable to locate the container specified in the searchContext. This may be due to the container being removed by another client.

searchByFilter

public SearchResults searchByFilter(CompoundDN searchContext,
                                    java.lang.String filter,
                                    SearchParameters params,
                                    java.lang.Comparable clientSideFilter)
                             throws ModelCommunicationException,
                                    ObjectNotFoundException

Searches for people that meet the criteria defined within the given filter. This search is performed as a raw search against the data store without any semantic mapping. People of all types will be returned.

Parameters:

searchContext - CompoundDN that defines the base of the search. At least one (1) element and at most three (3) are expected:

• searchContext.elements[0] must contain the tenant DN
• searchContext.elements[1] may contain the organization DN
• searchContext.elements[2] may contain the parent DN (optional)

An element cannot be skipped. For example, you can not pass the parent DN without passing the organization DN.

filter - Filter that defines the criteria for returned people to meet. The filter must be in the format defined by RFC2254.

params - SearchParameters that provide additional context for how the search should be performed. If the search scope is ONELEVEL_SCOPE, the search is limited only to the people that belong to the given parent (searchContext.last()). Otherwise, the whole organizational logical subtree will be searched.

clientSideFilter - Object used to perform client-side filtering, or null if client-side filtering is not required.

Returns:

SearchResults holding PersonEntities for all people that meet the search criteria.

Throws:

ModelCommunicationException - Thrown if unable to communicate with the data store.

ObjectNotFoundException - Thrown if unable to locate the container specified in the searchContext. This may be due to the container being removed by another client.

searchByFilter

public SearchResults searchByFilter(OrganizationalContainerEntity searchContext,
                                    java.lang.String profileName,
                                    java.lang.String filter,
                                    SearchParameters params)
                             throws ModelCommunicationException,
                                    ObjectNotFoundException

Searches for people that meet the criteria defined within the given filter. This search is performed as a raw search against the data store without any semantic mapping.

Parameters:

searchContext - OrganizationalContainerEntity which is to be used as the base context to search from.

profileName - Name of the ObjectProfile that defines the type of person (i.e., Employee, Contractor) to search for. If empty string passed, people of all types will be returned.

filter - Filter that defines the criteria for returned business units to meet. The filter must be in the format defined by RFC2254.

params - SearchParameters that provide additional context for how the search should be performed. If the search scope is ONELEVEL_SCOPE, the search is limited only to the people belong to the given parent (searchContext.last()). Otherwise, the whole organizational logical subtree will be searched.

Returns:

SearchResults holding PersonEntities for all people that meet the search criteria.

Throws:

ModelCommunicationException - Thrown if unable to communicate with the data store.

ObjectNotFoundException - Thrown if unable to locate the container specified in the searchContext. This may be due to the container being removed by another client.

searchByFilter

public SearchResults searchByFilter(CompoundDN searchContext,
                                    java.lang.String profileName,
                                    java.lang.String filter,
                                    SearchParameters params)
                             throws ModelCommunicationException,
                                    ObjectNotFoundException

Searches for people that meet the criteria defined within the given filter. This search is performed as a raw search against the data store without any semantic mapping.

Parameters:

searchContext - CompoundDN that defines the base of the search. At least one (1) element and at most three (3) are expected:

• searchContext.elements[0] must contain the tenant DN
• searchContext.elements[1] may contain the organization DN
• searchContext.elements[2] may contain the parent DN (optional)

An element cannot be skipped. For example, you can not pass the parent DN without passing the organization DN.

profileName - Name of the ObjectProfile that defines the type of person (i.e., Employee, Contractor) to search for. If empty string passed, people of all types will be returned.

filter - Filter that defines the criteria for returned people to meet. The filter must be in the format defined by RFC2254.

params - SearchParameters that provide additional context for how the search should be performed. If the search scope is ONELEVEL_SCOPE, the search is limited only to the people that belong to the given parent (searchContext.last()). Otherwise, the whole organizational logical subtree will be searched.

Returns:

SearchResults holding PersonEntities for all people that meet the search criteria.

Throws:

ModelCommunicationException - Thrown if unable to communicate with the data store.

ObjectNotFoundException - Thrown if unable to locate the container specified in the searchContext. This may be due to the container being removed by another client.

searchByFilter

public SearchResults searchByFilter(CompoundDN searchContext,
                                    java.lang.String profileName,
                                    java.lang.String filter,
                                    SearchParameters params,
                                    java.lang.Comparable clientSideFilter)
                             throws ModelCommunicationException,
                                    ObjectNotFoundException

Searches for people that meet the criteria defined within the given filter. This search is performed as a raw search against the data store without any semantic mapping.

Parameters:

searchContext - CompoundDN that defines the base of the search. At least one (1) element and at most three (3) are expected:

• searchContext.elements[0] must contain the tenant DN
• searchContext.elements[1] may contain the organization DN
• searchContext.elements[2] may contain the parent DN (optional)

An element cannot be skipped. For example, you can not pass the parent DN without passing the organization DN.

profileName - Name of the ObjectProfile that defines the type of person (i.e., Employee, Contractor) to search for. If empty string passed, people of all types will be returned.

filter - Filter that defines the criteria for returned people to meet. The filter must be in the format defined by RFC2254.

params - SearchParameters that provide additional context for how the search should be performed. If the search scope is ONELEVEL_SCOPE, the search is limited only to the people that belong to the given parent (searchContext.last()). Otherwise, the whole organizational logical subtree will be searched.

clientSideFilter - Object used to perform client-side filtering, or null if client-side filtering is not required.

Returns:

SearchResults holding PersonEntities for all people that meet the search criteria.

Throws:

ModelCommunicationException - Thrown if unable to communicate with the data store.

ObjectNotFoundException - Thrown if unable to locate the container specified in the searchContext. This may be due to the container being removed by another client.

searchByFilter

public SearchResults searchByFilter(CompoundDN searchContext,
                                    SearchParameters params,
                                    java.lang.String filter,
                                    java.lang.String categoryName)
                             throws ModelCommunicationException,
                                    ObjectNotFoundException

Searches for people in a given category that meet the criteria defined within the given filter . This search is performed as a raw search against the data store without any semantic mapping.

Parameters:

searchContext - CompoundDN that defines the base of the search. At least one (1) element and at most three (3) are expected:

• searchContext.elements[0] must contain the tenant DN
• searchContext.elements[1] may contain the organization DN
• searchContext.elements[2] may contain the parent DN (optional)

An element cannot be skipped. For example, you can not pass the parent DN without passing the organization DN.

params - SearchParameters that provide additional context for how the search should be performed. If the search scope is ONELEVEL_SCOPE, the search is limited only to the people that belong to the given parent (searchContext.last()). Otherwise, the whole organizational logical subtree will be searched.

filter - Filter that defines the criteria for returned people to meet. The filter must be in the format defined by RFC2254.

categoryName - Name of the category that defines the type of person (person or bpperson) to search for. If empty string passed, people of all types will be returned.

Returns:

SearchResults holding PersonEntities for all people that meet the search criteria.

Throws:

ModelCommunicationException - Thrown if unable to communicate with the data store.

ObjectNotFoundException - Thrown if unable to locate the container specified in the searchContext. This may be due to the container being removed by another client.

searchByFilter

public SearchResults searchByFilter(CompoundDN searchContext,
                                    SearchParameters params,
                                    java.lang.String filter,
                                    java.lang.String categoryName,
                                    java.lang.Comparable clientSideFilter)
                             throws ModelCommunicationException,
                                    ObjectNotFoundException

Searches for people in a given category that meet the criteria defined within the given filter . This search is performed as a raw search against the data store without any semantic mapping.

Parameters:

searchContext - CompoundDN that defines the base of the search. At least one (1) element and at most three (3) are expected:

• searchContext.elements[0] must contain the tenant DN
• searchContext.elements[1] may contain the organization DN
• searchContext.elements[2] may contain the parent DN (optional)

An element cannot be skipped. For example, you can not pass the parent DN without passing the organization DN.

params - SearchParameters that provide additional context for how the search should be performed. If the search scope is ONELEVEL_SCOPE, the search is limited only to the people that belong to the given parent (searchContext.last()). Otherwise, the whole organizational logical subtree will be searched.

filter - Filter that defines the criteria for returned people to meet. The filter must be in the format defined by RFC2254.

categoryName - Name of the category that defines the type of person (person or bpperson) to search for. If empty string passed, people of all types will be returned.

clientSideFilter - Object used to perform client-side filtering, or null if client-side filtering is not required.

Returns:

SearchResults holding PersonEntities for all people that meet the search criteria.

Throws:

ModelCommunicationException - Thrown if unable to communicate with the data store.

ObjectNotFoundException - Thrown if unable to locate the container specified in the searchContext. This may be due to the container being removed by another client.

searchByProfile

public SearchResults searchByProfile(CompoundDN searchContext,
                                     SearchParameters params,
                                     java.lang.String profileName,
                                     java.lang.String value)
                              throws ModelCommunicationException,
                                     ModelIntegrityException,
                                     ObjectNotFoundException

Searches for people in a given category that meet the criteria defined within the given filter . This search is performed as a raw search against the data store without any semantic mapping.

Parameters:

searchContext - CompoundDN that defines the base of the search. At least one (1) element and at most three (3) are expected:

• searchContext.elements[0] must contain the tenant DN
• searchContext.elements[1] may contain the organization DN
• searchContext.elements[2] may contain the parent DN (optional)

An element cannot be skipped. For example, you can not pass the parent DN without passing the organization DN.

params - SearchParameters that provide additional context for how the search should be performed. If the search scope is ONELEVEL_SCOPE, the search is limited only to the people that belong to the given parent (searchContext.last()). Otherwise, the whole organizational logical subtree will be searched.

Returns:

SearchResults holding PersonEntities for all people that meet the search criteria.

Throws:

ModelCommunicationException - Thrown if unable to communicate with the data store.

ObjectNotFoundException - Thrown if unable to locate the container specified in the searchContext. This may be due to the container being removed by another client.

ModelIntegrityException

searchByAuthorizedRole

public SearchResults searchByAuthorizedRole(DistinguishedName roleDN,
                                            SearchParameters params)
                                     throws ModelCommunicationException,
                                            ModelIntegrityException

Returns all people who are members of a given role or members of a child role of the given role in the role hierarchy

Parameters:

roleDN - DistinguishedName of the role in question.

params - SearchParameters that provide additional context for how the search should be performed. Note that scope is not applicable.

Returns:

SearchResults holding PersonEntities who are members of the role.

Throws:

ModelCommunicationException - Thrown if unable to communicate with the data store

ModelIntegrityException - Thrown if there is a model integrity violation error

Since:

TIM 5.1

searchByAuthorizedRoles

public SearchResults searchByAuthorizedRoles(java.util.Collection<DistinguishedName> roleCol,
                                             SearchParameters params)
                                      throws ModelCommunicationException,
                                             ModelIntegrityException

Returns all people who are members of any one of the roles in the given collection or members of a child role of any of the roles in the given collection

Parameters:

roleCol - Collection of DistinguishedName of the role in question. If the roleCol is NULL or empty, an empty set is returned

params - SearchParameters that provide additional context for how the search should be performed. Note that scope is not applicable.

Returns:

SearchResults holding PersonEntities who are members of the role.

Throws:

ModelCommunicationException - Thrown if unable to communicate with the data store.

ModelIntegrityException - Thrown if there is a model integrity violation error

Since:

TIM 5.1

searchByRole

public SearchResults searchByRole(DistinguishedName roleDN,
                                  SearchParameters params)
                           throws ModelCommunicationException,
                                  ObjectNotFoundException

Returns all people who are members of a given role.

Parameters:

roleDN - DistinguishedName of the role in question.

params - SearchParameters that provide additional context for how the search should be performed. Note that scope is not applicable.

Returns:

SearchResults holding PersonEntities who are members of the role.

Throws:

ModelCommunicationException - Thrown if unable to communicate with the data store.

ObjectNotFoundException

searchByAlias

public SearchResults searchByAlias(OrganizationalContainerEntity searchContext,
                                   java.lang.String alias,
                                   SearchParameters params)
                            throws ModelCommunicationException,
                                   ObjectNotFoundException

Returns all people with the given alias.

Parameters:

searchContext - OrganizationalContainerEntity which is to be used as the base context to search from.

alias - The value to search by.

params - SearchParameters that provide additional context for how the search should be performed. Note that scope is not applicable.

Returns:

SearchResults holding PersonEntities with the given alias.

Throws:

ModelCommunicationException - Thrown if unable to communicate with the data store.

ObjectNotFoundException - Thrown if unable to locate the container specified in the searchContext. This may be due to the container being removed by another client.

searchByAlias

public SearchResults searchByAlias(CompoundDN searchContext,
                                   java.lang.String alias,
                                   SearchParameters params)
                            throws ModelCommunicationException,
                                   ObjectNotFoundException

Returns all people with the given alias.

Parameters:

searchContext - CompoundDN that defines the base of the search. At least one (1) element and at most three (3) are expected:

• searchContext.elements[0] must contain the tenant DN
• searchContext.elements[1] may contain the organization DN
• searchContext.elements[2] may contain the parent DN (optional)

An element cannot be skipped. For example, you can not pass the parent DN without passing the organization DN.

alias - The value to search by.

params - SearchParameters that provide additional context for how the search should be performed. Note that scope is not applicable.

Returns:

SearchResults holding PersonEntities with the given alias.

Throws:

ModelCommunicationException - Thrown if unable to communicate with the data store.

ObjectNotFoundException - Thrown if unable to locate the container specified in the searchContext. This may be due to the container being removed by another client.

searchByName

public SearchResults searchByName(CompoundDN searchContext,
                                  java.lang.String profileName,
                                  java.lang.String name)
                           throws ModelCommunicationException,
                                  ObjectNotFoundException

Searches for people for a given name.

Parameters:

searchContext - CompoundDN that defines the base of the search.

profileName - Name of the ObjectProfile that defines the type of person (i.e., Employee, Contractor) to search for. If empty string/null/invalid value is passed, people of all types will be returned.

name - Name of the person to search for.

Returns:

SearchResults holding PersonEntities for all people that meet the search criteria.

Throws:

ModelCommunicationException - Thrown if unable to communicate with the data store.

ObjectNotFoundException - Thrown if unable to locate the container specified in the searchContext. This may be due to the container being removed by another client.

searchByName

public SearchResults searchByName(CompoundDN searchContext,
                                  java.lang.String profileName,
                                  java.lang.String name,
                                  SearchParameters params)
                           throws ModelCommunicationException,
                                  ObjectNotFoundException

Searches for people for a given name.

Parameters:

searchContext - CompoundDN that defines the base of the search.

profileName - Name of the ObjectProfile that defines the type of person (i.e., Employee, Contractor) to search for. If empty string/null/invalid value is passed, people of all types will be returned.

name - Name of the person to search for.

params - SearchParameters that provide additional context for how the search should be performed. If the search scope is ONELEVEL_SCOPE, the search is limited only to the people that belong to the given parent (searchContext.last()). Otherwise, the whole organizational logical subtree will be searched.

Returns:

SearchResults holding PersonEntities for all people that meet the search criteria.

Throws:

ModelCommunicationException - Thrown if unable to communicate with the data store.

ObjectNotFoundException - Thrown if unable to locate the container specified in the searchContext. This may be due to the container being removed by another client.

searchByURI

public PersonEntity searchByURI(OrganizationalContainerEntity searchContext,
                                java.lang.String uri)
                         throws ModelCommunicationException,
                                URINotUniqueException,
                                ObjectNotFoundException

Find the person for a specific URI.

Parameters:

searchContext - OrganizationalContainerEntity which is to be used as the base context to search from.

uri - URI of the person.

Returns:

PersonEntity with the corresponding URI.

Throws:

ModelCommunicationException - Thrown if unable to communicate with the data store.

URINotUniqueException - Thrown if more than one object is found for the URI under the specified search context.

ObjectNotFoundException - Thrown if unable to locate the person or the search context in the data store. This may be due to an invalid distinguished name, or the entity may have been removed by another client.