Oracle Ultra Search APIs
9.0.1

oracle.context.isearch.query
Class QueryTool

java.lang.Object
  |
  +--oracle.context.isearch.query.QueryTool

public class QueryTool
extends java.lang.Object

This class implements the Ultra Search Java Query API.

It defines all constants and methods that facilitate querying an Ultra Search instance index.

The methods implemented by this API can be classified as follows:

Methods that retrieve data from the Ultra Search instance

These methods return data from the Ultra Search instance such as data group information, query attribute information and query result data. The addUrl method adds data into the Ultra Search instance.

The methods that fall under this class are as follows:

Methods that return HTML code or are related to the presentation of HTML code

These methods perform the following tasks:

The methods that fall under this class are as follows:

Ultra Search database session methods

These methods are related to the jdbc database session. They include setting the username, password and session language.

The methods that fall under this class are as follows:

Utility methods

These methods exist as convenience method for the client web application developer. They encapsulate commonly performed tasks.

The methods that fall under this class are as follows:

Since:
1.0.2.0.0

Field Summary
static int ADD_URL_DISABLED
          A constant that defines one of the eight return values of the addUrl method signifying that the add seed URL feature has been disabled by the Ultra Search Administrator.
static int ADD_URL_DUPLICATE_URL
          A constant that defines one of the eight return values of the addUrl method signifying that the user has attempted to add a seed URL that has already exists for the target web source
static int ADD_URL_INCORRECT_SOURCE_TYPE
          A constant that defines one of the eight return values of the addUrl method signifying that an attempt was made to add the seed URL to a data source other than a web data source.
static int ADD_URL_INTERNAL_ERROR
          A constant that defines one of the eight return values of the addUrl method signifying that an internal error occurred during the attempt to add a seed URL to a web data source.
static int ADD_URL_INVALID_URL
          A constant that defines one of the eight return values of the addUrl method signifying that an attempt was made to add an invalid seed URL to a web data source.
static int ADD_URL_NO_WEBDS
          A constant that defines one of the eight return values of the addUrl method signifying that there was no appropriate web data source to add the seed URL to.
static int ADD_URL_OK
          A constant that defines one of the eight return values of the addUrl method signifying that the addition of the URL to the seed URL list completed successfully.
static int ADD_URL_OUT_OF_SCOPE
          A constant that defines one of the eight return values of the addUrl method signifying that an was made to add a seed URL outside the URL scope of a web data source.
static int EMAIL_DATA_SOURCE
          A constant that defines the email data source type
static int FILE_DATA_SOURCE
          A constant that defines the file data source type
static int TABLE_DATA_SOURCE
          A constant that defines the table data source type
static int WEB_DATA_SOURCE
          A constant that defines the web data source type

 

Constructor Summary
QueryTool()
          Default constructor

 

Method Summary
 int addUrl(java.lang.String url)
          Use this method to add a URL to the seed URL list of all web sources.
 int addUrltoGroup(java.lang.String url, java.lang.String groupName)
          Use this method to add a URL to the seed URL list of all web sources belonging to a data group.
 int addUrltoSource(java.lang.String url, java.lang.String sourceName)
          Use this method to add a URL to the seed URL list of a specific web sources.
 java.lang.String createPageLinks(java.lang.String query, int currentPage, int hitCount, QueryAttribute[] queryAttributes, Item[] groups, java.lang.String language, java.lang.String resultTarget)
          Use this method to create the result page links that appear at the bottom of the screen under the result list.
 java.lang.String createQueryForm(java.lang.String action, java.lang.String query, QueryAttribute[] queryAttr, java.lang.String language, java.lang.String[] group, Item[] attrChoices, Item[] langChoices, Item[] groupChoices, java.lang.String queryTarget, java.lang.String resultTarget)
          Creates the HTML form for the query input.
 java.lang.String createResultTable(java.lang.String query, int page, QueryAttribute[] queryAttributes, Item[] groups, java.lang.String language)
          Use this method to create an HTML table of the query result.
 void displayFileUrl(javax.servlet.ServletRequest request, javax.servlet.ServletResponse response)
          Call this method to display the contents of a file data source document.
 void displayTableUrl(javax.servlet.ServletRequest request, javax.servlet.ServletResponse response)
          Call this method to display the contents of a table data source (database row cell).
 int estimateHitCount(java.lang.String query, QueryAttribute[] queryAttributes, Item[] groups, java.lang.String language)
          Gets an estimate count of hits that satisfy a query and its criteria.
 java.lang.String getAddMoreAttrButton()
          Gets the text for the label that invites the end-user to add more search attributes to the query.
 java.lang.String getAndOperator()
          Gets the text for the label that signifies the AND logical operator.
 java.lang.String getAnyLanguageLabel()
          Gets the text for the label that indicates that a query should search documents in all languages.
 Item[] getAttributes()
          Gets the list of Query Attributes that are defined in the Oracle Ultra Search instance.
 java.lang.String getAuthorFormat()
          Gets the text for the document author format string on the result page.
 java.lang.String getDataGroupFormat()
          Gets the data group score format string that deterimes how the data group is to be presented on each hit row.
 java.lang.String getFilePagePath()
          Gets the URL path of the web application (JSP or Servlet) that will render the contents of a file.
 java.lang.String getFromLabel()
          Sets the text for the label that indicates that a query is to be restricted to certain data groups.
 Item[] getGroups()
          Gets the list of Data Groups that are defined in the Oracle Ultra Search instance.
 int getHitsPerPage()
          Gets the number of hits to display per page.
 java.lang.String getLanguageLabel()
          Gets the text for the label that indicates that a query is to be restricted to a certain language.
 Item[] getLanguages()
          Gets the list of languages that Oracle Ultra Search understands.
 java.lang.String getLastModifiedFormat()
          Gets the text for the label last-modified date format string on the result page.
 java.lang.String getMailPagePath()
          Gets the URL path of the web application (JSP or Servlet) that will render the contents of an email.
 int getMaxPageNum()
          Gets the maximum page number that the getResult method returns.
 java.lang.String getNarrowedByLabel()
          Gets the text for the label that indicates a query is to be narrowed by certain criteria.
 java.lang.String getNoTitleString()
          Gets the text to show in place of the title of a document when a document does not have a title.
 java.lang.String getOrOperator()
          Gets the text for the label that signifies the OR logical operator.
 java.lang.String getPageCharset()
          Gets the character set of the Query Application.
 int getPageLinks()
          Gets the number of result page links.
 java.lang.String getPageSizeFormat()
          Gets the page size format string on result page.
 java.lang.String getParameter(javax.servlet.ServletRequest request, java.lang.String pname)
          Gets a parameter value from the incoming servlet request in the "iso-8859-1" character set.
 java.lang.String[] getParameterValues(javax.servlet.ServletRequest request, java.lang.String pname)
          Gets the parameter values from the incoming servlet request in the "iso-8859-1" character set.
static java.lang.String getPlsqlVersion()
           
 java.lang.String getQueryPagePath()
          Gets the query page path.
static java.lang.String getQueryVersion()
           
 java.lang.String getResourceFileName()
          Gets the name of the .properties file that contains the database resource settings.
 Document[] getResult(java.lang.String query, int startPointer, int recordsRequested, QueryAttribute[] queryAttributes, Item[] groups, java.lang.String language)
          Gets the query result based on certain query criteria.
 java.lang.String getScoreFormat()
          Gets the document relevance score format string.
 java.lang.String getSearchButton()
          Gets the text for the "Search" button label.
 java.lang.String getSearchForLabel()
          Gets the text for the "Search for" label on query form.
 java.lang.String getSessionLang()
          Gets the session language for the database SQL session.
 java.lang.String getTablePagePath()
          Gets the URL path of the web application (JSP or Servlet) that will render the contents of a table row cell.
 java.lang.String getUser()
          Gets the database username of the Ultra Search instance that should be accessed.
 java.lang.String htmlEncode(java.lang.String str)
          Convenience method for converting certain characters into HTML encoding.
 boolean isVersionCompatible()
           
 void setAddMoreAttrButton(java.lang.String str)
          The text for the label that invites the end-user to add more search attributes to the query.
 void setAndOperator(java.lang.String str)
          Sets the text for the label that signifies the AND logical operator.
 void setAnyLanguageLabel(java.lang.String str)
          Sets the text for the label that indicates that a query should search documents in all languages.
 void setAuthorFormat(java.lang.String str)
          Sets the document author format string on the result page.
 void setDataGroupFormat(java.lang.String str)
          Sets the data group format string.
 void setFilePagePath(java.lang.String str)
          Sets the URL path of the web application (JSP or Servlet) that will render the contents of a file row cell.
 void setFromLabel(java.lang.String str)
          Gets the text for the label that indicates that a query is to be restricted to certain data groups.
 void setHitsPerPage(int n)
          Sets the number of hits to display per page.
 void setLanguageLabel(java.lang.String str)
          Sets the text for the label that indicates that a query is to be restricted to a certain language.
 void setLastModifiedFormat(java.lang.String str)
          Gets the last-modified date format string on the result page.
 void setMailPagePath(java.lang.String str)
          Sets the URL path of the web application (JSP or Servlet) that will render the contents of an email.
 void setMaxPageNum(int n)
          Sets the maximum page number that the getResult method returns.
 void setNarrowedByLabel(java.lang.String str)
          Sets the text for the label that indicates a query is to be narrowed by certain criteria.
 void setNoTitleString(java.lang.String str)
          Sets the text to show in place of the title of a document when a document does not have a title
 void setOrOperator(java.lang.String str)
          Sets the text for the label that signifies the OR logical operator.
 void setPageCharset(java.lang.String str)
          Sets the character set of the Query Application.
 void setPageLinks(int n)
          Sets the number of result page links at the bottom of a search result page.
 void setPageSizeFormat(java.lang.String str)
          Sets the page size format string on result page.
 void setPassword(java.lang.String str)
          Sets the database username password of the Ultra Search instance that should be accessed.
 void setQueryPagePath(java.lang.String str)
          Sets the URL path to the JSP Query Application.
 void setResourceFileName(java.lang.String str)
          Sets the name of the .properties file that contains the database resource settings.
 void setScoreFormat(java.lang.String str)
          Sets the document relevance score format string.
 void setSearchButton(java.lang.String str)
          Sets the text for the "Search" button label.
 void setSearchForLabel(java.lang.String str)
          Gets the text for the "Search for" label on query form.
 void setSessionLang(java.lang.String str)
          Sets the session language for database SQL session.
 void setTablePagePath(java.lang.String str)
          Sets the URL path of the web application (JSP or Servlet) that will render the contents of a table row cell.
 void setUser(java.lang.String str)
          Sets the database username of the Ultra Search instance that should be accessed.
 java.lang.String urlEncode(java.lang.String str)
          Convenience method for returning a string in the "x-www-form-urlencoded" format.

 

Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

 

Field Detail

ADD_URL_OK

public static final int ADD_URL_OK
A constant that defines one of the eight return values of the addUrl method signifying that the addition of the URL to the seed URL list completed successfully.

ADD_URL_NO_WEBDS

public static final int ADD_URL_NO_WEBDS
A constant that defines one of the eight return values of the addUrl method signifying that there was no appropriate web data source to add the seed URL to.

ADD_URL_INVALID_URL

public static final int ADD_URL_INVALID_URL
A constant that defines one of the eight return values of the addUrl method signifying that an attempt was made to add an invalid seed URL to a web data source.

ADD_URL_DISABLED

public static final int ADD_URL_DISABLED
A constant that defines one of the eight return values of the addUrl method signifying that the add seed URL feature has been disabled by the Ultra Search Administrator.

ADD_URL_DUPLICATE_URL

public static final int ADD_URL_DUPLICATE_URL
A constant that defines one of the eight return values of the addUrl method signifying that the user has attempted to add a seed URL that has already exists for the target web source

ADD_URL_INCORRECT_SOURCE_TYPE

public static final int ADD_URL_INCORRECT_SOURCE_TYPE
A constant that defines one of the eight return values of the addUrl method signifying that an attempt was made to add the seed URL to a data source other than a web data source. Seed URLs can only be added to web data sources.

ADD_URL_OUT_OF_SCOPE

public static final int ADD_URL_OUT_OF_SCOPE
A constant that defines one of the eight return values of the addUrl method signifying that an was made to add a seed URL outside the URL scope of a web data source. The URL scope of a web data source is defined by its inclusion and exclusion domain settings.

ADD_URL_INTERNAL_ERROR

public static final int ADD_URL_INTERNAL_ERROR
A constant that defines one of the eight return values of the addUrl method signifying that an internal error occurred during the attempt to add a seed URL to a web data source.

WEB_DATA_SOURCE

public static final int WEB_DATA_SOURCE
A constant that defines the web data source type

FILE_DATA_SOURCE

public static final int FILE_DATA_SOURCE
A constant that defines the file data source type

TABLE_DATA_SOURCE

public static final int TABLE_DATA_SOURCE
A constant that defines the table data source type

EMAIL_DATA_SOURCE

public static final int EMAIL_DATA_SOURCE
A constant that defines the email data source type
Constructor Detail

QueryTool

public QueryTool()
Default constructor
Method Detail

setMailPagePath

public void setMailPagePath(java.lang.String str)
Sets the URL path of the web application (JSP or Servlet) that will render the contents of an email.
Parameters:
str - a portion of a URL string representing the mail rendering application.

getMailPagePath

public java.lang.String getMailPagePath()
Gets the URL path of the web application (JSP or Servlet) that will render the contents of an email.
Returns:
a portion of a URL string representing the mail rendering application.

setResourceFileName

public void setResourceFileName(java.lang.String str)
                         throws java.sql.SQLException
Sets the name of the .properties file that contains the database resource settings. The file that is shipped with Oracle Ultra Search is named database.properties.
Parameters:
str - the database resource filename
Throws:
java.sql.SQLException - when a database error occurs.

getResourceFileName

public java.lang.String getResourceFileName()
Gets the name of the .properties file that contains the database resource settings.
Returns:
the database resource filename

setUser

public void setUser(java.lang.String str)
Sets the database username of the Ultra Search instance that should be accessed.
Parameters:
str - This must be an Oracle database username.

getUser

public java.lang.String getUser()
Gets the database username of the Ultra Search instance that should be accessed.
Returns:
The Oracle database username.

setPassword

public void setPassword(java.lang.String str)
Sets the database username password of the Ultra Search instance that should be accessed.
Parameters:
str - This must be an Oracle database username password.

setQueryPagePath

public void setQueryPagePath(java.lang.String str)
Sets the URL path to the JSP Query Application.

For example, setting Query Page Path to '/ultrasearch/query/jsp/gsearch.jsp' implies that end-users will access the Sample JSP Query Application via the URL http://host:port/ultrasearch/query/jsp/gsearch.jsp

Parameters:
str - The query page path

getQueryPagePath

public java.lang.String getQueryPagePath()
Gets the query page path.
Returns:
a portion of a URL string representing the query page path.

setTablePagePath

public void setTablePagePath(java.lang.String str)
Sets the URL path of the web application (JSP or Servlet) that will render the contents of a table row cell.
Parameters:
str - a portion of a URL string representing the table rendering application.

getTablePagePath

public java.lang.String getTablePagePath()
Gets the URL path of the web application (JSP or Servlet) that will render the contents of a table row cell.
Returns:
a portion of a URL string representing the table rendering application.

setFilePagePath

public void setFilePagePath(java.lang.String str)
Sets the URL path of the web application (JSP or Servlet) that will render the contents of a file row cell.
Parameters:
str - a portion of a URL string representing the file rendering application.

getFilePagePath

public java.lang.String getFilePagePath()
Gets the URL path of the web application (JSP or Servlet) that will render the contents of a file.
Returns:
a portion of a URL string representing the file rendering application.

setSessionLang

public void setSessionLang(java.lang.String str)
Sets the session language for database SQL session.

The session language determines how Oracle Text choose a lexer to interpret the query string.

The session language is a string that the Oracle Server understands. This list can be found in the Oracle National Language Support Guide. The languages returned by the getLanguages method are not exactly the same as that which are needed by the Oracle Server. Do not use the languages returned by the getLanguages method.

Parameters:
str - Theh Oracle Server compatible language string.

getSessionLang

public java.lang.String getSessionLang()
Gets the session language for the database SQL session.
Returns:
the session language that the Oracle Server is using.

setPageCharset

public void setPageCharset(java.lang.String str)
Sets the character set of the Query Application.

This QueryTool class which runs in the middle-tier needs to know the character set used by the JSP page (that you, the customer are free to define). The reasons why the QueryTool class needs to know the character set include the following:

  1. The Ultra Search APIs that return HTML code encode parameter names and values into URLs. For proper encoding, these APIs need to know the character set of the page.
  2. Incoming parameters from HTTP requests need to be interpreted correctly. Without knowing the character set, they will not be interpreted correctly.
Parameters:
str - Specify an official IANA Registered character set. An example is "iso-2022-jp-2" or the common "iso-8859-1".

getPageCharset

public java.lang.String getPageCharset()
Gets the character set of the Query Application.
Returns:
The character set of the Query Application.

setMaxPageNum

public void setMaxPageNum(int n)
Sets the maximum page number that the getResult method returns. The default value is 20.
Parameters:
n - the maximum page number of the page links int a query result page.

getMaxPageNum

public int getMaxPageNum()
Gets the maximum page number that the getResult method returns.
Returns:
the maximum page number of the page links int a query result page.

setHitsPerPage

public void setHitsPerPage(int n)
Sets the number of hits to display per page. The default value is 10.
Parameters:
n - an integer denoting the number of hits to display per page

getHitsPerPage

public int getHitsPerPage()
Gets the number of hits to display per page. The default value is 10.
Returns:
an integer denoting the number of hits to display per page

setPageLinks

public void setPageLinks(int n)
Sets the number of result page links at the bottom of a search result page. These links allow the end-user to navigate to other pages that contain more search hits. Default value is 10.
Parameters:
n - an integer denoting the number of page links.

getPageLinks

public int getPageLinks()
Gets the number of result page links.
Returns:
an integer denoting the number of page links.

setSearchForLabel

public void setSearchForLabel(java.lang.String str)
Gets the text for the "Search for" label on query form. This label appears to the left of the search box in the basic and advanced query forms. Default value is "Search for".
Parameters:
str - The text for the label.

getSearchForLabel

public java.lang.String getSearchForLabel()
Gets the text for the "Search for" label on query form.
Returns:
The text for the label.

setNoTitleString

public void setNoTitleString(java.lang.String str)
Sets the text to show in place of the title of a document when a document does not have a title
Parameters:
str - The text to show when there is no title

getNoTitleString

public java.lang.String getNoTitleString()
Gets the text to show in place of the title of a document when a document does not have a title.
Returns:
The text for the label.

setSearchButton

public void setSearchButton(java.lang.String str)
Sets the text for the "Search" button label. This is the label of the button that the user clicks on to submit a query. It appears in both the basic and advanced query forms. Default value is "Search".
Parameters:
str - The text for the label.

getSearchButton

public java.lang.String getSearchButton()
Gets the text for the "Search" button label.
Returns:
The text for the label.

setNarrowedByLabel

public void setNarrowedByLabel(java.lang.String str)
Sets the text for the label that indicates a query is to be narrowed by certain criteria. This label appears on the advanced query form. Default value is 'Narrowed by'.
Parameters:
str - The text for the label.

getNarrowedByLabel

public java.lang.String getNarrowedByLabel()
Gets the text for the label that indicates a query is to be narrowed by certain criteria.
Returns:
The text for the label.

setFromLabel

public void setFromLabel(java.lang.String str)
Gets the text for the label that indicates that a query is to be restricted to certain data groups. This label appears on the advanced query form. Default value is 'From'.
Parameters:
str - The text for the label.

getFromLabel

public java.lang.String getFromLabel()
Sets the text for the label that indicates that a query is to be restricted to certain data groups.
Returns:
The text for the label.

setLanguageLabel

public void setLanguageLabel(java.lang.String str)
Sets the text for the label that indicates that a query is to be restricted to a certain language. This label appears on the advanced query form. Default value is 'Language'.
Parameters:
str - The text for the label.

getLanguageLabel

public java.lang.String getLanguageLabel()
Gets the text for the label that indicates that a query is to be restricted to a certain language.
Returns:
The text for the label.

setAnyLanguageLabel

public void setAnyLanguageLabel(java.lang.String str)
Sets the text for the label that indicates that a query should search documents in all languages. This label appears on the advanced query form. Default value is 'any language'.
Parameters:
str - The text for the label.

getAnyLanguageLabel

public java.lang.String getAnyLanguageLabel()
Gets the text for the label that indicates that a query should search documents in all languages.
Returns:
The text for the label.

setAddMoreAttrButton

public void setAddMoreAttrButton(java.lang.String str)
The text for the label that invites the end-user to add more search attributes to the query. This label appears on the advanced query form. Default value is 'Add more attributes'.
Parameters:
str - The text for the label.

getAddMoreAttrButton

public java.lang.String getAddMoreAttrButton()
Gets the text for the label that invites the end-user to add more search attributes to the query.
Returns:
The text for the label.

setAndOperator

public void setAndOperator(java.lang.String str)
Sets the text for the label that signifies the AND logical operator. This label appears on the advanced query form. Default value is 'And'.
Parameters:
str - The text for the label.

getAndOperator

public java.lang.String getAndOperator()
Gets the text for the label that signifies the AND logical operator.
Returns:
The text for the label.

setOrOperator

public void setOrOperator(java.lang.String str)
Sets the text for the label that signifies the OR logical operator. This label appears on the advanced query form. Default value is 'Or'.
Parameters:
str - The text for the label.

getOrOperator

public java.lang.String getOrOperator()
Gets the text for the label that signifies the OR logical operator.
Returns:
The text for the label.

setAuthorFormat

public void setAuthorFormat(java.lang.String str)
Sets the document author format string on the result page. This string defines how the author information should appear for each document. Default value is 'Author: %s'. The token '%s' is replaced by the actual author's name.
Parameters:
str - The text for the document author format string.

getAuthorFormat

public java.lang.String getAuthorFormat()
Gets the text for the document author format string on the result page.
Returns:
The text for the document author format string.

setLastModifiedFormat

public void setLastModifiedFormat(java.lang.String str)
Gets the last-modified date format string on the result page. This string defines how the date format string should appear for each document. Default value is 'Last Modified: %s'. The token '%s' is replaced by the actual last-modifed date of the document.
Parameters:
str - The text for the last-modified date format string.

getLastModifiedFormat

public java.lang.String getLastModifiedFormat()
Gets the text for the label last-modified date format string on the result page.
Returns:
The last-modified date format string.

setPageSizeFormat

public void setPageSizeFormat(java.lang.String str)
Sets the page size format string on result page. This string defines how the page size string should appear for each document. Default value is 'Page Size: %s bytes'. The token '%s' is replaced by the actual document size.
Parameters:
str - The page size format string.

getPageSizeFormat

public java.lang.String getPageSizeFormat()
Gets the page size format string on result page.
Returns:
The page size format string.

setDataGroupFormat

public void setDataGroupFormat(java.lang.String str)
Sets the data group format string. This string defines how the data group should appear for each document. Default value is 'From: %s'. The token '%s' is replaced by the data group name.
Parameters:
str - The data group format string.

getDataGroupFormat

public java.lang.String getDataGroupFormat()
Gets the data group score format string that deterimes how the data group is to be presented on each hit row.
Returns:
The data group format string.

setScoreFormat

public void setScoreFormat(java.lang.String str)
Sets the document relevance score format string. This string defines how the relevance score should appear for each document. Default value is 'Score: <FONT color=red>%s</FONT>'. The token '%s' is replaced by the actual document score.
Parameters:
str - The document relevance score format string.

getScoreFormat

public java.lang.String getScoreFormat()
Gets the document relevance score format string.
Returns:
The document relevance score format string.

getParameter

public java.lang.String getParameter(javax.servlet.ServletRequest request,
                                     java.lang.String pname)
                              throws java.io.UnsupportedEncodingException
Gets a parameter value from the incoming servlet request in the "iso-8859-1" character set.

Browsers can send text encoded in various character sets. However, the JSP engine always interprets it in the "iso-8859-1" character set. Therefore, the JSP or Servlet web application always needs to convert the incoming parameters into the "iso-8859-1" character set.

This method is supplied as a convenience utility method that can be called by your JSP or Servlet web application.

Parameters:
request - The incoming Servlet request
pname - The parameter name
Returns:
The parameter value in the "iso-8859-1" character set.
Throws:
java.io.UnsupportedEncodingException - when strings that are part of an unsupported encoding are detected.

getParameterValues

public java.lang.String[] getParameterValues(javax.servlet.ServletRequest request,
                                             java.lang.String pname)
                                      throws java.io.UnsupportedEncodingException
Gets the parameter values from the incoming servlet request in the "iso-8859-1" character set.

Browsers can send text encoded in various character sets. However, the JSP engine always interprets it in the "iso-8859-1" character set. Therefore, the JSP or Servlet web application always needs to convert the incoming parameters into the "iso-8859-1" character set. This method is supplied as a convenience utility method that can be called by your JSP or Servlet web application.

Parameters:
request - The incoming Servlet request
pnamem - The parameter name
Returns:
An array of parameter values in the "iso-8859-1" character set.
Throws:
java.io.UnsupportedEncodingException - when strings that are part of an unsupported encoding are detected.

getLanguages

public Item[] getLanguages()
                    throws java.sql.SQLException
Gets the list of languages that Oracle Ultra Search understands.

The languages returned by this method are not exactly the same as those needed by the getSessionLang method.

This method is especially useful for displaying a list of easily-readable languages to the end-user. Typically, this list is displayed to the end-user who selects a language to search in.

Returns:
An array of Item objects where each Item object represents information about one language.
Throws:
java.sql.SQLException - when a database error occurs.

getGroups

public Item[] getGroups()
                 throws java.sql.SQLException
Gets the list of Data Groups that are defined in the Oracle Ultra Search instance.

The Data Groups are defined via the Administration Tool.

Returns:
An array of Item objects where each Item object represents information about one Data Group.
Throws:
java.sql.SQLException - when a database error occurs.

getAttributes

public Item[] getAttributes()
                     throws java.sql.SQLException
Gets the list of Query Attributes that are defined in the Oracle Ultra Search instance.

The Query Attributes are defined via the Administration Tool.

Returns:
An array of Item objects where each Item object represents information about one query attribute.
Throws:
java.sql.SQLException - when a database error occurs.

getResult

public Document[] getResult(java.lang.String query,
                            int startPointer,
                            int recordsRequested,
                            QueryAttribute[] queryAttributes,
                            Item[] groups,
                            java.lang.String language)
                     throws java.io.UnsupportedEncodingException,
                            java.sql.SQLException
Gets the query result based on certain query criteria.

The input arguments specify the criteria for this query. They include the query attributes, data groups to search in and the language to restrict the search to.

The startPointer and recordsRequested parameters are used to determine which records to return.

A note about the queryAttributes argument:

queryAttributes is an array of QueryAttribute objects that represent query attributes which the documents returned by the query must comply to.

For example, the following settings specify documents which contain 'Oracle' in the Title attribute and 'John' in the Author attribute:

queryAttributes[1].id = 45; // fictional id of 'Title' attribute
queryAttributes[1].query = 'Oracle'; // the value of the 'Title' attribute
queryAttributes[1].operator = 'And'; //
queryAttributes[2].id = 46; // fictional id of 'Author' attribute
queryAttributes[2].query = 'John'; // the value of the 'Author' attribute
queryAttributes[2].operator = 'And'; //

Parameters:
query - The query string.
startPointer - The first document of the hit list to obtain. For example, specifying 3 means that the first two documents will be ignored.
recordsRequested - The number of documents to be returned.
queryAttributes - An array of QueryAttribute objects.
groups - An array of Item objects where each Item object encapsulates information identifying a Data Group which the user wants to restrict the search to.
language - The language of the documents that should be searched.
Returns:
An array of Document objects where each Document object encapsulates information about a document that matches the query criteria.
Throws:
java.sql.SQLException - when a database error occurs.
java.io.UnsupportedEncodingException - when strings that are part of an unsupported encoding are detected.

estimateHitCount

public int estimateHitCount(java.lang.String query,
                            QueryAttribute[] queryAttributes,
                            Item[] groups,
                            java.lang.String language)
                     throws java.sql.SQLException
Gets an estimate count of hits that satisfy a query and its criteria.
Parameters:
query - The query string.
queryAttributes - An array of QueryAttribute objects where each object represents a query attribute that the documents returned by the query must comply to.
groups - An array of Item objects where each Item object encapsulates information identifying a Data Group which the user wants to restrict the search to.
language - The language of the documents that should be searched.
Returns:
An estimate count of the hits that satisfy the query.
Throws:
java.sql.SQLException - when a database error occurs.

createQueryForm

public java.lang.String createQueryForm(java.lang.String action,
                                        java.lang.String query,
                                        QueryAttribute[] queryAttr,
                                        java.lang.String language,
                                        java.lang.String[] group,
                                        Item[] attrChoices,
                                        Item[] langChoices,
                                        Item[] groupChoices,
                                        java.lang.String queryTarget,
                                        java.lang.String resultTarget)
Creates the HTML form for the query input. The form is composed of a title bar, a basic search text input box, input boxes for attributes, a data group check box, and a language pull down menu. By specifying values of various input parameters such as the query string, groups or attributes, you can cause the generated form to have preset values. This is useful when you want your search application to "remember" its last query. This method returns an HTML formatted string, which contains the fields you specify. The action parameter determines what action the query application will perform when the form is submitted.

There are two possible actions that can be specified. These are determined by the values of the contants SEARCH_BUTTON and ADD_MORE_ATTR_BUTTON.

If the action parameter value is equal to the SEARCH_BUTTON constant, this causes the query application to perform a query.

If it is equal to the ADD_MORE_ATTR_BUTTON constant, the query application to redraws the form with one more attribute line that enables the end-user to add another attribute requirement.

Parameters:
action - The action form parameter value.
query - The query string to display. Defaults to an empty string.
queryAttr - An array of QueryAttribute objects where each object represents a query attribute setting to display in the HTML form.
language - The language of the documents that should be selected in the HTML form.
groups - An array of Item objects where each Item object encapsulates information identifying a Data Group which should be selected in the HTML form.
attrChoices - An array of Item objects that specifies the attribute list that the query form displays to the end-user.
langChoices - An array of Item objects that specifies the language list that the query form displays to the end-user.
groupChoices - An array of Item objects that specifies the group list that the query form displays to the end-user.
queryTarget - The query form target frame name. This parameter is used when there is a specific HTML frame where the query form should be placed in.
resultTarget - The query result target frame. This parameter is used when there is a specific HTML frame where the query result text should be placed in. It causes the HTML anchor tags to specify the target attribute as the resultTarget frame.
Returns:
A string representing an HTML form matching the various input criteria.

createResultTable

public java.lang.String createResultTable(java.lang.String query,
                                          int page,
                                          QueryAttribute[] queryAttributes,
                                          Item[] groups,
                                          java.lang.String language)
                                   throws java.io.UnsupportedEncodingException,
                                          java.sql.SQLException
Use this method to create an HTML table of the query result. This method returns an HTML formatted string. The HTML formatted string contains the query result set ordered by relevance.
Parameters:
query - The query string.
page - Specifies which result page to create HTML for. Different pages contain different hit results. The number of hits per page is controlled via the setHitsPerPage and getHitsPerPage methods.
queryAttributes - An array of QueryAttribute objects where each object represents a query attribute that the documents returned by the query must comply to.
groups - An array of Item objects where each Item object encapsulates information identifying a Data Group which the user wants to restrict the search to.
language - The language of the documents that should be searched.
Returns:
A string representing an HTML table that when rendered will display the hit results in a table.
Throws:
java.sql.SQLException - when a database error occurs.
java.io.UnsupportedEncodingException - when strings that are part of an unsupported encoding are detected.

urlEncode

public java.lang.String urlEncode(java.lang.String str)
                           throws java.io.UnsupportedEncodingException
Convenience method for returning a string in the "x-www-form-urlencoded" format. This method is especially useful to formulate standard URLs that
Parameters:
The - input string to convert.
Returns:
The string converted to the "x-www-form-urlencoded" format.
Throws:
java.io.UnsupportedEncodingException - when the input string is in an unsupported encoding.

htmlEncode

public java.lang.String htmlEncode(java.lang.String str)
Convenience method for converting certain characters into HTML encoding.

This method analyzes the input string and performs the following conversions:

Parameters:
str - The input string to convert.
Returns:
The converted version of the input string.

createPageLinks

public java.lang.String createPageLinks(java.lang.String query,
                                        int currentPage,
                                        int hitCount,
                                        QueryAttribute[] queryAttributes,
                                        Item[] groups,
                                        java.lang.String language,
                                        java.lang.String resultTarget)
                                 throws java.io.UnsupportedEncodingException,
                                        java.sql.SQLException
Use this method to create the result page links that appear at the bottom of the screen under the result list. Query users use these links to browse the query result pages. This method returns an HTML formatted string that contains multiple anchor tag sets that represent links to other pages.

The hitcount is used to calculate the number of page links to display. The number of page links is the hitCount divided by the number of hits per page or the max page number, whichever is smaller.

If the hitCount is set to 0, this method will attempt to calculate the hitCount account to the query criteria - which means it will take longer to return.

Parameters:
query - The query string.
currentPage - The current page number.
hitCount - The estimated hit count for this query.
queryAttributes - An array of QueryAttribute objects where each object represents a query attribute which was specified in the search. Query attribute information is used to when calculating the hitCount and also in forming the URLs to other pages.
groups - An array of Item objects where each Item object encapsulates information identifying a Data Group which the user specified in the search. Data Group information is used to when calculating the hitCount and also in forming the URLs to other pages.
language - The language of the documents that was searched. language information is used to when calculating the hitCount and also in forming the URLs to other pages.
resultTarget - The query result target frame. This parameter is used when there is a specific HTML frame where the query result text should be placed in. It causes the HTML anchor tags to specify the target attribute as the resultTarget frame.
Returns:
A string containing HTML code that represents links to other result pages.
Throws:
java.sql.SQLException - when a database error occurs.
java.io.UnsupportedEncodingException - when strings that are part of an unsupported encoding are detected.

addUrl

public int addUrl(java.lang.String url)
           throws java.sql.SQLException
Use this method to add a URL to the seed URL list of all web sources. Adding a seed URL may alter the scope of the Ultra Search Crawler for the relevant web sources, resulting in more documents being crawled. This feature is especially useful if you want to enable the end-users to add their own websites to the seed URL list. The Ultra Search Administrator has the ability to toggle this feature on or off. This is done via the Ultra Search Administration Tool.

The return value is a string constant of one of the following 8 values:

Please see the descriptions for these public static string constants for more details.
Parameters:
url - The URL to add to the seed URL list for web crawling.
Returns:
A string constant that represents the result code of the addUrl operation.
Throws:
java.sql.SQLException - when a database error occurs.

addUrltoSource

public int addUrltoSource(java.lang.String url,
                          java.lang.String sourceName)
                   throws java.sql.SQLException
Use this method to add a URL to the seed URL list of a specific web sources. See the addUrltoSource method for adding a seed URL to all web sources for more information.
Parameters:
url - The URL to add to the seed URL list for web crawling.
sourceName - The name of the web data source to add the seed URL to.
Returns:
A string constant that represents the result code of the addUrl operation.
Throws:
java.sql.SQLException - when a database error occurs.

addUrltoGroup

public int addUrltoGroup(java.lang.String url,
                         java.lang.String groupName)
                  throws java.sql.SQLException
Use this method to add a URL to the seed URL list of all web sources belonging to a data group. See the addUrltoSource method for adding a seed URL to all web sources for more information.
Parameters:
url - The URL to add to the seed URL list for web crawling.
groupName - The name of the web data group containing specific web sources to add the seed URL to.
Returns:
A string constant that represents the result code of the addUrl operation.
Throws:
java.sql.SQLException - when a database error occurs.

displayTableUrl

public void displayTableUrl(javax.servlet.ServletRequest request,
                            javax.servlet.ServletResponse response)
                     throws java.io.IOException,
                            java.sql.SQLException
Call this method to display the contents of a table data source (database row cell).

This method makes a database call which returns the contents the database row cell. The table may reside on a separate database which must be accessible by the Ultra Search database via a database link.

Parameters:
request - The incoming Servlet request object containing all request data.
response - The outgoing Servlet response object whose PrintWriter this method will print text to.
Throws:
java.io.IOException - when an error occurs during printing of text to the response object's PrintWriter.
java.sql.SQLException - when a database error occurs.

getPlsqlVersion

public static java.lang.String getPlsqlVersion()

getQueryVersion

public static java.lang.String getQueryVersion()

isVersionCompatible

public boolean isVersionCompatible()
                            throws java.sql.SQLException

displayFileUrl

public void displayFileUrl(javax.servlet.ServletRequest request,
                           javax.servlet.ServletResponse response)
                    throws java.io.IOException,
                           java.sql.SQLException
Call this method to display the contents of a file data source document.

This method makes a database call which returns the contents of the file. Therefore, the file must be accessible by the database server.

Parameters:
request - The incoming Servlet request object containing all request data.
response - The outgoing Servlet response object whose PrintWriter this method will print text to.
Throws:
java.io.IOException - when an error occurs during printing of text to the response object's PrintWriter.
java.sql.SQLException - when a database error occurs.

Oracle Ultra Search APIs
9.0.1