com.ibm.itim.apps.search

Class SearchResultsMO

java.lang.Object

com.ibm.itim.apps.search.SearchResultsMO

All Implemented Interfaces:

java.io.Serializable

public class SearchResultsMO
extends java.lang.Object
implements java.io.Serializable

Provides access to an authorized and sortable set of DirectoryObject which may be traversed on a page by page basis. A SearchResultsMO is usually the result of executing a search through a SearchMO and provides access to sets of DirectoryObject in sequential pages through getPage(int pageNo) where pageNo may be equal to (but not greater than) the value returned by getPageCount() if the last page in the set is needed. A SearchResultsMO may be sorted given the name of an attribute whose value to sort the set by and one of SearchMO.ASCENDING_SORT or SearchMO.DESCENDING_SORT to indicate a low to high or high to low sort order. The sort function is provided by sortResults(). Because the SearchResultsMO itself does not hold the result set but instead maintains a reference to a stateful session EJB hosted by the server whose state does include the result set of DirectoryObject, close() provides clients an explicit way to free up EJB resources (i.e., to remove the stateful bean instance) and a way to reclaim server memory after traversal of the set is complete.

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
com.ibm.itim.apps.impl.PlatformContextImpl	platform The PlatformContext holding platform connection information.
javax.security.auth.Subject	subject The Subject representing the authenticated caller.

Constructor Summary

Constructors

Constructor and Description
SearchResultsMO(PlatformContext platform, javax.security.auth.Subject subject) Constructs the the managed object with a platform context and a subject.

Method Summary

Modifier and Type	Method and Description
void	close() Releases this SearchResultsMO EJB resources (removes the stateful session bean instance associated with this SearchResultsMO).
java.util.Collection<DirectoryObject>	getPage(int pageNo) Returns the specified page of the result set.
int	getPageCount() Returns the number of pages in the result set.
int	getPageCount(int lookaheadLimit) Returns the number of available pages up to a look-ahead limit.
java.util.Collection	getResults() Deprecated. This method has been replaced with the getSearchResults() which addresses additional requirements introduced by RESTful services.
java.util.Collection	getSearchResults() Returns all of the results.
SearchResultsStatus	getSearchResultsStatus() Gets the SearchResultsStatus.
void	reverseSortResults() Reverses the the sorting order of the search results.
void	setSearchResults(java.util.Collection results) Holds the given results in this SearchResultsMO
void	setSearchResultsStatus(SearchResultsStatus sResultsStatus) Sets the SearchResultsStatus.
void	setSearchResultsWithLocale(java.util.Collection results, java.lang.String sortAttribute, java.util.Locale locale) Holds the given results in this SearchResultsMO
void	sortResults(java.lang.String attribute, int order) Resorts by the given sort attribute and order (ascending vs descending).

Methods inherited from class java.lang.Object

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

Field Detail

subject

public javax.security.auth.Subject subject

The Subject representing the authenticated caller. Is initialized by the SearchResultsMO constructor.

platform

public com.ibm.itim.apps.impl.PlatformContextImpl platform

The PlatformContext holding platform connection information.

Constructor Detail

SearchResultsMO

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

Constructs the the managed object with a platform context and a subject.

Parameters:

platform - PlatformContext holding platform connection information.

subject - Subject representing the authenticated caller.

Method Detail

setSearchResults

public void setSearchResults(java.util.Collection results)
                      throws java.rmi.RemoteException,
                             ApplicationException

Holds the given results in this SearchResultsMO

Parameters:

results - Collection of DirectoryObjectEntity

Throws:

java.rmi.RemoteException - thrown if unable to communicate with the platform

ApplicationException - if an error prevents the given results from being associated with a SearchAuthority bean instance.

setSearchResultsWithLocale

public void setSearchResultsWithLocale(java.util.Collection results,
                                       java.lang.String sortAttribute,
                                       java.util.Locale locale)
                                throws java.rmi.RemoteException,
                                       ApplicationException

Holds the given results in this SearchResultsMO

Parameters:

results - Collection of value objects. Only supported value objects are enumeration of ExistingUserAccess, DirectoryObject.

sortAttribute - attribute name to sort with.

locale - locale to sort with.

Throws:

java.rmi.RemoteException - thrown if unable to communicate with the platform

ApplicationException - if an error prevents the given results from being associated with a SearchAuthority bean instance.

Since:

ITIM 5.0

getPageCount

public int getPageCount()
                 throws java.rmi.RemoteException,
                        ApplicationException,
                        java.lang.IllegalStateException

Returns the number of pages in the result set.

Performance Note: Users of this method should note that in many cases, the page count cannot be determined by the system without loading the complete result set from the underlying database or directory. This can lead to performance and scaling problems when the result set size is very large. If there is reason to believe that the result set could be large then it is recommended that users take advantage of the getPageCount(int lookaheadLimit) method that allows an upper bound on the amount of lookahead that the system will perform to determine the page count.

Returns:

Number of pages in the result set.

Throws:

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

ApplicationException - is thrown if a server-side error prevents this method from returning the number of pages in the result set.

java.lang.IllegalStateException - if the underlying EJB resource(s) are unavailable. This generally means that the SearchAuthority bean for the server EJB cannot be found.

See Also:

getPageCount(int)

getPageCount

public int getPageCount(int lookaheadLimit)
                 throws java.rmi.RemoteException,
                        ApplicationException,
                        java.lang.IllegalStateException

Returns the number of available pages up to a look-ahead limit. This method allows clients to determine if a certain number of pages is available in a given result set without forcing the system to load all of the result pages. See the performance notes in the API documentation for the getPageCount() method.

Parameters:

lookaheadLimit - The number of pages to advance through the result set in order to determine the available page count.

Returns:

The number of pages available, up to the specified look-ahead limit. If more pages than the limit are available, the limit will be returned. If less pages than the limit are available, the available page count will be returned.

Throws:

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

ApplicationException - If there is a problem performing this operation at the server.

java.lang.IllegalStateException - if the underlying EJB resource(s) are unavailable. This generally means that the SearchAuthority bean for the server EJB cannot be found.

See Also:

getPageCount()

getPage

public java.util.Collection<DirectoryObject> getPage(int pageNo)
                                              throws java.rmi.RemoteException,
                                                     ApplicationException,
                                                     java.lang.IllegalStateException

Returns the specified page of the result set.

Parameters:

pageNo - The number of the page to return.

Returns:

Collection of DirectoryObjects representing page of results.

Throws:

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

ApplicationException - If there is a problem performing this operation at the server.

java.lang.IllegalStateException - if the underlying EJB resource(s) are unavailable. This generally means that the SearchAuthority bean for the server EJB cannot be found.

getResults

@Deprecated
public java.util.Collection getResults()
                                             throws java.rmi.RemoteException,
                                                    ApplicationException,
                                                    java.lang.IllegalStateException

Deprecated. This method has been replaced with the getSearchResults() which addresses additional requirements introduced by RESTful services.

Returns all of the results.

Returns:

Collection of DirectoryObjects representing the complete result set.

Throws:

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

ApplicationException - If there is a problem performing this operation at the server.

java.lang.IllegalStateException - if the underlying EJB resource(s) are unavailable. This generally means that the SearchAuthority bean for the server EJB cannot be found.

sortResults

public void sortResults(java.lang.String attribute,
                        int order)
                 throws java.rmi.RemoteException,
                        ApplicationException,
                        java.lang.IllegalStateException

Resorts by the given sort attribute and order (ascending vs descending).

Parameters:

attribute - Name of the attribute to sort by.

order - Enumeration of the order to sort by. Value may be either SearchMO.ASCENDING_SORT or SearchMO.DESCENDING_SORT.

Throws:

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

ApplicationException - Thrown if unable to resort. This is most likely caused by either an invalid sort attribute name or invalid sort order.

java.lang.IllegalStateException - if the underlying EJB resource(s) are unavailable. This generally means that the SearchAuthority bean for the server EJB cannot be found.

reverseSortResults

public void reverseSortResults()
                        throws java.rmi.RemoteException,
                               ApplicationException,
                               java.lang.IllegalStateException

Reverses the the sorting order of the search results.

Throws:

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

ApplicationException - Thrown if unable to resort. This is most likely caused by either an invalid sort attribute name or invalid sort order.

java.lang.IllegalStateException - if the underlying EJB resource(s) are unavailable. This generally means that the SearchAuthority bean for the server EJB cannot be found.

close

public void close()
           throws java.rmi.RemoteException,
                  ApplicationException

Releases this SearchResultsMO EJB resources (removes the stateful session bean instance associated with this SearchResultsMO).

Throws:

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

ApplicationException - Thrown if unable to resort. This is most likely caused by either an invalid sort attribute name or invalid sort order.

setSearchResultsStatus

public void setSearchResultsStatus(SearchResultsStatus sResultsStatus)

Sets the SearchResultsStatus.

Parameters:

sResultsStatus - A SearchResultsStatus instance, or null of not applicable to the search request.

getSearchResultsStatus

public SearchResultsStatus getSearchResultsStatus()

Gets the SearchResultsStatus.

Returns:

sResultsStatus A SearchResultsStatus instance, or null of not applicable to the search request.

getSearchResults

public java.util.Collection getSearchResults()
                                      throws java.rmi.RemoteException,
                                             ApplicationException,
                                             java.lang.IllegalStateException

Returns all of the results.

Returns:

Collection of DirectoryObjects representing the complete result set.

Throws:

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

ApplicationException - If there is a problem performing this operation at the server.

java.lang.IllegalStateException - if the underlying EJB resource(s) are unavailable. This generally means that the SearchAuthority bean for the server EJB cannot be found.