Oracle Ultra Search Online Documentation
Release 9.2


Home	Book List	Contents	Master Index	Feedback

Ultra Search Query Tag Library

	Related Topics
About the Ultra Search Sample Query Applications

On top of the Java Query API, Ultra Search provides a JSP tag library as an alternative for developing search applications. Based on the Sun Microsystems Java Server Pages specification version 1.1, the Ultra Search tag library better separates the dynamic/Java development effort from the static/HTML development effort, and enables Web developers who are unfamiliar with Java to incorporate search functionality into their applications.

The Ultra Search tag library provides a subset of the features in the Java Query API. Advanced features, such as custom query expansion and URL submission, are not available as tags. The main features of the tag library are the following:

Ability to retrieve search attributes, groups, languages, and LOVs for rendering the advance query form

Ability to iterate through the resulting hit set, and retrieve document attributes and properties for rendering the result page

The tag library is summarized in following table:

Tag Description Attributes

instance This tag establishes a connection to an Ultra Search instance. instanceId
username
password
URL
dataSourceName
tablePagePath
emailPagePath
filePagePath

showAttributes For an advanced query, use this tag to show the list of attributes available. instance
locale

showGroups For an advanced query, use this tag to show the list of groups. instance
locale

showLanguages For an advanced query, use this tag to show the list of languages defined in the instance. instance

showLOV Show all values defined for a search attribute. instance
locale
attributeName
attributeType

getResult Perform the search. resultId
instance
query
queryLocale
documentLanguage
from
to
boostTerm
withCount

fetchAttribute This is a nested tag within getResult to specify which attributes of each document should be fetched along with the query results. There can be any number of nested fetchAttribute tags. attributeName
attributeType

showHitCount If withCount="true" in the getResult tag, then the result includes a total number of hits, and you can use showHitCount to display this number. result

showResults Renders the results of the search. result
instance

showAttributeValue Renders a document attribute. attributeName
attributeType

Details of these tags are described in the following subsections. Note the following requirements for using Ultra Search tags:

Install the file ultrasearch_query.jar and include it in classpath or the WEB-INF/lib directory of the Web application. This file is provided with the Ultra Search installation under the ultrasearch/lib directory.

Make sure that the tag library description file, ultrasearch-taglib.tld, is deployed with the application and is in the location specified in the taglib directives of your JSP pages, such as in the following example:
<%@ taglib uri="/WEB-INF/ultrasearch-taglib.tld" prefix="US" %>

The Ultra Search tag library definition (TLD) file can be found in $ORACLE_HOME/ultrasearch/sample/query/WEB-INF/ultrasearch-taglib.tld after sample.ear has been deployed. It is also packaged with ultrasearch_query.jar under the name META-INF/taglib.tld.

Tag	Description	Attributes
instance	This tag establishes a connection to an Ultra Search instance.	instanceId username password URL dataSourceName tablePagePath emailPagePath filePagePath
showAttributes	For an advanced query, use this tag to show the list of attributes available.	instance locale
showGroups	For an advanced query, use this tag to show the list of groups.	instance locale
showLanguages	For an advanced query, use this tag to show the list of languages defined in the instance.	instance
showLOV	Show all values defined for a search attribute.	instance locale attributeName attributeType
getResult	Perform the search.	resultId instance query queryLocale documentLanguage from to boostTerm withCount
fetchAttribute	This is a nested tag within `getResult` to specify which attributes of each document should be fetched along with the query results. There can be any number of nested `fetchAttribute` tags.	attributeName attributeType
showHitCount	If `withCount="true"` in the `getResult` tag, then the result includes a total number of hits, and you can use `showHitCount` to display this number.	result
showResults	Renders the results of the search.	result instance
showAttributeValue	Renders a document attribute.	attributeName attributeType

Tag Descriptions

The following sections describes each Ultra Search tag, its attributes, and action. Examples are shown without any static HTML, which can be inserted to format the output.
<instance> Tag: Connecting to the Ultra Search Instance
The Instance tag establishes a connection to an Ultra Search instance. Some basic parameters must be established in order for this tag to work, such as JDBC connection string, schema username/password, Ultra Search instance name, and so on.
tag attributes

instanceId="name"

This attribute names the instance defined by this tag. This name is then used by other Ultra Search tags to specify the instance being searched.

username

This creates a database connection.

password

This creates a database connection.

url

Gets the URL used to create a JDBC connection. This attribute is optional if dataSourceName is specified.

dataSourceName

The JNDI name that identifies a JDBC data source. Users should set either the URL or data source name properties. This is optional if URL is specified.

instanceName

The name of the Ultra Search instance that is owned by the schema user. If the schema user owns only one Ultra Search instance, this is optional.

tablePagePath

The URL path of the Web application that renders the contents of a database table.

emailPagePath

The URL path of the Web application that renders the contents of an email.

filePagePath

The URL path of the Web application that renders the contents of a file.

tag action
This tag defines a scripting variable of the name set by the instanceId property. All the other tag properties correspond to a property in the oracle.ultrasearch.query.QueryInstance class. Either the URL or dataSourceName attribute should be set. They are exclusive of each other.
example
The following example uses the URL property to connect to the database.
<US:instance 
 instanceId="mybookstore"
 url="oracle:jdbc:thin:@dbhost:1521:inst1"
 username="scott"
 password="tiger"
 tablePage="../display.jsp"
 emailPage="../mail.jsp"
 filePage="../display.jsp"
/>
<iterAttributes> Tag: Show All Search Attributes
When a user wants to perform an advanced query, the application needs to show the list of attributes that are available, the list of groups, and the list of languages defined in the instance. This can be done using some iteration tags that define script variables for page rendering.
Each attribute in Ultra Search has a name, a type, and a display name that is translated depending on the locale that is set for the QueryInstance tag. The attribute type should be used to determine which operators can be used on this attribute and how to parse the user's input.

tag attributes

instance="name"

This is a mandatory attribute to refer to the object defined by the instance tag.

locale="locale"

This determines the display name fetched using this tag.

tag action
This tag is an iteration tag. It loops through all the search attributes in the instance referred to by the instance tag attribute. In each loop, it defines a scripting variable named "attribute", which is an oracle.ultrasearch.query.Attribute object. It also defines a string variable named "displayname", which is the localized name of the attribute.
example
The following example shows all the attributes in "mybookstore" instance, using their English display names.
<US:iterAttributes instance="mybookstore" locale="<%=Locale.ENGLISH%>" >
<%= attribute %>
<%= displayname %>
</US:iterAttributes>
<iterGroups> Tag: Show All Search Groups
Similar to the showAttributes tag, the showGroups tag iterates through all the groups defined in an instance.
tag attributes

instance="name"

This a mandatory attribute to refer to the object defined by the instance tag.

locale="locale"

This attribute determines the display name fetched using this tag.

tag action
This tag is an iteration tag. It loops through all the search groups in the instance referred to by the instance tag attribute. In each loop, it defines a scripting variable named "group", which is an oracle.ultrasearch.query.Group object. It also defines a string variable named "displayname", which is the localized name of the group.
example
The following example shows all the groups in "mybookstore" instance, using their English display names.
<US:iterGroups instance="mybookstore" locale="<%=Locale.ENGLISH%>" >
<%= group %>
<%= displayname %>
</US:iterGroups >
<iterLanguages> Tag: Show All Search Languages
Similar to the showAttributes tag, the showLanguages tag iterates through all the languages defined in an instance. Because each language is defined by a java.util.Locale object, their display names are not handled by Ultra Search. Therefore, this tag does not define the displayname scripting variable.
tag attributes

instance="name"

This is a mandatory attribute to refer to the object defined by the instance tag.

tag action
This tag is an iteration tag. It loops through all the search languages in the instance referred to by the instance tag attribute. In each loop, it defines a scripting variable named "language", which is a java.util.Locale object. The display name for the language is provided by Java as a property of the object itself (through the getDisplayName() method).
example
The following example shows all the languages in "mybookstore" instance, using their English display names.
<US:iterLanguages instance="mybookstore">
<%= language %>
<%= language.getDisplayName (Locale.ENGLISH) %>
</US:iterLanguages >
<iterLOV> Tag: Show All Values Defined for a Search Attribute

tag attributes

instance="name"

This a mandatory attribute to refer to the object defined by the instance tag.

locale="locale"

This determines the display name fetched using this tag.

attributeName="attname"

The name of the attribute whose LOV is being fetched in this LOV.

attributeType="string | number | date"

The type of the attribute whose LOV is being fetched in this LOV. This is needed because attribute name does not uniquely identify an attribute in the instance.

tag action
This tag is an iteration tag. It loops through all the values in a search attribute's LOV. In each loop, it defines a scripting variable named "value", which is either a java.lang.String, java.util.Date, or java.math.BigDecimal object, depending on the attribute type. It also defines a string variable named "displayname", which is the localized display name of the value.
example
The following example shows all the values for a string attribute named "Dept" in "mybookstore" instance, using their English display names.
<US:iterLOV instance="mybookstore" attribute_name="Dept" attribute_type="String" >
<%= value %>
<%= displayname %>
</US:iterLOV >
Formulating the Query
Ultra Search supports a set of classes for building queries. Currently these classes do not have any tag equivalents. See [Decisions] section for rationale.
<getResult> Tag: Perform Search
<getResult> tag performs the search and returns the result by defining a scripting variable of the type oracle.ultrasearch.query.Result.
tag attributes

resultId="name"

This names the result generated by this tag. This name is then used by other tags to render the result on the page.

instance="name"

This is a mandatory attribute to refer to the object defined by the instance tag.

query="<%= expression %>"

This specifies a Query object to search with.

queryLocale="locale"

This specifies the locale of the Query object.

documentLanguage="locale"

This specifies the language of the documents to search for. This is optional. If it is not specified, then all languages are included in the search.

from="number"

This specifies the index of the first hit.

to="number"

This specifies the index of the last hit.

boostTerm="string"

This specifies the search term that will be used for relevance boosting. This is optional.

withCount="true | false"

This specifies whether the result will have an estimate of the total hit count. This is optional. If unspecified, the behavior is same as withCount=false.

tag action
The <getResult> tag corresponds to the getResult() method on the oracle.ultrasearch.query.Instance class. The attributes of tag maps to the parameters of the method straightforwardly, with the exception that getResult() method can specify the attributes to fetch. The <getResult> tag require the use of the nested <fetchAttribute> tag to accomplish metadata selection.
example
The following example shows a search for the first 20 documents of a query in English that appears in French documents.
<US:getResult 
 resultId="searchresult"
 instance="mybookstore"
 query="<%= query %>"
 queryLocale="<%= Locale.ENGLISH %>"
 documentLanguage="<%= Locale.FRENCH %>"
 from="1" to="20">
</US:getResult>
<fetchAttribute> Tag: Meta-data Selection
<fetchAttribute> tag is used as nested tag inside <getResult>. It specifies which attributes of each document should be fetched along with the query result. Each <getResult> can have any number of nested <fetchAttribute> tags.
tag attributes

attributeName="attname"

The name of the attribute whose LOV is being fetched in this LOV.

attributeType="string | number | date"

The type of the attribute whose LOV is being fetched in this LOV. This is needed because attribute name does not uniquely identify an attribute in the instance.

tag action
Each occurance of the <fetchAttribute> adds to the list of attributes passed to the getResult() invoked by the <getResult> tag.
example
The following example shows the same search in <getResult> tag, but fetching title and publication-date attributes of each book.
<US:getResult 
 resultId="searchresult"
 instance="mybookstore"
 query="<%= query %>"
 queryLocale="<%= Locale.ENGLISH %>"
 documentLanguage="<%= Locale.FRENCH %>"
 from="1" to="20">

<US:fetchAttribute 
 attributeName="title"
 attributeType="string" />

<US:fetchAttribute 
 attributeName="publication-date"
 attributeType="date" />

</US:getResult>
<showHitCount> Tag: Show Estimated Hit Count
After the search is performed, the result needs to be rendered. If withCount=true is in the <US:getResult> tag, then the result contains a count of total hits, and <showHitCount> tag can be used to display it.
tag attributes

result="name"

This refers to the resultId specified in the <US:getResult> tag.

tag action
This tag simply outputs the hit count to the page.
example
The following shows the hit count of the a search result.
<US:showHitCount result="searchresult" />
<iterResult> Tag: Render the Results
This tag is an iteration tag. It loops through all the documents in a search result.
tag attributes

result="name"

This refers to the resultId specified in the <US:getResult> tag.

instance="name"

This used refers to the instanceId specified in the <US:instance> tag.

tag action
The tag loops through all the documents in a search result and defines a scripting variable "doc" that is a oracle.ultrasearch.query.Document object. In addition, it can have nested tags of <showAttributeValue>, which helps to render the document's attributes. It is an error if the result specified is not one obtained from search on the instance specified. In other words, the result must come from the instance.
example
The following shows the URL of all documents in a search result.
<US:iterResult
result="searchresult" 
instance="mybookstore">

<%= doc.getUrl() %>

</US:iterResult>
<showAttributeValue> Tag: Render a Document Attribute
This tag shows an attribute of a document with in the <US:iterResult> tag.
tag attributes

attributeName="attname"

The name of the document attribute.

attributeType="string | number | date"

The type of the document attribute. This is needed because attribute name does not uniquely identify an attribute in the instance.

default="default string"

A value to output when the document has no value for this attribute. This is useful when a document has no title. The string "No Title" can be displayed as the default value.

tag action
This tag looks up the document attribute value and renders it on the page. If the attribute was not fetched as part of the search result, then nothing is output to the page.
example
The following shows the title and publication dates of all documents in a search result.
<US:iterResult
result="searchresult" 
instance="mybookstore">

<US:showAttributeValue attributeName="title" attributeType="string" default="No Title" />

<US:showAttributeValue attributeName="publication-date" attributeType="date" />

</US:iterResult>


Home	Book List	Contents	Master Index	Feedback