com.arsdigita.search.intermedia
Class SearchSpecification

java.lang.Object
  com.arsdigita.search.intermedia.SearchSpecification

Direct Known Subclasses:

SearchSpecification, SimpleSearchSpecification

public class SearchSpecification

extends Object

This class is used to perform a search for content that has been indexed. Indexing of content is described in Searchable interface documentation.

To perform a search, there are two steps:

1. Specify the search by calling a constructor to create an object of this class. This requires specifying the SQL Select statement that makes up the search, and the names of the fields that will be returned. Pagination of the results can also be specified.
2. Execute the search by calling method getPage to return each page of search results.

The main task is the specification of the SQL Select statement. The SQL select statement should query the search_content table, and perhaps other joined tables. The following are the fields in the search_content table:

  object_id           integer primary key,
                      references acs_objects (object_id)
  object_type         varchar2(100),  -- Same as acs_objects(object_type)
  link_text           varchar2(1000),
  url_stub            varchar2(100),
  summary             varchar2(4000),
  xml_content         clob,
  raw_content         blob,
  language            varchar2(3)

Fields xml_content and raw_content contain the content that is indexed. Searching for content is done by selecting from these columns using the Oracle "contains" function. The xml_content field allows using the "within" operator to search for content within specified XML elements.

Example. Suppose an object has the following content indexed:

 xml_content:  <Article>
                 <title>Market Research</title>
                 <author>Ernest Johnston</author>
               </Article>

 raw_content:  Focus groups indicate ambivalence.

and that another table (article_info) has a field (publish_date) which indicates the date the article was published.

Then the following SQL statement could be used to search for a query string in the <title> attribute or raw_content field for articles that were published earler than the current date and order the results. '$queryString' symbolizes where the query string would be placed.

 select   object_id, link_text, url_stub, summary, score(1)+score(2) as score
    from  search_content sc, article_info ai
   where  (contains(xml_content, '$queryString within title', 1) > 0
              or contains(raw_content, '$queryString', 2) > 0)
     and  ai.publish_date < sysdate
     and  ai.article_id = sc.object_id
   order  by score desc
 

The columns that would need to be specified to the constructor are: object_id, link_text, url_stub, summary and score. They query would find the example object if the queryString was "market" or "ambivalence" (respectively through the title attribute and raw_content field) but not if the query string was "Ernest" since the author section is not searched. All attributes in the xml_content field can be searched by not including a "within" clause. Details of of the Oracle interMedia contains, within and score functions are described in Oracle8i Application Developer's Guide - XML and in Oracle8i interMedia Text Reference.

Version:

1.0

Author:

Jeff Teeters

See Also:

SearchDataQuery

Field Summary

static String

versionId

Constructor Summary

SearchSpecification(String sql, String[] columns)
Create a SearchSpecification object, using the default values for maxRows and rowsPerPage.

SearchSpecification(String sql, String[] columns, int maxRows, int rowsPerPage)
Create a SearchSpecification object.

Method Summary

String[]	getColumns() Get the columns names that the sql select returns.
int	getMaxResultRows() Get the maximum number of result rows that can be retrieved by the search.
DataQuery	getPage(int page) Execute a search, returning a page of search results.
Object	getParameter(String parameterName) Allows a caller to get a parameter value for a parameter that has already been set
int	getRowsPerPage() Get the maximum number of rows per result page returned by method getPage.
String	getSelect() Get the Sql select statement used to do a search.
protected String	reformatSqlForPage(int page) Build a new sql select statement, that is reformatted to select the specified page.
void	setMaxResultRows(int maxRows) Set the maximum number of result rows retrieved by the search.
void	setParameter(String name, Object value) Allows a user to bind a parameter within the query.
void	setRowsPerPage(int rowsPerPage) Set the maximum number of result rows retrieved by the search.
void	setSelect(String sql, String[] columns) Set the Sql select statement and columns used to do a search.

Methods inherited from class java.lang.Object

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

Field Detail

versionId

public static final String versionId

See Also:

Constant Field Values

Constructor Detail

SearchSpecification

public SearchSpecification(String sql,
                           String[] columns,
                           int maxRows,
                           int rowsPerPage)

Create a SearchSpecification object.

Parameters:

sql - Sql select statement to perform the search. See example above.

columns - The names of columns returned by the search.

maxRows - The maximum number of result rows retrieved by the search.

rowsPerPage - The maximum number of rows per result page returned by method getPage.

SearchSpecification

public SearchSpecification(String sql,
                           String[] columns)

Create a SearchSpecification object, using the default values for maxRows and rowsPerPage.

Parameters:

sql - Sql select statement to perform the search. See example above.

columns - The names of columns returned by the search.

Method Detail

setParameter

public void setParameter(String name,
                         Object value)

Allows a user to bind a parameter within the query.

Parameters:

name - The name of the parameter to bind

value - The value to assign to the parameter

getParameter

public Object getParameter(String parameterName)

Allows a caller to get a parameter value for a parameter that has already been set

Parameters:

parameterName - The name of the parameter to retrieve

Returns:

This returns the object representing the value of the parameter specified by the name or "null" if the parameter value has not yet been set.

setSelect

public void setSelect(String sql,
                      String[] columns)

Set the Sql select statement and columns used to do a search.

Parameters:

sql - Sql select statement to perform the search. See example above.

columns - The names of columns returned by the search.

setMaxResultRows

public void setMaxResultRows(int maxRows)

Set the maximum number of result rows retrieved by the search.

Parameters:

maxRows - The maximum number of result rows retrieved by the search.

setRowsPerPage

public void setRowsPerPage(int rowsPerPage)

Set the maximum number of result rows retrieved by the search.

Parameters:

rowsPerPage - The maximum number of rows per result page returned by method getPage.

getSelect

public String getSelect()

Get the Sql select statement used to do a search.

getColumns

public String[] getColumns()

Get the columns names that the sql select returns.

getMaxResultRows

public int getMaxResultRows()

Get the maximum number of result rows that can be retrieved by the search.

getRowsPerPage

public int getRowsPerPage()

Get the maximum number of rows per result page returned by method getPage.

reformatSqlForPage

protected String reformatSqlForPage(int page)

Build a new sql select statement, that is reformatted to select the specified page. This method would normally not be used by an application developer. It is a helper function for methods in this class or classes that extend it (e.g. SimpleSearchSpecification).

Example usage.
Input:

 select id, name from result_info order by substr(name,2,3)
 

Output:

 select * from
 (select temp_view.*, rownum as temp_rownum from
 (select id, name from result_info order by substr(name,2,3)) temp_view)
 where temp_rownum >= firstRow and temp_rownum <= lastRow
 

Notes:

• String "temp_" in the identifiers are replaced by an unlikely string to reduce chance of name conflicts.
• The first condition temp_rownum >= firstRow is left out if firstRow is 1.
• The lastRow is set to one more than the actual last row on the page (unless its the last page) so the calling routine can figure out if there is another page of search results.

getPage

public DataQuery getPage(int page)

Execute a search, returning a page of search results. If there is a "next page" of results after the returned page, the number of rows returned will be the number of rows per page plus one. This allows determining if a "next page" link should be generated by counting the number of rows returned; i.e. if the total is greater than rowsPerPage) then there is a next page, otherwise there is not. A row that flags the presence of a next page, should not be displayed to the user because it will be the first row returned on the next page.

Parameters:

page - The page of search results to retrieve (page==1 means first page).