oracle.ifs.beans

Class Selector

java.lang.Object

oracle.ifs.beans.Selector

Direct Known Subclasses:

WastebasketSelector

public class Selector
extends Object

The Selector class creates and executes SIMPLE searches. The search is simple because it only searches one class (no "joins" are supported).
A search is performed by constructing a Selector object, setting the search class and search selection, then calling getItems()to run the query. The search class represents a Library class type, i.e. FOLDER. The search selection takes the form of a SQL WHERE clause (without the word "WHERE"). In addition, the sort order defines the manner in which the query is sorted. Lastly, the RecursiveSearch option determines whether or not sublcasses are searched as well.
The search results will be locally cached, and a call to resetItems() is required before the query will be executed again. Calls to item attribute, sort order, selection and class methods will all clear the cache automatically.
Query results are accessed by using the JavaBeans compliant getItems() methods, or by using the openItems(), nextItems(), closeItems() methods.

Using only nextItem() to access selected objects keeps the memory footprint of the selector class low, as it does not cache any objects. When you have potentially large number of objects selected, use nextItem() style of access.

If you use getItems() or getItems(index), the Selector class starts caching the fetched objects in memory. Use this as a convenience when you are certain that the number of selected objects will be a small.

Mixing nextItem() style of access with getItems() style is to be avoided. In case of mixed style access, the Selector class falls back to getItems() mode of operation, where it starts caching all fetched results.

Note that instances of this class do not persist. If you wish to use the same selector in more than one session, consider using a SelectorObject, which can be saved.

Version:

1.0

Author:

Dave Long

See Also:

SelectorObject, SelectorObjectDefinition

(Published)

Field Summary

Fields

Modifier and Type	Field and Description
protected long	m_CursorId Open cursor handle; used by open/next/close methods
protected Vector	m_CursorItems Vector containing items fetched by an open cursor, as LibraryObjects
protected int	m_CursorPos The last position of a cursor call
protected int	m_MaxItemCount The max number of items returned via getItems().
protected boolean	m_RecursiveSearch True if a recursive search (with respect to the specified class) will be executed.
protected int	m_ResolvedCursorPos The last position of the resolved items cursor.
protected Vector	m_ResolvedItems Vector containing the selector results, as LibraryObjects
protected String	m_SearchClass Selector class.
protected String	m_SearchSelection Selector definition string (i.e. the SQL where clause).
protected LibrarySession	m_Session The current session
protected SortSpecification	m_SortSpecification Sort specification.

Constructor Summary

Constructors

Constructor and Description
Selector(LibrarySession session) Construct a Selector object.

Method Summary

Modifier and Type	Method and Description
void	closeItems() Closes the search after cursor based access.
int	getItemCount() Returns the number of items in the search results.
LibraryObject[]	getItems() Returns the entire search results as an array.
LibraryObject	getItems(int index) Returns a single search result item from the search results with an index relative the the search sort order.
int	getMaxItemCount() Returns the setting of the maximum number of items that will be returned in a getItems() invocation.
String	getSearchClassname() Returns the search class.
String	getSearchSelection() Returns the search selection.
protected int	getSelectorItemCount() Get the search item count.
SortSpecification	getSortSpecification() Returns the Sort Specification
boolean	isRecursiveSearch() Returns true if recursive searching is enabled with respect to classes (i.e., true if this selector will search all subclasses of the specific class).
protected Vector	listSelectorItems() List the Selector items.
LibraryObject	nextItem() Gets the next item using an open cursor on the search.
void	openItems() Opens a cursor on this Search ready for reading search results.
protected void	openSelector() Opens a cursor on this Search ready for reading search results.
void	resetItems() Clears locally stored search results.
protected void	resolveSortSpecification(LibrarySession session) Force the SortSpecification (if specified) to be resolved and verified.
void	setMaxItemCount(int maxItemCount) Sets the maximum number of items that will be returned in a getItems() invocation.
void	setRecursiveSearch(boolean recursive) Enables/disables recursive searching with respect to classes.
void	setSearchClassname(String searchClass) Sets the search class.
void	setSearchSelection(String searchSelection) Sets the search selection.
void	setSortSpecification(SortSpecification spec) Sets the Sort Specification
LibrarySession	verifyConnected() Return the current LibrarySession if the session is connected; otherwise raise a "not connected" exception.

Methods inherited from class java.lang.Object

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

Field Detail

m_Session

protected LibrarySession m_Session

The current session

(Unpublished)

m_SortSpecification

protected SortSpecification m_SortSpecification

Sort specification.

(Unpublished)

m_SearchClass

protected String m_SearchClass

Selector class.

(Unpublished)

m_SearchSelection

protected String m_SearchSelection

Selector definition string (i.e. the SQL where clause).

(Unpublished)

m_RecursiveSearch

protected boolean m_RecursiveSearch

True if a recursive search (with respect to the specified class) will be executed.

(Unpublished)

m_MaxItemCount

protected int m_MaxItemCount

The max number of items returned via getItems(). A value of 0 means unlimited.

(Unpublished)

m_ResolvedItems

protected Vector m_ResolvedItems

Vector containing the selector results, as LibraryObjects

(Unpublished)

m_CursorItems

protected Vector m_CursorItems

Vector containing items fetched by an open cursor, as LibraryObjects

(Unpublished)

m_CursorPos

protected int m_CursorPos

The last position of a cursor call

(Unpublished)

m_ResolvedCursorPos

protected int m_ResolvedCursorPos

The last position of the resolved items cursor.

(Unpublished)

m_CursorId

protected long m_CursorId

Open cursor handle; used by open/next/close methods

(Unpublished)

Constructor Detail

Selector

public Selector(LibrarySession session)
         throws IfsException

Construct a Selector object.

Parameters:

session - the current session.

Throws:

IfsException - if operation fails.

(Published)

Method Detail

getSearchClassname

public String getSearchClassname()
                          throws IfsException

Returns the search class.

Returns:

the search class.

Throws:

IfsException - if operation fails.

(Published)

setSearchClassname

public void setSearchClassname(String searchClass)
                        throws IfsException

Sets the search class.

Parameters:

searchClass - the search class.

Throws:

IfsException - if operation fails.

(Published)

getSearchSelection

public String getSearchSelection()
                          throws IfsException

Returns the search selection.

Returns:

the search selection.

Throws:

IfsException - if operation fails.

(Published)

setSearchSelection

public void setSearchSelection(String searchSelection)
                        throws IfsException

Sets the search selection.

Parameters:

searchSelection - the search selection.

Throws:

IfsException - if operation fails.

(Published)

isRecursiveSearch

public boolean isRecursiveSearch()
                          throws IfsException

Returns true if recursive searching is enabled with respect to classes (i.e., true if this selector will search all subclasses of the specific class).

Returns:

true is enabled.

Throws:

IfsException - if the operation fails.

(Published)

setRecursiveSearch

public void setRecursiveSearch(boolean recursive)
                        throws IfsException

Enables/disables recursive searching with respect to classes. The default is set true, which means that subclasses are search as well as the specified class. Setting it to false retricts the search to the single specified class.

Parameters:

recursive - true for enabled.

Throws:

IfsException - if the operation fails.

(Published)

setMaxItemCount

public void setMaxItemCount(int maxItemCount)
                     throws IfsException

Sets the maximum number of items that will be returned in a getItems() invocation. A value of zero indicates that there is no limit on the desired number of items.

Parameters:

maxItemCount - maximum number of items that will be returned from a getItems() invocation

Throws:

IfsException - if the operation fails.

(Unpublished)

getMaxItemCount

public int getMaxItemCount()
                    throws IfsException

Returns the setting of the maximum number of items that will be returned in a getItems() invocation. A value of zero indicates that there is no limit on the desired number of items.

Returns:

maximum number of items that will be returned from a getItems() invocation

Throws:

IfsException - if the operation fails.

(Unpublished)

getSortSpecification

public SortSpecification getSortSpecification()
                                       throws IfsException

Returns the Sort Specification

Returns:

the search item sort specificaion.

Throws:

IfsException - if the operation fails.

(Published)

setSortSpecification

public void setSortSpecification(SortSpecification spec)
                          throws IfsException

Sets the Sort Specification

Parameters:

spec - the sort specification.

Throws:

IfsException - if the operation fails.

(Published)

getItems

public LibraryObject[] getItems()
                         throws IfsException

Returns the entire search results as an array. If the Selector instance was used with only nextItem() style of access prior to this, then the cursor will be re-opened.

Returns:

the search results. Returns null if no items found.

Throws:

IfsException - if operation fails.

(Published)

getItems

public LibraryObject getItems(int index)
                       throws IfsException,
                              IndexOutOfBoundsException

Returns a single search result item from the search results with an index relative the the search sort order. If the Selector instance was used with only nextItem() style of access prior to this, then the cursor will be re-opened.

Parameters:

index - the index of a search result.

Returns:

a search result.

Throws:

IfsException - if operation fails.

IndexOutOfBoundsException - if the index is greater than the number of items in the search.

(Published)

getItemCount

public int getItemCount()
                 throws IfsException

Returns the number of items in the search results. If the items have already been fetched then this simply returns the size of the locally stored vector. Otherwise this gets the count from the IFS server.

Returns:

the number of items.

Throws:

IfsException - if operation fails.

(Published)

openItems

public void openItems()
               throws IfsException

Opens a cursor on this Search ready for reading search results. This method is used if you expect the search to return a large number of items and you don't want to get them all at once (cursor style).
Note: You must call closeItems() to close the open cursor.

Throws:

IfsException - if the operation fails.

See Also:

closeItems()

(Published)

openSelector

protected void openSelector()
                     throws IfsException

Opens a cursor on this Search ready for reading search results. This method is split out from openItems(), so that it can be overridden by WastebasketSelector.

Throws:

IfsException - if the operation fails.

(Unpublished)

nextItem

public LibraryObject nextItem()
                       throws IfsException

Gets the next item using an open cursor on the search.

Returns:

The Item. Throws IfsException 22000 if no more items.

Throws:

IfsException - 22000 if no more items, or other error code if the operation fails.

(Published)

closeItems

public void closeItems()
                throws IfsException

Closes the search after cursor based access.

Throws:

IfsException - if the operation fails.

(Published)

resetItems

public void resetItems()
                throws IfsException

Clears locally stored search results. A subsequent call to getItems() will re-fetch the search results from the server. Any calls to search class, search selection, or attribute methods will call this method internally.

Throws:

IfsException - if operation fails.

(Published)

listSelectorItems

protected Vector listSelectorItems()
                            throws IfsException

List the Selector items.

Returns:

Vector of Selector items.

Throws:

IfsException - if the operation fails.

(Unpublished)

getSelectorItemCount

protected int getSelectorItemCount()
                            throws IfsException

Get the search item count.

Returns:

the number of items

Throws:

IfsException - if operation fails.

(Unpublished)

verifyConnected

public LibrarySession verifyConnected()
                               throws IfsException

Return the current LibrarySession if the session is connected; otherwise raise a "not connected" exception.

Returns:

the current LibrarySession

Throws:

ConnectionException - if not connected

IfsException

(Unpublished)

resolveSortSpecification

protected void resolveSortSpecification(LibrarySession session)
                                 throws IfsException

Force the SortSpecification (if specified) to be resolved and verified.

Parameters:

session - the current LibrarySession

Throws:

ConnectionException - if not connected

IfsException

(Unpublished)