Skip Headers

Oracle Ultra Search Release Notes
Release 1, Version 9.0.3

Part Number B10092-01

Oracle® Ultra Search

Release Notes

Release 1, Version 9.0.3

August 2002

Part No. B10092-01

This document summarizes the differences between Oracle Ultra Search in Oracle Collaboration Suite release 9.0.3 and its documented functionality.

To view the Ultra Search documentation:

1 Certification and System Requirements

See the Oracle Ultra Search User's Guide and the Oracle Ultra Search section in the Oracle Collaboration Suite Installation Guide for systems requirements.

1.1 Ultra Search Installation

The Ultra Search middle tier is compliant with Oracle J2EE container (OC4J). Follow the instructions in the Oracle Ultra Search User's Guide to configure the Ultra Search middle tier with OC4J.

Ultra Search requires you to have either JRE or JDK on the database host where you install the Ultra Search server component. By default, JDK 1.3.1 is installed by Oracle Universal Installer (OUI) during database installation under directory $ORACLE_HOME/jdk. If you use a different JDK, either create a soft link, or copy the files from the location where you install JDK to $ORACLE_HOME/jdk. Ultra Search is certified with JDK 1.3.1 in this release.

1.2 Ultra Search Upgrade Information

To upgrade Ultra Search 9.0.2 from an iAS 9.0.2 infrastructure database to Ultra Search 9.0.3, perform the following steps:

  1. Copy all Ultra Search 9.0.2 files, recursively, under $ORACLE_HOME/ultrasearch/ to a different directory in case if you need to downgrade to 9.0.2 later.

  2. Login to the Ultra Search 9.0.2 administration tool, stop and disable all crawler synchronization schedules in every Ultra Search instance.

  3. Launch Oracle Collaboration Suite 9.0.3 installer, and perform the Infrastructure install.

  4. Specify the directory of the iAS 9.0.2 infrastructure as the Oracle Home.

  5. The Oracle Universal Installer then detects a previously installed database and automatically upgrades the infrastructure database and the Ultra Search server component.

    See Also:

    Oracle Ultra Search User's Guide for information on upgrading Ultra Search from a customer database, as opposed to an iAS 9.0.2 infrastructure database

1.3 Ultra Search Downgrade Information

Ultra Search 9.0.3 supports downgrading to 9.0.2 only. Downgrading to Ultra Search 1.0.3 is not supported.

Downgrade is based on the server component only. Downgrade on the middle tier is not supported.

1.3.1 Downgrade from Ultra Search 9.0.3 to 9.0.2

Login to the Ultra Search 9.0.3 administration tool. Stop and disable all crawler synchronization schedules, if any, in every Ultra Search instance. Then, set the iAS infrastructure environment variable $ORACLE_HOME to the iAS 9.0.2 home directory.

Before the downgrade, copy all Ultra Search 9.0.2 files, previously saved into a different directory, back to $ORACLE_HOME/ultrasearch/ Then, perform the following steps:

  1. Log on to the Ultra Search 9.0.3 administration tool. Stop and disable all crawler synchronization schedules, if any, in every Ultra Search instance.

  2. Reload 9.0.2 PL/SQL packages into the database (or the iAS Metadata Repository). Connect to the database as WKSYS:

    sqlplus wksys/<password>
    SQL> @$ORACLE_HOME/ultrasearch/admin/wk0pkh.sql
    SQL> @$ORACLE_HOME/ultrasearch/admin/wk0plb.sql
  3. Reload 9.0.2 Java stored packages into the database (or the iAS Metadata Repository).

    For UNIX:

    SQL> @$ORACLE_HOME/ultrasearch/admin/wk0loadjava.sql <Actual path of 

    For Windows:

    SQL> @%ORACLE_HOME%\ultrasearch\admin\wk0loadjava.sql   <Actual path 
    of ORACLE_HOME>/ultrasearch/lib

2 General Issues and Workarounds

2.1 Ultra Search Installation Issue

Bug 2304242 - Customer database silent mode install hanged at Ultra Search phase

For database installation with Oracle Portal Configuration Assistant (OPCA), Ultra Search only supports silent mode when there is no Ultra Search in the target database. For interactive mode, or if there is already an Ultra Search installed, the "DISPLAY" environment variable must be set correctly.

2.2 Deprecated and Desupported Features

The following features have been deprecated or desupported:

3 Configuration Issues and Workarounds

This section describes Ultra Search configuration issues and their workarounds for Ultra Search.

3.1 Setting Up Ultra Search Sample Query Applications

In addition to the configuration steps described in the Oracle Ultra Search User's Guide, you must also follow these steps in order for Ultra Search sample query application to function correctly.

To configure Ultra Search sample query applications and sample search portlet, edit the OC4J data-sources.xml file. For editing data-sources.xml, see the Oracle Ultra Search User's Guide.

3.1.1 Setting Up 9.0.1 Query API Sample - Deprecated

To configure gsearch.jsp, you must manually edit the file and change the variable setting for 'username' and 'password', and then edit to change the connection string. The file gsearch.jsp is under the $ORACLE_HOME/ultrasearch/sample/query/9i directory.

For editing the, see the Oracle Ultra Search User's Guide.

For detailed information, see $ORACLE_HOME/ultrasearch/sample/query/9i/README.html

3.2 Running the Crawler

The Ultra Search crawler is a Java process that runs on the server tier when launched. Therefore, Ultra Search requires you to have either JRE or JDK installed on the database host where you install the Ultra Search server component.

See Also:

"Certification and System Requirements"

3.2.1 Setting the JOB_QUEUE_PROCESSES Parameter

Oracle Ultra Search schedule launching uses the DBMS_JOB package. Therefore, the Oracle Ultra Search DBA must make sure that there is least one SNP process running. In other words, the initialization parameter file for the Oracle Ultra Search database instance should contain a line that specifies the JOB_QUEUE_PROCESSES parameter to be at least two.

3.3 Globalization Support

Oracle Ultra Search, like any other application that uses the database to store content, requires that the character set of the database be able to support the character set used at the application level. For example, if the application language is in Japanese, and if the database character set is SF7ASCII, then any data that the application attempts to store is corrupt, because the SF7ASCII character set does not support Asian languages.

The Oracle9i Globalization Support Guide provides detailed information on database character sets.


Universal character sets, such as UTF8, attempt to support all languages of the world, including, but not limited to, Asian, European, and Middle Eastern languages.

3.4 Ultra Search on Real Application Clusters

Ultra Search can crawl on one fixed node or on any node, depending on the storage access configuration of the Real Application Clusters system. PL/SQL APIs are provided to configure which node should run the crawler, if needed. For Ultra Search administration and the Ultra Search query application, you can configure the connection string to connect to any node of Real Application Clusters.

See Also:

The documentation for Oracle9i Real Application Clusters

3.4.1 Configuring Storage Access

The disk of any node in a Real Application Clusters system can be shared (cluster file system) or not shared (raw disk). For Real Application Clusters on a cluster file system (CFS), the cache files generated by the crawler on any node are visible to any Oracle instance and can be indexed by any Oracle instance that performs index synchronization. If the disk is not shared, the crawler must run on one particular Oracle instance to ensure that all cache files can be indexed.

This is due to the nature of Oracle Text indexing, where rows inserted to one table by different sessions go to the same pending queue, and whoever initiates index synchronization will attempt to index all of the inserted rows. Because of this limitation, on a CFS, Ultra Search is configured to launch the crawler on any database instance. If it is not on a CFS, Ultra Search launches the crawler on the database instance where INSTANCE_NUMBER = 1.

The Ultra Search administrator can configure which instance to run the crawler with the following PL/SQL API:

WK_ADM.SET_LAUNCH_INSTANCE(instance_name, connect_url) 

where instance_name is the name of the launching instance (or the database name if it is to be launched on any node) and connect_url is the connect descriptor.

For connection to a single database instance, the descriptor can be in the short form "<host>:<port>:<SID>" or the connect descriptor (Oracle Net keyword-value pair). For example:


To connect to any database instance, the full database connect descriptor must be used. For example:




See Also:

Oracle9i JDBC Developer's Guide and Reference for configuration details.

Note: You cannot configure Ultra Search to launch the crawler on any node on a non-cluster file system.

To query on the existing launching instance configuration, use the following PL/SQL API:


This returns the name of the launching instance or the database name if any node can launch the crawler. Remote Crawler File Cache

The Ultra Search remote crawler requires that the remote file system be mounted on the Oracle instance for indexing.

For cluster file system Real Application Clusters, the file system of the remote machine should be NFS mounted to all nodes of the system.

For non-cluster file system Real Application Clusters, the NFS mount can be limited to the specific node where the Oracle instance is serving the remote crawler. There is no advantage to mounting the remote file system to all nodes--it could lead to stale NFS handles when nodes go down. When there is a configuration change to move to a different Oracle instance, the remote file system should be NFS mounted to the new node accordingly.

3.4.2 Logging on to the Oracle Instance

All components of Ultra Search use the JDBC thin driver with the connect string consisting of "<host name>:<port number>:<SID> or the full connect descriptor as seen in tnsname.ora. Administration

The administration middle tier connects to the Oracle database with a JDBC connection specified in the file. If the client serving node is down, then you must manually edit this file to connect to a different Oracle instance. Query Search Application

Query components should fully utilize Real Application Clusters. You can specify the JDBC connection string as a database connect descriptor so that it can connect to any Oracle instance in Real Application Clusters. For example:


See Also:

Oracle9i JDBC Developer's Guide and Reference Java Crawler

The connect string used by Ultra Search crawler is initialized during installation and can be changed with the WK_ADM.SET_LAUNCH_INSTANCE API. When there is a system configuration change, like adding or dropping a node, the connect string is changed automatically. Choosing a JDBC Driver

The Ultra Search administrator can optionally configure the local crawler to use the JDBC OCI driver to log on to the database. This is done with the following PL/SQL API:



This API requires the WKADMIN privilege. The change affects all Ultra Search instances.


The OCI driver requires that environment variables, like LD_LIBRARY_PATH and NLS_LANG, be set properly on the launching database instance. The crawler inherits the environment setting from Oracle process. Therefore, you must set them up appropriately before starting up Oracle.

See Also:

Oracle9i JDBC Developer's Guide and Reference for configuration details on using the OCI driver.

The following PL/SQL API finds out what kind of JDBC drivers are used currently:


4 Performance Tuning

4.1 Verifying Crawler Progress

After you have configured the Oracle Ultra Search system, you can launch a crawler immediately from the Schedules screen.

View the Oracle Ultra Search crawler status by checking its state in the Oracle Ultra Search administration tool page.

Click the "Schedules" tab, and you see a table that lists all schedules and their state.

When a schedule is launching, it is in the "LAUNCHING" state. During the launching state, URLs to be crawled are marked by a SQL update operation. The amount of time this process may take depends on how many URLs are there for update. In cases such as maintenance crawling of the schedule, there can be millions of URLs to update, with the schedule staying in the "LAUNCHING" state for a very long time.

When a schedule has completed launching and the crawler has begun fetching pages, the state changes to "EXECUTING".

4.2 Crawler Performance Tuning

For crawler performance tuning, see Step 5 in Configuring the Oracle Server in the Oracle Ultra Search User's Guide.

4.3 Query Performance Tuning

This section contains suggestions on how to improve the response time of the Ultra Search query.

4.3.1 Tune the DB_CACHE_SIZE Parameter

The database buffer cache keeps frequently accessed data read from datafiles, and efficient usage of the buffer cache can improve Ultra Search query performance. The cache size is controlled by the DB_CACHE_SIZE initialization parameter.

For more information on how to tune this parameter, see Oracle9i Database Performance Tuning Guide and Reference.

4.3.2 Optimize the Index

Optimize the Ultra Search index after the crawler has made substantial updates. This can be done by scheduling index optimization on a regular basis. Make sure index optimization is scheduled during off-peak hours, because query performance is slow during an index optimization schedule.

For information on index optimization schedules, see the Oracle Ultra Search User's Guide or the online help for the Schedules Page ($ORACLE_HOME/ultrasearch/doc/help/a_schedules.htm).

4.3.3 Optimize the Index Based on Tokens

Optimize the Ultra Search index by basing it on frequently searched tokens. Queries can be logged by turning on query statistics collection in the Administration tool. The frequently searched tokens then can be passed to CTX_DDL.OPTIMIZE_INDEX in token mode. The Ultra Search index name is WK$DOC_PATH_IDX.

For more information on OPTIMIZE_INDEX, see Oracle Text Reference.

4.3.4 Simplify Query Expansion

The search response time is directly influenced by the Text query string used. Although Ultra Search provides a default mechanism to expand user input into a Text query, simpler expansions can greatly reduce search time.

For information on customizing query expansion, see the section on Customizing the Query Syntax Expansion in the Oracle Ultra Search User's Guide and the Javadoc for the oracle.ultrasearch.query.Query interface.

5 Known Bugs

5.1 Query Bugs

5.1.1 Bug 2114417 - Unwanted/Invalid Syntax Displayed For Query String

When query statistics collection is enabled, the query statistics pages (Daily summary of query statistics, Top 50 queries, Top 50 ineffective queries, Top 50 failed queries) may show text query strings like '(((WKA2X &({abc}))WITHIN S2))*2,({abc}))'. This behavior is due to 9.0.2 Java API expanding the user's query ('abc' in this case) before it is sent to the database.

In most cases, the user's query can be deciphered from the text query.

5.1.2 Bug 2097381 - Portal Users Should Embed Ultra Search Portlets Hosted On Same OC4J Instance

Portal users should embed Ultra Search portlets that are hosted on the same OC4J instance as the Oracle9iAS Portal server. For example, if the Oracle Portal OC4J instance is installed on host A / port 7777, then the Ultra Search provider must also be hosted as a Web application on host A / port 7777.

It is possible that the Ultra Search provider running on host A / port 777 could be registered with a second Oracle Portal instance running on a different host / port combination. In such cases, when the Ultra Search portlet is embedded within portal pages, the pop-up list-of-values will not work correctly. This is because of a security bug inherent in Javascript.

5.1.3 Bug 2494158 - Ultra Search Portlet: Advance Search: Lov Values: 404 Not Found

When running the Ultra Search portlet, users could encounter an error when clicking the LOV icons in the advanced search page. The JSP file for the list of values (lov.jsp) cannot be located. The following error message appears in the browser window:

Portal/applications/UltrasearchPortlet/query/servlet/lov.jsp (No such 
file or directory) 

Enter the following:

cd $ORACLE_HOME/j2ee/OC4J_Portal/applications/UltrasearchPortlet/query/ 
mkdir servlet 
cd servlet 
ln -s ../* .  
rmdir servlet 

Then, restart iAS.

This error occurs because the search portlet calls the JPDK API PortletRendererUtil.absoluteLink. The JPDK API does not return what it returned in previous releases. It now returns http://hostname:7777/provider/ultrasearch/servlet/soaprouter/, which is the registration URL for the Ultra Search provider.


Javadoc for this API method is in, java.lang.String)

The API call for PortletRendererUtil.absoluteLink is meant to provide an absolute path for JSP portlets to refer to relative files. With the Ultra Search provider, the search.jsp file refers to lov.jsp that resides one directory above it. Hence, it's relative path to lov.jsp is "../lov.jsp". Ultra Search combines PortletRendererUtil.absoluteLink+"../lov.jsp".

In previous releases, PortletRendererUtil.absoluteLink returned the absolute path to the search.jsp, which is http://hostname:7777/provider/ultrasearch/portlet/search.jsp. This yields an absolute path to lov.jsp as http://hostname:7777/provider/ultrasearch/portlet/../lov.jsp, which ultimately gets resolved to http://hostname:7777/provider/ultrasearch/lov.jsp.

5.1.4 Bug 2489561 Marconi:NLS:Japanese Attribute Display Names Cannot Be Displayed In Query Page, and Bug 2505711 Metadata Should Not Be Forced To Be Referenced Using 5 Letter Locale Codes

When using the Ultra Search Complete Sample application, user-entered translated metadata, such as the display names for attributes, lov entries and group names that are entered with the Ultra Search administration tool, may not propagate to the Ultra Search Complete Sample application. Display names loaded with the Ultra Search metadata loader also fail to propagate. This problem occurs when the browser language setting is sent to a locale that only includes into letter language code, such as "ja".

Solution description for the Complete Sample application:

  1. cd $ORACLE_HOME/j2ee/OC4J Portal/applications/UltrasearchQuery/query/

  2. Locate the following 2 files:

    • common_global_code.jsp

    • search.jsp

  3. Edit common_global_code.jsp as follows:

    In the definition for s_supportedLocales, locate the line that reads:

       new Locale("iw",""),

    Immediately after that line, add the following line:

       new Locale("ja",""),
  4. Edit common_global_code.jsp again as follows:

    After the method called getRequestLocale, add the following new method:

       * For bug 2489561  
      java.util.Locale getLocaleWithDefaultCountryCode(Locale locale)
        String langCode = locale.getLanguage();
        String countryCode = locale.getCountry();
        if (langCode != null && (countryCode == null || 
          // override the country code only if it's originally not set
          // and the language code is one of the supported languages.
          if (langCode.equals("ar"))
            countryCode = "TN";
          else if (langCode.equals("cs"))
            countryCode = "CZ";
          else if (langCode.equals("da"))
            countryCode = "DK";
          else if (langCode.equals("de"))
            countryCode = "AT";
          else if (langCode.equals("el"))
            countryCode = "GR";
          else if (langCode.equals("en"))
            countryCode = "US";
          else if (langCode.equals("es"))
            countryCode = "ES";
          else if (langCode.equals("fi"))
            countryCode = "FI";
          else if (langCode.equals("fr"))
            countryCode = "FR";
          else if (langCode.equals("hu"))
            countryCode = "HU";
          else if (langCode.equals("it"))
            countryCode = "IT";
          else if (langCode.equals("ja"))
            countryCode = "JP";
          else if (langCode.equals("iw"))
            countryCode = "IL";
          else if (langCode.equals("ko"))
            countryCode = "KR";
          else if (langCode.equals("nl"))
            countryCode = "NL";
          else if (langCode.equals("no"))
            countryCode = "NO";
          else if (langCode.equals("pl"))
            countryCode = "PL";
          else if (langCode.equals("pt"))
            countryCode = "PT";
          else if (langCode.equals("ro"))
            countryCode = "RO";
          else if (langCode.equals("ru"))
            countryCode = "RU";
          else if (langCode.equals("sk"))
            countryCode = "SK";
          else if (langCode.equals("sv"))
            countryCode = "FI";
          else if (langCode.equals("th"))
            countryCode = "TH";
          else if (langCode.equals("tr"))
            countryCode = "TR";
          else if (langCode.equals("zh"))
            countryCode = "CN";
          if (countryCode == null)
            return locale;
            return new Locale(langCode, countryCode); 
        return locale;
  5. Edit search.jsp as follows:

    Locate the line that reads:

    l_request_locale = getRequestLocale(request);

    Replace it with the following lines:

    java.util.Locale l_browser_locale = getRequestLocale(request);
    l_request_locale = getLocaleWithDefaultCountryCode(l_browser_
  6. Finally, restart iAS.

Whenever metadata, such as attribute display names and group display names, are stored with the Ultra Search administration tool, they are keyed with the full five letter locale code, which includes both language and country. For example, "ja-JP" for Japanese. This is a bug that will be fixed in the near future.

When the query application invokes the Query API methods to obtain the translated metadata, the query application passes the current browser locale as an argument. If the browser locale has been set to "ja" (without country code), then the Query API does not find the translated strings in the database, because they are keyed by "ja-JP".

Until bug 2505711 is fixed, this temporary workaround implements the following logic:

If (locale does not have country set)

then (set country code to default_country)

... where the default_country is a hard_coded list in the method getLocaleWithDefaultCountryCode that is provided above.

5.2 Crawler Bugs

5.2.1 Bug 2166510 - NLS: Crawler Shutdown Unexpected If Log Directory Name Contains MBCS

The crawler is unable to handle log directory path with multibyte characters.

Avoid specifying log directories that have Chinese, Japanese, or Korean characters.

5.2.2 Bug 2166662 - NLS: Can't Find Files With MBCS Name

File data source crawling cannot crawl directories or files with multibyte characters; for example, Chinese or Japanese.

Avoid naming the file in Chinese, Japanese, or Korean or putting them under such directory.

5.2.3 Bug 2186745 - File Data Source Can Not Crawl Directory Or File Name With HTML Reserved Symbol

The crawler is unable to pick up files or directories whose name contains HTML reserved symbols, like '<' or '>', when doing file data source crawling.

Rename the file or directory that is using such symbol.

5.2.4 Bug 2265100 - Unable To Stop Crawling When Crawler Is Enqueuing URL From A Crawler Agent

Stop crawling does not stop the crawler, even though the schedule status shows that the crawler has stopped. This happens when the crawler agent is used and the crawler is in the process of enqueuing URLs fetched from the agent. The crawler stops only after enqueuing is finished.

Currently, there is no way to stop the enqueuing other than manually killing the crawler process.

5.3 Oracle Portal Dependency

5.3.1 Bug 2244234 - Translations Of Items Have Same Display URL In Portal XML

In Portal, the URLs for translations of an item have the same display URL as that of the base language item. Portal users can view different translations because when users log in to Portal, the language is established as part of the browser session. However, this language negotiation process only works with browsers operated by human users. Therefore, the Ultra Search crawler receives the same display URL for the translated items. This violates the stated requirement that all display URLs presented to Ultra Search be unique. The implication is that Ultra Search cannot crawl translations of an item.

As in bug 2218987, with multiple translations, only one of the translation items or the base item itself is indexed by the crawler. The rest are rejected by the crawler because of the duplicate display URLs.

5.3.2 Bug 2244239 - Some Attributes In Portal XML Are Not Encased In Translations Section

If there are translations for an item or page, then some attributes of that item/page cannot be correctly transmitted to the Ultra Search crawler. As a result, attribute queries may not work correctly for translated items.

5.3.3 Bug 2244254 - Portal XML Should Not Reveal Item Types Of BASETYPE=NONE

Ultra Search crawler can process specific Portal item types. However, Portal item type of "none" does not have display URLs. As a result, they are not revealed to Ultra Search. Because anything that does not have a display URL cannot be represented in the search application search results list in such a way that the user can click on it to view the item.

5.4 Oracle Text Dependency

5.4.1 Bug 2205449 - Oracle Core Dump During Text Indexing in Multibyte Character Set Database, Such as UTF8

This impacts Ultra Search crawling, because the Ultra Search crawler invokes Oracle Text for indexing during the crawling process. The patch is available in ARU 1562387.

6 Documentation Errata

6.1 Oracle Ultra Search Documentation

The following are known issues with the Oracle Ultra Search documentation.

6.1.1 Incorrect Jar File Name for Sample Crawler Agent

The "Creating a Data Source Type" section in chapter 6 of the Oracle Ultra Search User's Guide contains an incorrect value for the sample agent jar file name. This causes you to get the following crawler error when you try to use the sample agent:

WKG-30116: Cannot find agent class "SampleAgent" from the java class path

The correct value is "sampleAgent.jar", not "sampleagent".

6.1.2 Errors in Sample Query Application READMEs

The READMEs titled "Oracle Ultra Search Simple Sample Query Application README", "Oracle Ultra Search Portlet Sample README", and "Ultra Search Query API Complete Sample Application README" make reference to the data-sources.xml configuration file. The full path for that file is given as $ORACLE_HOME/j2ee/home/config/data-sources.xml. This is incorrect.

The correct path is $ORACLE_HOME/j2ee/OC4J_Portal/config/data-sources.xml

Oracle is a registered trademark, and Oracle9i is a trademark or registered trademark of Oracle Corporation. Other names may be trademarks of their respective owners.

Copyright © 2002 Oracle Corporation.

All Rights Reserved.

Copyright © 2002 Oracle Corporation.

All Rights Reserved.