oracle.ifs.beans

Class Search

java.lang.Object

oracle.ifs.beans.Search

public final class Search
extends Object

The Search class provides a way to search for objects. A Search is specified by a SearchSpecification. To execute a Search use the open, next & close functions.

Version:

1.0

Author:

Harish Butani

See Also:

SearchSpecification, AttributeSearchSpecification, ContextSearchSpecification, SearchResultObject

(Published)

Field Summary

Fields

Modifier and Type	Field and Description
protected Long	m_Id Id of server-side Search object.
protected SearchSpecification	m_SearchSpecification SearchSpecification defining Search.
protected LibrarySession	m_Session LibrarySession in which Search will execute.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	Search(LibrarySession sess, Long searchObjectId) Constructs a Search object.
	Search(LibrarySession sess, SearchSpecification sp) Constructs a Search object.

Method Summary

Modifier and Type	Method and Description
void	close() Closes the search.
static String	convertAttributeName(ClassObject cls, String attrName) Helper Functions used by Qualifiers to convert attribute names from old names to current names.
protected static void	createView(LibrarySession sess, ViewSpecification vsp)
void	dispose() Disposes this Search.
String	explainPlan(String planTable, String planName, boolean clearRows, AttributeValue[] bindValues) Generates the Query plan for the Search.
int	getItemCount() Returns the number of rows in search result.
int	getItemCount(AttributeValue[] bindValues) Returns the number of rows in search result.
int	getItemCount(AttributeValue[] bindValues, String language) Returns the number of rows in search result.
int	getItemCount(AttributeValue[] bindValues, String language, int timeout) Returns the number of rows in search result.
int	getItemCount(String language) Returns the number of rows in search result.
SearchResultObject[]	getItems() Returns the all the rows in the Search Result.
SearchResultObject	getItems(int index) Returns the ith row in the Search Result.
LibraryObject[]	getResolvedItems() Returns the resolved objects for all the rows in the Search Result.
LibraryObject	getResolvedItems(int index) Returns the resolved object for the ith row in the Search Result.
SearchSpecification	getSearchSpecification() Returns the SearchSpecification of this Search.
String	getSQL() Returns the SQL query generated by the search.
SearchResultObject	next() Returns the next result row.
void	open() Opens the Search.
void	open(AttributeValue[] bindValues) Opens the Search.
void	open(AttributeValue[] bindValues, String language) Opens the Search.
void	open(AttributeValue[] bindValues, String language, int timeout) Opens the Search.
void	open(String language) Opens the Search.
void	open(String sqlHint, AttributeValue[] bindValues) Another variation of open.
void	setSearchSpecification(SearchSpecification sp) Set the SearchSpecification.
protected LibrarySession	verifyConnected() Ensure LibrarySession of this Search is valid.

Methods inherited from class java.lang.Object

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

Field Detail

m_SearchSpecification

protected SearchSpecification m_SearchSpecification

SearchSpecification defining Search.

(Unpublished)

m_Session

protected LibrarySession m_Session

LibrarySession in which Search will execute.

(Unpublished)

m_Id

protected Long m_Id

Id of server-side Search object.

(Unpublished)

Constructor Detail

Search

public Search(LibrarySession sess,
              SearchSpecification sp)
       throws IfsException

Constructs a Search object.

Parameters:

sess - LibrarySession in which Search will execute.

sp - SearchSpecification defining Search. The SearchSpecification is cloned, any changes in SearchSpecification after constructing a Search will not be picked up.

Throws:

IfsException - 21000 if sess is not valid; 19001 if sp is not valid

(Published)

Search

protected Search(LibrarySession sess,
                 Long searchObjectId)
          throws IfsException

Constructs a Search object. The server side Search object's id is provided. This constructor is used when user wants to execute a saved search.

Parameters:

sess - LibrarySession in which Search will execute.

searchObjectId - id of server-side Search Object. This contains the Specification and is ready to execute it.

Throws:

IfsException - 21000 if sess is not valid

(Unpublished)

Method Detail

createView

protected static void createView(LibrarySession sess,
                                 ViewSpecification vsp)
                          throws IfsException

Throws:

IfsException

(Unpublished)

setSearchSpecification

public void setSearchSpecification(SearchSpecification sp)
                            throws IfsException

Set the SearchSpecification. If the search was previosly opened, exisitng cached items and cursors are closed. The SearchSpecification is cloned. Therefore, any changes to it after calling this method will not affect the outcome of the search.

Parameters:

sp - SearchSpecification defining Search.

Throws:

IfsException - 19001 if sp is not valid

(Published)

getSearchSpecification

public SearchSpecification getSearchSpecification()
                                           throws IfsException

Returns the SearchSpecification of this Search.

Returns:

the SearchSpecification

Throws:

IfsException - if the operation fails

(Published)

explainPlan

public String explainPlan(String planTable,
                          String planName,
                          boolean clearRows,
                          AttributeValue[] bindValues)
                   throws IfsException

Generates the Query plan for the Search. The plan is stored in the plan_table. It is also returned as a String by issuing a select on the plan_table. See SearchSpecification for details.
If the planTable is null, then the default table 'PLAN_TABLE' is used. The planName is used as statement_id in the plan_table. If clearRows is true, the generated rows are deleted from the plan_table. The default is false.

Parameters:

planTable - The db table where the plan is stored.

planName - A name for the plan

clearRows - If true, the planTable is cleared of the generated rows.

bindValues - Bind values for the Search

Returns:

the Query Plan.

Throws:

IfsException - 22009 on error

See Also:

SearchSpecification

(Unpublished)

open

public void open()
          throws IfsException

Opens the Search. This executes the Search and sets the cursor to the top of the ResultSet. Calls open(null, null). Assumes no bind values and language defaults to the sessions default.

Throws:

IfsException - if the operation fails.

(Published)

open

public void open(String language)
          throws IfsException

Opens the Search. This executes the Search and sets the cursor to the top of the ResultSet. This allows a specific session language to be used for searches.

Parameters:

language - language to be used for search

Throws:

IfsException - if open fails

(Published)

open

public void open(AttributeValue[] bindValues)
          throws IfsException

Opens the Search. This executes the Search and sets the cursor to the top of the ResultSet. Users can specify the bind values. Default language will be used. Calls open(bindValues, null).

Parameters:

bindValues - array of late bound values

Throws:

IfsException - if open fails

(Published)

open

public void open(AttributeValue[] bindValues,
                 String language)
          throws IfsException

Opens the Search. This executes the Search and sets the cursor to the top of the ResultSet. Users can specify the bind values and the session language.

Parameters:

bindValues - array of late bound values

language - language to be used for the search

Throws:

IfsException - if open fails

(Published)

open

public void open(AttributeValue[] bindValues,
                 String language,
                 int timeout)
          throws IfsException

Opens the Search. This executes the Search and sets the cursor to the top of the ResultSet. Users can specify the bind values, session language and timeout value.

Parameters:

bindValues - array of late bound values

language - language to be used for the search

timeout - search will timeout after this number of seconds; if 0, the timeout is infinite.

Throws:

IfsException - if open fails

(Published)

open

public void open(String sqlHint,
                 AttributeValue[] bindValues)
          throws IfsException

Another variation of open. Allows user to specify a sql Hint, when executing a search.

Parameters:

sqlHint - Hint specified in Oracle Hint syntax. See Oracle Performance and Tuning manual.

bindValues - Bind Values

Throws:

IfsException - if open fails.

(Unpublished)

getItemCount

public int getItemCount()
                 throws IfsException

Returns the number of rows in search result. Calls getItemCount(null, null). Assumes no bind values and language defaults to the sessions default. Runs a select count(*) query to get the count. This does NOT cache the result. Repeated calls to this method in the same search object result in database query everytime. The number of items returned here is not guaranteed to match the number of items found, when the actual search is run. This is because, objects might be created or deleted between the time when getItemCount() is called and the actual search is run by calling open(). When getItemCount() is called on a Search that is setup to remove duplicates, the number returned is the total number of distinct first result class type objects in the result set.

Returns:

Number of items in search result set.

Throws:

IfsException - if the operation fails.

(Published)

getItemCount

public int getItemCount(String language)
                 throws IfsException

Returns the number of rows in search result. This allows a specific session language to be used. Runs a select count(*) query to get the count. This does NOT cache the result. Repeated calls to this method in the same search object result in database query everytime. The number of items returned here is not guaranteed to match the number of items found, when the actual search is run. This is because, objects might be created or deleted between the time when getItemCount() is called and the actual search is run by calling open().

Parameters:

language - language to be used for search

Returns:

Number of items in search result set.

Throws:

IfsException - if the operation fails.

(Published)

getItemCount

public int getItemCount(AttributeValue[] bindValues)
                 throws IfsException

Returns the number of rows in search result. Users can specify the bind values. Default language will be used. Calls getItemCount(bindValues, null). Runs a select count(*) query to get the count. This does NOT cache the result. Repeated calls to this method in the same search object result in database query everytime. The number of items returned here is not guaranteed to match the number of items found, when the actual search is run. This is because, objects might be created or deleted between the time when getItemCount() is called and the actual search is run by calling open().

Parameters:

bindValues - array of late bound values

Returns:

Number of items in search result set.

Throws:

IfsException - if the operation fails.

(Published)

getItemCount

public int getItemCount(AttributeValue[] bindValues,
                        String language)
                 throws IfsException

Returns the number of rows in search result. Users can specify the bind values and the session language. Runs a select count(*) query to get the count. This does NOT cache the result. Repeated calls to this method in the same search object result in database query everytime. The number of items returned here is not guaranteed to match the number of items found, when the actual search is run. This is because, objects might be created or deleted between the time when getItemCount() is called and the actual search is run by calling open().

Parameters:

bindValues - array of late bound values

language - language to be used for the search

Returns:

Number of items in search result set.

Throws:

IfsException - if the operation fails.

(Published)

getItemCount

public int getItemCount(AttributeValue[] bindValues,
                        String language,
                        int timeout)
                 throws IfsException

Returns the number of rows in search result. Users can specify the bind values, session language and timeout value. Runs a select count(*) query to get the count. This does NOT cache the result. Repeated calls to this method in the same search object result in database query everytime. The number of items returned here is not guaranteed to match the number of items found, when the actual search is run. This is because, objects might be created or deleted between the time when getItemCount() is called and the actual search is run by calling open().

Parameters:

bindValues - array of late bound values

language - language to be used for the search

timeout - search will timeout after this amount of time; if 0, infinite timeout.

Returns:

Number of items in search result set.

Throws:

IfsException - if the operation fails.

(Published)

getSQL

public String getSQL()
              throws IfsException

Returns the SQL query generated by the search. Developers can use this to debug their search tree. The SQL generated does not have bind values filled in. These include the bind values used to handle security.

Returns:

the SQL generated by the search.

Throws:

IfsException - if the operation fails

(Published)

next

public SearchResultObject next()
                        throws IfsException

Returns the next result row. The result row is returned as a SearchResultObject. Depending on the SearchSepcification, the result row can contain one or more LibraryObjects, it also contains information about Context Scores.

Returns:

SearchResultObject corresponding to the next row of the cursor.

Throws:

IfsException - IFS-22000 if there is no more rows in the search results.

See Also:

SearchResultObject

(Published)

getItems

public SearchResultObject[] getItems()
                              throws IfsException

Returns the all the rows in the Search Result. Function provided for SimpleDoc.

Returns:

all rows in Search Result

Throws:

IfsException

(Unpublished)

getItems

public SearchResultObject getItems(int index)
                            throws IfsException

Returns the ith row in the Search Result. Function provided for SimpleDoc.

Returns:

ith row of Search Result

Throws:

IfsException

(Unpublished)

close

public void close()
           throws IfsException

Closes the search. You cannot get any more search results after calling this method. Closes the database cursor held by the search. All open() calls should have matching close() calls.

Throws:

IfsException - if operation fails

(Published)

dispose

public void dispose()
             throws IfsException

Disposes this Search.

Dispose a search to fully release its resources. If opened, the Search is closed. Once disposed, the Search cannot be reopened.

Throws:

IfsException - if the operation fails

(Published)

convertAttributeName

public static String convertAttributeName(ClassObject cls,
                                          String attrName)

Helper Functions used by Qualifiers to convert attribute names from old names to current names.

Parameters:

cls - attribute's class

attrName - attributeName

Returns:

converted name

(Unpublished)

verifyConnected

protected LibrarySession verifyConnected()
                                  throws IfsException

Ensure LibrarySession of this Search is valid.

Returns:

LibrarySession if it is valid

Throws:

IfsException - 21000 if session is invalid.

(Unpublished)

getResolvedItems

public LibraryObject[] getResolvedItems()
                                 throws IfsException

Returns the resolved objects for all the rows in the Search Result. Function provided for SimpleDoc.

Returns:

all rows in Search Result

Throws:

IfsException

(Unpublished)

getResolvedItems

public LibraryObject getResolvedItems(int index)
                               throws IfsException

Returns the resolved object for the ith row in the Search Result. Function provided for SimpleDoc.

Returns:

ith row of Search Result

Throws:

IfsException

(Unpublished)