2
Installing and Configuring Ultra Search

This chapter contains the following topics:

• Ultra Search Requirements
• Installing the Ultra Search Server Component
• Installing the Server Component on an Existing Database or Metadata Repository
• Installing the Ultra Search Middle Tier on Web Server Hosts
• Installing the Server Component on Remote Crawler Hosts

Ultra Search Requirements

To use Oracle Ultra Search, you must install the following components with the Oracle Universal Installer:

• Ultra Search server component
• Ultra Search middle tier component

  Note: Ultra Search can be installed to crawl in both local and remote configurations. In remote configurations, the Ultra Search server component is also installed on one or more additional machines for scalability.

The Ultra Search server component can be installed on any already existing database that is Oracle database release 9.0.1 or higher with Oracle Text installed. To do this, invoke OPCA (Oracle Portal Configuration Assistant) from a middle tier host, and specify a database host.

See Also: "Installing the Server Component on an Existing Database or Metadata Repository"

Conventions

ORACLE_HOME refers to the Oracle home directory where the Ultra Search server component is installed. ORACLE_HOME also refers to the Oracle home directory where the Ultra Search middle tier component is installed.

REMOTE_ORACLE_HOME refers to the Oracle home directory where the Ultra Search server component is installed on a remote crawler host.

Ultra Search System Requirements

The following section describes the Ultra Search system requirements.

Hardware Requirements

Sufficient RAM

The Ultra Search indexing engine runs within Oracle. Hence, it is important that the system have enough memory to accommodate a large Oracle installation. The Oracle instance system global area should be a minimum of 50MB.

See Also: Oracle9i Database Performance Tuning Guide and Reference

The Ultra Search Web crawler runs as a separate Java process on the same host. Allocate 50MB of memory for the Web crawler alone.

The Ultra Search administration tool is a J2EE 1.2 standard Web application. Therefore, it can be installed and run on a separate host from the Ultra Search server component. However, you might want to install and run this component on the same host as the Ultra Search server component. Regardless of your choice, allocate enough memory for the J2EE engine. Oracle Corporation recommends using the Oracle HTTP server with the Oracle J2EE container. Allocate enough memory for the HTTP server as well as the JDK that runs the J2EE engine.

Sufficient Disk Space

Because customer requirements vary widely, Oracle cannot recommend a specific amount of disk space. However, as a general guideline, the minimal requirements are as follows:

• Approximately 3 GB of disk space for the iAS infrastructure or database and the Ultra Search server component.
• For each Web server host, enough space to install the Oracle HTTP server and related products. In addition, you need 15MB of disk space for the Ultra Search middle tier component.
• For each remote crawler host, the same amount of disk space as needed to install the Ultra Search server component.
• Disk space for a large TEMPORARY tablespace. As a general guideline, create a TEMPORARY tablespace as large as available depending on the RAM on your host.
• Disk space for the Ultra Search instance user's tablespace.
  • The Ultra Search instance user is a database user that you need to explicitly create. All data that is collected and processed as part of the crawling and indexing process is stored in this user's schema.
  • As a general guideline, create the tablespace as large as the total amount of data that you want to index. For example, if you approximate that the total amount of data to be crawled and indexed is 10GB, then create a tablespace that is at least 10GB for the Ultra Search instance user. Make sure to assign that tablespace as the default tablespace of the Ultra Search instance user.

Software Requirements

The Ultra Search middle tier components are Web applications. Therefore, they require a Web server to run. Oracle Corporation recommends the Oracle HTTP Server and Jserv or Oracle HTTP Server and the Oracle J2EE container.

Installing the Ultra Search Server Component

The Ultra Search server component is included as part of the Oracle database. It is installed together with the Ultra Search middle tier component during the installation. It is installed in the same Oracle home directory as the database server tier.

The Ultra Search server component consists of the following:

• Ultra Search data dictionary and PL/SQL packages
• Ultra Search crawler Java classes
• Ultra Search remote crawler
• Ultra Search product libraries

Installing and Configuring the Server Component

Step 1: Install 9iAS Infrastructure and the Ultra Search Server Component

Database Release:

Start up the Oracle Universal Installer (OUI) on the relevant host. After choosing the destination Oracle home name and full path, choose the option "Oracle9i Server." Ultra Search server tier is installed with the Oracle9i database by default.

iAS Infrastructure:

Start up the OUI on the relevant host. After choosing the destination Oracle home name and full path, choose the option "Oracle9iAS Infrastructure 9.0.2.0.0." Ultra Search server tier is installed with the Oracle iAS infrastructure by default.

During the installation of iAS or the Oracle database server, the Ultra Search server component is installed. The following activity occurs during this process:

• All Ultra Search server component files are copied into a directory named "ultrasearch". This directory resides immediately under the ORACLE_HOME of the designated database installation.
• The database user WKSYS with password wksys is created. You should change this password later for security purposes. All Ultra Search database objects are installed in this user's schema.
• Various PL/SQL scripts are run against the database as user WKSYS. These scripts install and create various database objects.

  See Also: Your installation guide for information on setting necessary environment variables

Step 2: Configure the Oracle Database for Ultra Search

After you have installed all Ultra Search components, you must configure the Oracle database. This is a post-installation operation.

See Also: "Configuring the Oracle Server for Ultra Search"

Installing the Server Component on an Existing Database or Metadata Repository

Ultra Search can be installed on an Oracle9i database, or an iAS metadata repository, that is currently in use.

Note: This feature is supported on the iAS release only.

Installing Ultra Search on an existing database or metadata repository includes transferring files, creating Ultra Search super user WKSYS, loading Ultra Search PL/SQL database packages, and associating Oracle9i Application Server (9iAS) with Ultra Search.

Unlike the infrastructure database installation, Ultra Search packages are loaded from the middle tier installation. By choosing to install Oracle Portal to your database, Oracle Portal Configuration Assistant (OPCA) loads the Ultra Search packages onto the database host you choose. You then manually transfer necessary files to the database tier's file system.

See Also: http://portalstudio.oracle.com/ for more information on Oracle Portal and on how to use OPCA

Database Requirements

• The Java development kit (JDK) must be release 1.2.207 or higher.
• Oracle database must be release 9.0.1 or higher.
• The initialization file must have JOB_QUEUE_PROCESSES set to greater than two.
• Oracle Text must be installed in the database. Oracle Text provides the text indexing and search capabilities required to index and query data retrieved from your data sources, such Web sites or database tables.

  Note: To run the crawler, Ultra Search requires a Java 1.2 compliant runtime environment (JDK) to be installed on the database machine. JDK 1.2.2 07 should already be installed with the Oracle HTTP server.

Installing the Server Component on an Existing Oracle9i Database

1. Create user WKSYS, load Ultra Search PL/SQL packages, and associate Ultra Search with 9iAS.

   Ultra Search PL/SQL database packages are loaded during the middle tier (9iAS) installation. During this installation, after the Oracle Universal Installer copies the necessary files to the middle tier host, OPCA associates Ultra Search with 9iAS. After specifying the database tier host, Oracle SID, and port, Ultra Search packages area loaded by OPCA to the database on the database tier host.

   If OPCA detects that the Ultra Search superuser WKSYS already exists, and the Ultra Search release is 1.0.3 (based on Oracle9i database 9.0.1), then it asks the user to choose from the following three options:

   • Deinstall/Reinstall: This drops the existing WKSYS user, creates a new WKSYS user, and reloads the Ultra Search packages. All data collected by Ultra Search is deleted.
   • Migrate: This asks the user to follow the instructions on the Ultra Search migration document for manual migration.

     See Also: "Upgrade from Ultra Search 1.0.3 (Oracle9i Database 9.0.1) to 9.0.3"

   • Abort: This stops OPCA from loading Ultra Search PL/SQL database packages into the existing database.

     Note: The default password for WKSYS is wksys. You should immediately change the password to avoid any security issues. OPCA then configures 9iAS to work with Ultra Search. Configuration involves the following files: mod_oc4j.conf, server.xml, and ultrasearch.properties. For details, see "Installing the Ultra Search Middle Tier on Web Server Hosts".

2. Transfer files and configure the database. Ultra Search requires that certain files exist on the database tier's file system. Because the database tier might exist in a physically unreachable place, and because neither the Oracle Universal Installer nor OPCA have access to the remote database tier's file system, you must manually copy the necessary files. In the ORACLE_HOME/ultrasearch/setup/ directory, there are several files including setupDB.jar, setupDB.bat, setupDB.csh, and setupDB.sh. Copy these files to the ORACLE_HOME of your remote database tier.
3. Set the files to the correct location by running the following scripts for your operating system.

   For Windows NT: Edit setupDB.bat using any text editor. After the line "set ORACLE_HOME=" put the directory name where you installed the Oracle database. Save the change and run setupDB.bat by double clicking setupDB.bat or by running setupDB in the command prompt.

   For Solaris: Run setupDB.sh under the Bourne shell prompt. The system sets the current directory as ORACLE_HOME and asks for the path to your JDK_HOME. If the default path to the jar executable or Java executable is not correct, then the system asks for the path to JDK. If you do not have JDK installed, then download the latest JDK and run setupDB.sh again.

   Note: To run this script, the executable bit of setupDB.sh should be turned on.

Installing the Server Component on an Existing iAS Metadata Repository

1. Create user WKSYS, load Ultra Search PL/SQL packages, and associate Ultra Search with 9iAS.

   Ultra Search PL/SQL packages are loaded during the middle tier (9iAS) installation. During this installation, after the Oracle Universal Installer copies the necessary files to the middle tier host, OPCA associates Ultra Search with 9iAS. After specifying the metadata repository tier host, Oracle SID, and port, Ultra Search packages area loaded by OPCA to the metadata repository on the metadata repository tier host.

   If the detected Ultra Search release is 9.0.2 or later, then it asks the user to choose from the following three options:

   • Deinstall/Reinstall: This drops the existing WKSYS user, creates a new WKSYS user, and reloads the Ultra Search packages. All data collected by Ultra Search is deleted.
   • Upgrade to 9.0.3: This upgrades the existing Ultra Search packages to release 9.0.3. All data collected with the existing Ultra Search remain intact.
   • Abort: This stops OPCA from loading Ultra Search PL/SQL packages into the existing metadata repository.

     .

     Note: The default password for WKSYS is wksys. You should immediately change the password to avoid any security issues. OPCA then configures 9iAS to work with Ultra Search. Configuration involves the following files: mod_oc4j.conf, server.xml, and ultrasearch.properties. For details, see "Installing the Ultra Search Middle Tier on Web Server Hosts".

2. Transfer files and configure the metadata repository. Ultra Search requires that certain files exist on the metadata repository tier's file system. Because the metadata repository tier might exist in a physically unreachable place, and because neither the Oracle Universal Installer nor OPCA have access to the remote metadata repository tier's file system, you must manually copy the necessary files. In the ORACLE_HOME/ultrasearch/setup/ directory, there are several files including setupDB.jar, setupDB.bat, setupDB.csh, and setupDB.sh. Copy these files to the ORACLE_HOME of your remote metadata repository tier.
3. Set the files to the correct location by running the following scripts for your operating system.

   For Windows NT: Edit setupDB.bat using any text editor. After the line "set ORACLE_HOME=" put the directory name where you installed the Oracle metadata repository. Save the change and run setupDB.bat by double clicking setupDB.bat or by running setupDB in the command prompt.

   For Solaris: Run setupDB.sh under the Bourne shell prompt. The system sets the current directory as ORACLE_HOME and asks for the path to your JDK_HOME. If the default path to the jar executable or Java executable is not correct, then the system asks for the path to JDK. If you do not have JDK installed, then download the latest JDK and run setupDB.sh again.

   Note: To run this script, the executable bit of setupDB.sh should be turned on.

Installing the Ultra Search Middle Tier on Web Server Hosts

The Ultra Search middle tier component includes the following:

• Ultra Search administration tool
• Ultra Search Java query API
• Ultra Search Java server page sample query applications

For the iAS release, the Ultra Search middle tier component is part of the Application Server install. You must choose the "Oracle 9iAS Portal and Wireless" option from the Oracle Universal Installer menu to install and configure the Ultra Search middle tier component with the Application Server install.

For the database release, the Ultra Search middle tier component is installed with the Ultra Search server component during the database server install. This component is also part of the database client install. However, Oracle database client install does not install Oracle HTTP server, which is a requirement for the Ultra Search middle tier component. You should install Oracle HTTP server before installing the Ultra Search middle tier component. Do so by choosing the "server" install option from the Oracle Universal Installer menu. Then, perform a custom install and choose the Oracle HTTP Server for installation.

The following section describes how to install and configure the Ultra Search middle tier component on a host that you have designated to be a Web server. You can install the Ultra Search middle tier component on multiple Web server hosts to handle a large number of incoming queries by end users.

Web Application Concepts

The Ultra Search administration tool and the Ultra Search JSP query applications are Java Server Page Web applications. These are three tier architecture applications. Figure 2-1 shows the relationship between the browser interface (the first tier), the Web server and the JSP engine (the middle tier), and the Oracle database (the third tier). Typically, you install JSP applications on the same host as your Web server. The Ultra Search JSP applications consist of Ultra Search Java libraries, JSP files, and the ultrasearch.properties configuration file. This file specifies which database the JSP applications connect to.

Your Web server accepts requests from the browser and forwards all administration tool JSP page requests to the JSP engine for processing. To store and retrieve crawler configuration data, the JSP engine communicates with the Oracle database through the JDBC driver, as in Figure 2-1.

To invoke the Ultra Search administration tool or the Ultra Search JSP query applications, enter a URL that invokes those Web applications. The URLs are described in the following section. Use the Ultra Search administration tool to define Ultra Search instances, manage users, configure and schedule the Ultra Search crawler, and set query options. Use the Ultra Search JSP query applications to search for documents gathered and indexed by the Ultra Search server component.

Figure 2-1 Ultra Search Architecture

Text description of the illustration isrch010.gif

Browser Requirements

To use the administration tool, your browser must be Netscape version 4.0 or Microsoft Internet Explorer version 4.0 or higher.

Installing the Middle Tier Component

Installing with the Oracle Database

There are two ways to configure the Ultra Search middle tier component:

Option 1

Install Ultra Search middle tier component into an Oracle home with Oracle HTTP Server preinstalled. If the Oracle HTTP server is preinstalled, then the installer can automatically configure it to run the Ultra Search middle tier component. To obtain the Oracle HTTP server, choose the "Server" install option from the Oracle Universal Installer (OUI) menu. Then, perform a custom install and choose the Oracle HTTP server for installation.

Option 2

Install without Oracle HTTP server preinstalled.

If the Oracle HTTP Server is not preinstalled, then you must manually perform all configuration work that the installer does. If you use a different Web server, then you must also manually configure the Web server accordingly.

Choose the installation option. Start up OUI on the relevant host. Choose to install the Oracle9i client. Make sure to choose the "Administrator Install" or the "Custom Install" option. The OUI prompts for an Oracle home directory in which to install the middle tier component. This directory is referred to as $ORACLE_HOME.

Installing with the Oracle Application Server

Start the OUI on the relevant host. Choose the destination Oracle home name and full path, and do the following steps:

1. Choose the option "Oracle 9iAS Application Server 9.0.2.0.0", and click next.
2. Choose the option "B. Portal and Wireless", and click next.
3. On the "Available Product Components" screen, make sure "Oracle Ultra Search Extension for EMD 9.0.2.0.0" is checked. Click next.
4. On the "Component Configuration" screen, make sure "Oracle9iAS Portal" is checked. This allows Oracle Portal Configuration Assistant to configure Oracle HTTP server and OC4J with Ultra Search. If you uncheck this option, then you must follow the instructions listed under Configuring Ultra Search Middle Tier Component with Oracle HTTP Server and OC4J to set up Oracle HTTP server and OC4J manually.
5. Continue with the installation until Oracle9iAS is successfully installed.

   Note: If you decide to use a third party J2EE container or a servlet engine, then uncheck the option "Oracle9iAS Portal" on the "Component Configuration" screen of Oracle Installer, and see the "Deploying the Ultra Search EAR File on a Third Party Middle Tier". Upon completion of this step, all middle tier component files are copied under the $ORACLE_HOME.

Configuring the Middle Tier Component

Installing with the Oracle Database

If you chose Option 1, then OUI automatically configures the Ultra Search middle tier component with Oracle HTTP server and Jserv. Proceed to "Editing the ultrasearch.properties File".

If you chose Option 2, then you must manually perform the following steps to configure your existing Web server. The default Web server setup of Oracle 9.2 is Oracle HTTP server with Jserv. You can also deploy the Ultra Search middle tier component on Oracle HTTP server with Oracle J2EE container (OC4J). However, Oracle J2EE container is only available with Oracle9i Application Server. Proceed to the section corresponding to the Web server you decide to use to configure the Ultra Search middle tier component.

Installing with the Oracle Application Server

If you checked the "Oracle9iAS Portal" option on the "Component Configuration" Oracle Installer screen, then the configuration steps in the following section are automatically performed by OPCA. Proceed directly "Editing the data-sources.xml File".

If not, then you must manually perform the steps under "Configuring the Middle Tier Component with Oracle HTTP Server and Jserv" to configure your existing Web server.

You can also deploy Ultra Search Web applications using Oracle Enterprise Manager.

See Also: Oracle9i Database Administrator's Guide for more information on Enterprise Manager

Configuring the Middle Tier Component with Oracle HTTP Server and Jserv

1. Oracle Universal Installer (OUI) automatically creates a Web server alias for the Ultra Search online documentation accessible through the administration tool. The Installer edits $ORACLE_HOME/Apache/jsp/conf/ojsp.conf to create an alias for the Ultra Search document root. The following line is added to that file:

   Alias /ultrasearch/doc/ "$ORACLE_HOME/ultrasearch/doc/"
   
   

2. OUI automatically creates a Web server alias for the Ultra Search administration tool. The Installer edits $ORACLE_HOME/Apache/jsp/conf/ojsp.conf to create an alias for the Ultra Search JSP tree root. The following line is added to that file:

   Alias /ultrasearch/admin/ "$ORACLE_HOME/ultrasearch/webapp/isearch_admin/"
   
   

3. OUI automatically creates a Web server alias for the Ultra Search JSP query applications and welcome page: The Installer edits $ORACLE_HOME/Apache/jsp/conf/ojsp.conf to create an alias for the Ultra Search JSP tree root. The following line is added to that file:

   Alias /ultrasearch/ "$ORACLE_HOME/ultrasearch/sample/"
   

   Note: This alias must be positioned last.

4. OUI automatically adds the Ultra Search middle tier library, the Ultra Search Java query API library, and the JGL object library to the servlet engine Java classpath. The Installer edits $ORACLE_HOME/Apache/Jserv/etc/jserv.properties to include those files. The following five lines are added:

   wrapper.classpath=$ORACLE_HOME/ultrasearch/lib/ultrasearch_midtier.jar 
   wrapper.classpath=$ORACLE_HOME/ultrasearch/lib/ultrasearch_query.jar 
   wrapper.classpath=$ORACLE_HOME/ultrasearch/lib/jgl3.1.0.jar 
   wrapper.classpath=$ORACLE_HOME/lib/mail.jar 
   wrapper.classpath=$ORACLE_HOME/lib/activation.jar
   
   

5. OUI automatically adds the Oracle9i JDBC thin driver to the servlet engine Java classpath. The Installer edits $ORACLE_HOME/Apache/Jserv/etc/jserv.properties to include that directory. The following three lines are added:

   wrapper.classpath=$ORACLE_HOME/jlib/uix2.jar
   wrapper.classpath=$ORACLE_HOME/jlib/share.jar
   wrapper.classpath=$ORACLE_HOME/jlib/regexp.jar
   
   

6. OUI automatically adds the Oracle9i JDBC thin driver to the servlet engine Java classpath. The Installer edits $ORACLE_HOME/Apache/Jserv/etc/jserv.properties to include that directory. The following line is added:

   wrapper.classpath=$ORACLE_HOME/jdbc/lib/classes12.zip
   
   

7. OUI automatically adds the directory containing the ultrasearch.properties file to the servlet engine classpath. The Installer edits $ORACLE_HOME/Apache/Jserv/etc/jserv.properties to include that directory. The following line is added:

   wrapper.classpath=$ORACLE_HOME/ultrasearch/webapp/config/
   

   Note: On Windows NT, the path is $ORACLE_HOME/Apache/Jserv/conf/jserv.properties.

8. The current version of Ultra Search middle tier component requires version 2.1 or higher of servlet.jar. To configure Jserv with version 2.2 of servlet.jar, edit $ORACLE_HOME/Apache/Jserv/etc/jserv.properties file, and add the following line:

   wrapper.classpath=$ORACLE_HOME/lib/servlet.jar
   
   

9. Proceed to "Editing the ultrasearch.properties File".

Configuring the Middle Tier Component with Oracle HTTP Server and OC4J

Note: This is available with iAS only. To deploy Ultra Search Web applications, you must have a J2EE 1.2 container. Oracle Corporation recommends using Apache Web server and Oracle Containers for J2EE (OC4J).

See Also: "Deploying the Ultra Search EAR File on a Third Party Middle Tier" if you use a third party J2EE container or servlet engine

1. For OC4J configuration, modify the following OC4J configuration files: server.xml, application.xml, and default-web-site.xml in $ORACLE_HOME/j2ee/OC4J_Portal/config/. The configuration of OC4J works with Ultra Search J2EE applications.

   See Also: OC4J documentation for more information on deploying EAR and WAR applications and for the more advanced functionality of OC4J.

   • For server.xml, under <application-server> tag, add the following:

     <application name="ultrasearch_admin" path="$ORACLE_
     HOME/ultrasearch/webapp/ultrasearch_admin.ear" />
     
     <application name="ultrasearch_query" path="$ORACLE_
     HOME/ultrasearch/sample.ear" />
     
     <application name="ultrasearch_portlet" path="$ORACLE_
     HOME/ultrasearch/webapp/ultrasearch_portlet.ear" /> 
     

     Note: These lines let OC4J know that it must deploy the Ultra Search EAR file, as well as define where this EAR files is. Ultrasearch_admin.ear contains the Ultra Search administration tool Web application. The sample.ear file contains the sample query JSP pages. After OC4J deploys sample.ear, you can see the $ORACLE_HOME/ultrasearch/sample directory. Use the JSPs in this directory to create you own query Web pages. For more information on this directory, see "Testing the Ultra Search JSP Sample Query Applications".

   • For application.xml, under <orion-application> tag, add the following:

     <library path="$ORACLE_HOME/ultrasearch/lib/ultrasearch_query.jar" />
     <library path="$ORACLE_HOME/ultrasearch/webapp/config" />
     <library path="$ORACLE_HOME/jlib/uix2.jar" />
     <library path="$ORACLE_HOME/jlib/share.jar" />
     <library path="$ORACLE_HOME/jlib/regexp.jar" />
     <library path="$ORACLE_HOME/lib/mail.jar" />
     <library path="$ORACLE_HOME/lib/activation.jar" />
     <library path="$ORACLE_HOME/lib/xmlparserv2.jar" />
     <library path="$ORACLE_HOME/jdbc/lib/nls_charset12.zip" />
     <library path="$ORACLE_HOME/jdbc/lib/classes12.jar" />
     
     

     The preceding libraries are required for the Ultra Search administration tool and query Web applications to run.

     Note: $ORACLE_HOME/ultrasearch/webapp/config contains the ultrasearch.properties file. For more information, see "Editing the ultrasearch.properties File".

• For default-web-site.xml

  For <web-site> tag, set port="<ajp13 port>" and add protocol="ajp13" as a attribute for <web-site> tag. Under <web-site> tag, add the following:

  <web-app application="ultrasearch_admin" name="admin" 
  root="/ultrasearch/admin" />
  
  <web-app application="ultrasearch_query" name="query" 
  root="/ultrasearch/query" />
  
  <web-app application="ultrasearch_portlet" name="query" 
  root="/provider/ultrasearch" />
  

  The preceding lines describe which Web application (WAR file) in the Ultra Search EAR files are deployed.

  • The application field describes the application name. It should match the application name in server.xml.
  • The name field describes the Web application name. This should match the WAR file name within the EAR file corresponding to the application.
  • Root specify the virtual path for this Web application. The virtual path is the path under the URL. For the administrative Web application, access it using http://<hostname.domainname>:<HTTPport>/ultrasearch/admin/.

    Note: The virtual path for a particular Web application is defined in three files: default-web-site.xml, mod_oc4j.conf, and application.xml in the META-INF directory of the EAR file. (The META-INF is created by extracting the EAR file.) You must modify the root attribute of web-app in default-web-site.xml, and the value enclosed by tag context-root in application.xml to change the virtual path point to each Web application.

• Modify modOC4J configuration files. Add the following to $ORACLE_HOME/Apache/Apache/conf/mod_oc4j.conf:

  Oc4jMount /ultrasearch/admin/* ajp13://<host>:<ajp13 port>
  Oc4jMount /ultrasearch/query/* ajp13://<host>:<ajp13 port>
  Oc4jMount /provider/ultrasearch/* ajp13://<host>:<ajp13 port>
  
  

  Where <host> is the host name of the computer where the OC4J is installed, and <ajp13 port> is the port for ajp13 protocol. It must match the <ajp13 port> listed under default-web-site.xml, and the OC4Jmount must match the root of web-app in default-web-site.xml.

  Note: With this modOC4J configuration, you must start the OC4J server manually with the command "java -jar oc4j.jar -config $ORACLE_HOME/j2ee/OC4J_Portal/config/server.xml" in the $ORACLE_HOME/j2ee/home/ directory. Module OC4J offers more functionality, such as load balancing and fail over. Turn on this functionality based on your needs. See the official module OC4J documentation for the configuration of this functionality.

• Add alias to Oracle HTTP Web server. Modify the $ORACLE_HOME/Apache/jsp/conf/ojsp.conf file to deploy the Ultra Search online help documentation and the Ultra Search welcome page:

  Alias /ultrasearch/doc/ "$ORACLE_HOME/ultrasearch/doc/" for Solaris

  Alias /ultrasearch/doc/ "$ORACLE_HOME\ultrasearch\doc/" for NT

  Alias /ultrasearch/ "$ORACLE_HOME/ultrasearch/sample/" for Solaris

  Alias /ultrasearch/ "$ORACLE_HOME\ultrasearch\sample/" for NT

  If you choose to install Ultra Search on an already existing database, then in addition to the preceding steps, the installation of Ultra Search on a customer's database is required.

  See Also: "Installing the Server Component on an Existing Database or Metadata Repository"

  Follow instructions in the Configuring the Administration Tool with Single Sign-On Server; otherwise proceed to "Editing the data-sources.xml File".

• Ultra Search sample pages require JDBC connections to the database as the instance owner. Due to Jserv limitations, the username, password and connection string used to create the JDBC connection are hard-coded inside the sample's JSP code. To configure the JSP to query a specific instance, edit the JSP source code, and replace the username, password, and connection string values.

  All sample JSP source code are in $ORACLE_HOME/ultrasearch/sample/query directory.

  The following files contain username, password, and connection string values:

  • common_customize_instance.jsp (used by search.jsp)
  • usearch.jsp
  • tag/tsearch.jsp
  • 9i/gsearch.jsp
  • 9i/display.jsp
  • 9i/gsearchf.jsp
  • 9i/gutil.jsp
  • 9i/mail.jsp

    Note: The 9i JSP files are being deprecated. It is not necessary to configure them if you do not plan to use them.

Configuring the Administration Tool with Single Sign-On Server

Note: This is available with iAS only.

To configure the Ultra Search administration tool with Oracle single sign-on (SSO) server, you must also follow the steps in the following section in addition to the configuration in "Configuring the Middle Tier Component with Oracle HTTP Server and OC4J".

1. For OC4J configuration, modify the following OC4J configuration files: application.xml, and default-web-site.xml in $ORACLE_HOME/j2ee/OC4J_Portal/config/.
   • For application.xml, under <orion-application> tag, add the following:

     <library path="$ORACLE_HOME/jlib/repository.jar" />
     <library path="$ORACLE_HOME/jlib/jndi.jar" />
     <library path="$ORACLE_HOME/jlib/ldapjclnt9.jar" />
     <library path="$ORACLE_HOME/j2ee/home/jazn.jar" />
     <library path="$ORACLE_HOME/j2ee/home/jaas.jar" />
     
     

   • For default-web-site.xml, under <web-site> tag, add the following:

     <web-app application="ultrasearch_admin" name="admin" 
     root="/ultrasearch/admin_sso" />
     
     

2. Modify modOC4J configuration files. Add the following to mod_oc4j.conf: Oc4jMount /ultrasearch/admin_sso/* ajp13://<host>:<ajp13 port>
3. Modify Oracle HTTP server configuration file httpd.conf under $ORACLE_HOME/Apache/Apache/conf directory, add the following lines:

   <IfModule mod_osso.c>
   <Location /ultrasearch/admin_sso>
   require valid-user
   authType Basic
   </Location>
   </IfModule>
   
   

   Access URL http://<hostname.domainname>:<HTTPport>/ultrasearch/admin_sso/ to log on to Ultra Search administration tool using SSO authentication.

   Proceed to "Editing the data-sources.xml File".

Deploying the Ultra Search EAR File on a Third Party Middle Tier

Because Ultra Search EAR files contain only Web applications (WAR files), they can be made to deploy on any J2EE 1.2 container. To do so, you must know the Ultra Search WAR file name, the predefined URL root, and the Java library required. The following section explains the Ultra Search EAR files that you need to know to deploy in a standard J2EE 1.2 container. It does not contain information on the configuration of each J2EE 1.2 container.

See Also:   The documentation of the third party J2EE container for its configuration. "Configuring the Middle Tier Component" for the exact configuration of Oracle HTTP server and Oracle J2EE container

Deploying the Administration Tool

Ultra Search administration tool is a Web application contained in $ORACLE_HOME/ultrasearch/webapp/ultrasearch_admin.ear file. The following is the file structure of ultrasearch_admin. Extract the archived file by running the command "jar -xvf ultrasearch_admin.ear".

ultrasearch_admin.ear 
            META-INF/ 
                      application.xml 
                      orion-application.xml 
            admin.war 
            admin_sso.war 
            ultrasearch_midtier.jar 
            jgl3.1.0.jar

Note: admin.war is the Ultra Search administration tool, and admin_sso.war is the Ultra Search administration tool with SSO (single sign-on) support. Both ultrasearch_midtier.jar and jgl3.1.0.jar are Java libraries used by admin.war and admin_sso.war. They are not EJBs. The context root for admin.war and admin_sso.war are /ultrasearch/admin and /ultrasearch/admin_sso. They are defined in META-INF/application.xml.

The following is the structure of admin.war and admin_sso.war. They contain the same set of files. You can see it by running the command "jar -xvf admin.war" and "jar -xvf admin_sso.war".

admin_sso.war and admin.war 
            WEB-INF/ 
                      lib/ 
                      web.xml 
            index.jsp 
            */*.jsp

To make Ultra Search EAR file and WAR file J2EE 1.2 compliant, you must move the ultrasearch_midtier.jar and jgl3.1.0.jar to the WEB-INF/lib/ directory of admin.war and admin_sso.war. Then, rejar admin.war, admin_sso.war, and ultrasearch_admin.ear using the command "jar -cvf <war file or EAR file name> <files to jar>".

Note: The new admin.war file created is a servlet 2.2 standard Web application. Deploy admin.war alone using any servlet 2.2 engine.

The following Java libraries are needed for Ultra Search administration tool. They should be added to the library path of J2EE container or the servlet engine used to deploy the Ultra Search administration tool.

$ORACLE_HOME/ultrasearch/webapp/config 
$ORACLE_HOME/jlib/uix2.jar 
$ORACLE_HOME/jlib/share.jar 
$ORACLE_HOME/jlib/regexp.jar 
$ORACLE_HOME/jdbc/lib/nls_charset12.zip 
$ORACLE_HOME/jdbc/lib/classes12.jar 
$ORACLE_HOME/lib/xmlparserv2.jar

To configure Ultra Search with SSO, you must have the Oracle iAS infrastructure installed and Oracle Internet Directory turned on. In addition to this library path, the following library paths are also needed:

$ORACLE_HOME/jlib/repository.jar 
$ORACLE_HOME/jlib/jndi.jar 
$ORACLE_HOME/jlib/ldapjclnt9.jar 
$ORACLE_HOME/j2ee/home/jazn.jar 
$ORACLE_HOME/j2ee/home/jaas.jar

Deploying the Sample Query Applications

Ultra Search sample query applications are Web applications contained in the $ORACLE_HOME/ultrasearch/sample.ear file. This file is already compliant to the J2EE 1.2 standard. You should not have to change this file to deploy it.

The following is the file structure of sample.ear. Extract the archived file by running the command "jar -xvf sample.ear".

sample.ear
            META-INF/ 
                      application.xml 
            query.war 
            agent/ 
            index.html

All the query JSP pages are contained in query.war. This file is a servlet 2.2 compliant Web application. Deploy it alone with any servlet 2.2 engine. The context root for query.war is /ultrasearch/query. It is defined in the META-INF/application.xml of the sample.ear file. You can change it by editing this file.

The following are the Java libraries needed for Ultra Search sample query application:

$ORACLE_HOME/ultrasearch/webapp/config 
$ORACLE_HOME/jdbc/lib/classes12.jar 
$ORACLE_HOME/jdbc/lib/nls_charset12.zip 
$ORACLE_HOME/lib/xmlparserv2.jar 
$ORACLE_HOME/lib/activation.jar 
$ORACLE_HOME/lib/mail.jar

Ultra Search query applications also use the connection pooling functionality of J2EE container. You must define a container authenticated data source. This data source must return an Oracle connection. Oracle Corporation recommends using the Java class equal to oracle.jdbc.pool.OracleConnectionCacheImpl for this data source.

In addition, the data source should contain the field location equal to jdbc/UltraSearchPooledDS, username, password equal to the Ultra Search instance owner's database username, and password and URL equal to the JDBC connection string in the form of "jdbc:oracle:thin:@<database host>:<oracle port>:<oracle sid>".

See Also: "Editing the data-sources.xml File" for the data source configuration of the Oracle J2EE container

Deploying the Ultra Search Portlet

Ultra Search Portlet is a Web application contained in the $ORACLE_HOME/ultrasearch/webapp/ultrasearch_portlet.ear file. This file is compliant to the J2EE 1.2 standard. This file is similar to sample.ear in terms of file structure. Extract the archived file by running the command "jar -xvf ultrasearch_portlet.ear".

ultrasearch_portlet.ear 
            META-INF/ 
                      application.xml 
            query.war 
            agent/ 
            index.html

All the query JSP pages are contained in query.war. This file is a servlet 2.2 compliant Web application. You can deploy it alone with any servlet 2.2 engine. The context root for query.war is /provider/ultrasearch/. It is defined in the META-INF/application.xml of the ultrasearch_portlet.ear file. You can change it by editing this file.

The following Java libraries are needed for the Ultra Search Portlet:

$ORACLE_HOME/jdbc/lib/classes12.jar
$ORACLE_HOME/jdbc/lib/nls_charset12.zip
$ORACLE_HOME/lib/xmlparserv2.jar
$ORACLE_HOME/lib/activation.jar
$ORACLE_HOME/lib/mail.jar

Ultra Search Portlet uses the connection pooling functionality of J2EE container. You must define a container authenticated data source. This data source must return an Oracle connection. Oracle Corporation recommends using the Java class equal to oracle.jdbc.pool.OracleConnectionCacheImpl for this data source.

In addition, the data source should contain the field location equal to jdbc/UltraSearchPooledDS, username, password equal to the Ultra Search instance owner's database username, and password and URL equal to the JDBC connection string in the form of "jdbc:oracle:thin:@<database host>:<oracle port>:<oracle sid>".

See Also: "Editing the data-sources.xml File" for the data source configuration of Oracle J2EE container

Editing the data-sources.xml File

Note: This is available with iAS only.

Caution: Storage of clear database schema passwords in data-sources.xml is insecure. For secure storage, you must implement your own solution.

The Ultra Search iAS query API uses the data source functionality of the J2EE container. Under directory $ORACLE_HOME/j2ee/OC4J_Portal/config, edit the file data-sources.xml. Under tag <data-sources> add the following:

<data-source 
   class="oracle.jdbc.pool.OracleConnectionCacheImpl" 
   name="UltraSearchDS" 
   location="jdbc/UltraSearchPooledDS" 
   username="<username>" 
   password="<password>" 
   url="jdbc:oracle:thin:@<database_host>:<oracle_port>:<oracle_sid>"
/> 

where <username> and <password> are the Ultra Search instance owner's database username and password, <database_host> is the host name of the back end database machine, <oracle_port> is the port to the user's Oracle database, and <oracle_sid> is the SID of the user's Oracle database. In addition to username, password, and JDBC URL, data-sources.xml also allows configuration of the connection cache size, as well as the cache scheme. The following tag specifies the minimum and maximum limits of the cache size, the inactivity time-out interval, and the cache scheme.

<data-source 
   class="oracle.jdbc.pool.OracleConnectionCacheImpl" 
   name="UltraSearchDS" 
   location="jdbc/UltraSearchPooledDS" 
   username="wk_test" 
   password="wk_test" 
   url="jdbc:oracle:thin:@localhost:5521:isearch" 
   min-connections="3" 
   max-connections="30" 
   inactivity-timeout="30">
 <property name="cacheScheme"  value="1"/>
</data-source>

Note: The URL of the JDBC data source can be provided in the form of jdbc:oracle:thin:@[hostname]:[port]:[sid] or in the form of a TNS keyword-value syntax, such as "jdbc:oracle:thin:@(DESCRIPTION=(LOAD_BALANCE=yes)(ADDRESS_LIST=(ADDRESS=(PROTOCOL=TCP) (HOST=cls02a)(PORT=3999))(ADDRESS=(PROTOCOL=TCP) (HOST=cls02b)(PORT=3999)))(CONNECT_DATA= (SERVICE_NAME=acme.us.com)))"

There are three types of caching schemes:

• DYNAMIC_SCHEME = 1
• FIXED_WAIT_SCHEME = 2
• FIXED_RETURN_NULL_SCHEME = 3

  See Also: Oracle9iAS Containers for J2EE Services Guide

Editing the ultrasearch.properties File

The ultrasearch.properties file specifies which database the Web application and JSP applications connect to. Edit $ORACLE_HOME/ultrasearch/webapp/config/ultrasearch.properties to specify the hostname, port, and SID of the Oracle instance and listener.

To do this, edit the line that begins with "connection.url" to read: "connection.url=jdbc:oracle:thin:<hostname>:<port>:<SID>"

• For hostname, enter the full host name of the Oracle base instance running Ultra Search.
• For port, enter the listener port number for the Oracle9i database instance.
• For SID, enter the Oracle9i database instance ID.

Here is an example connection.url string:

connection.url=jdbc:oracle:thin:@ultrasearch.us.oracle.com:1521:myInstance

If you chose to configure the Ultra Search middle tier component with Oracle HTTP Server and Jserv, then you must also edit the line that begins with "admin.srchome" to read: "admin.srchome=<jsp_src_home>".

• For Solaris, enter "admin.srchome=$ORACLE_HOME/ultrasearch/webapp/isearch_admin"
• For NT, enter "admin.srchome=$ORACLE_HOME\\ultrasearch\\webapp\\isearch_admin"

Where $ORACLE_HOME is the Oracle home directory where the Ultra Search server component is installed.

This is the location of the Ultra Search administration tool JSP pages.

Note: You should not need to change the first line, because it is the name of the Oracle JDBC driver.

See Also: Your documentation on the Oracle JDBC driver

Starting the Web Server

With the iAS release only, if you allow Oracle Portal Configuration Assistant to configure the Web server for you, then you should start the Web server using the Enterprise Manager console.

See Also: Oracle9iAS Administrator's Guide for information on the Enterprise Manager console

With the database release, or if you choose to configure the Oracle HTTP server and OC4J manually, do the following:

• Start Oracle HTTP server by invoking $ORACLE_HOME/Apache/Apache/bin/spachectl stop followed by $ORACLE_HOME/Apache/Apache/bin/spachectl start.
• The default HTTP port is 7777. Change this by editing $ORACLE_HOME/Apache/Apache/conf/httpd.conf
• To test if the Oracle HTTP server is started, visit the Ultra Search welcome page: http://<hostname.domainname>:<HTTPport>/ultrasearch/index.html. This page provides general information about Ultra Search, and it also contains links to the Ultra Search administration tool, as well as Ultra Search sample query JSP page. However, the Ultra Search administration tool, Ultra Search sample query page, and the directory $ORACLE_HOME/ultrasearch/sample are not available after OC4J is started.
• If you deploy Ultra Search middle tier with OC4J, start OC4J by invoking java -jar $ORACLE_HOME/j2ee/home/oc4j.jar -config $ORACLE_HOME/j2ee/OC4J_Portal/config/server.xml
• Configuration can be made for OC4J to start automatically when Oracle HTTP server starts. See the OC4J documentation for more information.

Testing the Ultra Search Administration Tool

Check that the Web Server is running.

Test your changes by attempting to log on to the administration tool:

• Visit: http://<hostname.domainname>:<HTTPport>/ultrasearch/admin/index.jsp

  where <hostname.domainname> is the full name of the host where you have installed the Ultra Search middle tier component, and <HTTPport> is the default Web server port. If you are running the Web browser on the same host, then enter "localhost".

• During the installation of the Ultra Search server component, you should have created a new Ultra Search instance owner. The instance owner is created in Step 4 of the Ultra Search server component installation process. Log on to the Ultra Search administration tool by entering the Ultra Search instance owner's database username and password.
• The nature of JSP pages is such that the first time any page is accessed, it takes a few seconds to compile. Subsequent accesses are much faster.
• If you log on to the Ultra Search administration tool successfully, then you have completed the Ultra Search administration tool configuration process.

Testing the Ultra Search JSP Sample Query Applications

After you verify that the Ultra Search administration tool is working, you should be able to run the Ultra Search JSP sample query applications.

To test the Ultra Search JSP sample query applications, do one of the following:

• Visit http://<hostname.domainname>:<HTTPport>/ultrasearch/query/search.jsp
• Follow the links in the Ultra Search welcome page: http://<hostname.domainname>:<HTTPport>/ultrasearch/index.html

  See Also: "Configuring the Middle Tier Component with Oracle HTTP Server and OC4J" for information about configuring the JSP to query a specific instance

Locations for sample query applications are listed in the following section. Access the sample query source code by going to the directories list. You can also see a working demo of each sample query JSP page with the URL root, and you can append the correct JSP file name at the end of the URL root.

The root query directory is $ORACLE_HOME/ultrasearch/sample/query/.

The URL root for the query is http://<hostname.domainname>:<HTTPport>/ultrasearch/query/.

The 9iAS query (query sample JSP pages that use the 9iAS query API and include usearch.jsp and search.jsp) is in $ORACLE_HOME/ultrasearch/sample/query/.

The URL root for the 9iAS query is in http://<hostname.domainname>:<HTTPport>/ultrasearch/query/.

(For example: access search.jsp with http://<hostname.domainname>:<HTTPport>/ultrasearch/query/search.jsp.)

The 9i query (query JSP that uses the 9i query API and includes gsearch.jsp) is in $ORACLE_HOME/ultrasearch/sample/query/9i/.

The URL root for the 9i query is in http://<hostname.domainname>:<HTTPport>/ultrasearch/query/9i/.

Portlet is in $ORACLE_HOME/ultrasearch/sample/query/portlet/.

The URL root for Portlet is in http://<hostname.domainname>:<HTTPport>/ultrasearch/query/portlet/.

Taglib is in $ORACLE_HOME/ultrasearch/sample/query/tag/.

The URL root for taglib is in http://<hostname.domainname>:<HTTPport>/ultrasearch/query/tag/

Installing the Server Component on Remote Crawler Hosts

The Ultra Search remote crawler allows multiple crawlers to run in parallel on different hosts. However, all remote crawler hosts must share common resources, such as common directories and a common Ultra Search database.

Installing the Server Component on Remote Crawler Hosts

The Ultra Search remote crawler is part of the Ultra Search server component. Therefore, the installation procedure is the same as installing the Ultra Search server component.

On each remote crawler host, the Ultra Search server component is installed under a common directory known as the Oracle home. You should have been prompted by the Oracle Universal Installer to enter this directory. The Oracle home directory is referred to as $REMOTE_ORACLE_HOME.

If you choose not to install the Oracle HTTP server during the Oracle9i Application Server (9iAS) installation, then you must perform the following steps manually for remote crawling:

• Locate $REMOTE_ORACLE_HOME/ultrasearch/tools/remotecrawler/scripts/unix/define_env on a UNIX system or $REMOTE_ORACLE_HOME/ultrasearch/tools/remotecrawler/scripts/winnt/define_env.bat on a Windows NT system.
• Replace %ORACLE_HOME% with the value of the REMOTE_ORACLE_HOME environment variable.
• Replace %s_jreLocation% with the directory path of a Java runtime environment (JRE) version 1.2.2 and higher. You should specify the root directory of the JRE.
• Replace %s_jreJDBCclassfile% with the full path and file name of the Oracle JDBC thin driver (version 12).

Configuring the Server Component on Remote Crawler Hosts

The only configuration needed for an Ultra Search remote crawler host is to register the host with the Ultra Search system. The registration process is done by running a SQL script on the Ultra Search remote crawler host. The SQL script connects over SQL*Plus to the 9iAS middle tier and registers the remote crawler host.

1. Locate the correct Oracle home.

   The Ultra Search middle tier component is installed under a common directory known as the Oracle home. If you have installed other Oracle products prior to the Ultra Search middle tier component, then you could have multiple Oracle homes on your host. The registration script requires that you enter the Oracle home directory in which the Ultra Search middle tier component is installed.

2. Locate the WKSYS superuser password.

   You must run the registration script as the WKSYS superuser or as a database user that has been granted the WKADMIN role.

3. Start SQL*Plus.

   The SQL script is located in /ultrasearch/tools/remotecrawler/scripts/common/register.sql under $REMOTE_ORACLE_HOME.

   You must now run SQL*Plus. Be sure to run the correct version of SQL*Plus, because multiple versions can reside on the same host if you have previously installed some Oracle products. On UNIX platforms, make sure that the correct values for PATH, ORACLE_HOME and TNS_ADMIN variables are set. On Windows platforms, choose the correct menu item from the Start menu.

   After you have identified how to run the correct SQL*Plus client, you must log on to the Ultra Search database. To do this, you might need to configure an Oracle Net service setting for the Ultra Search database.

   See Also: Oracle9i Net Services Administrator's Guide for information on how to configure a service setting

   After SQL*Plus is running, log on to the database using the schema and password that you located in Step 2.

4. Invoke the registration script.

   Starting up SQL*Plus as the WKSYS superuser and enter the following:

   @<full path name of registration script>
   

   For example, if value for $REMOTE_ORACLE_HOME on a UNIX host is /home/oracle9i, then enter the following at the SQL*Plus prompt:

   @/home/oracle9i/ultrasearch/tools/remotecrawler/scripts/unix/register.sql
   

   If you are running SQL*Plus on Windows NT, and $REMOTE_ORACLE_HOME is in d:\Oracle\Oracle9i, then enter the following at the SQL*Plus prompt:

   @d:\Oracle\Oracle9i\ultrasearch\tools\remotecrawler\scripts\winnt\register.sql
   
   

   The registration script prompts you for two variables. The following is a list of the variables and their descriptions:

   REMOTE_CRAWLER_HOSTNAME: The DNS host name of the remote crawler host.

   ORACLE_HOME: The Oracle home located in Step 1. For example, /u01/oracle9i on a UNIX host or D:/u01/oracle9i on a Windows NT host. (Be careful to use forward slashes for Windows NT hosts.)

   The registration script invokes the wk_crw.register_remote_crawler PL/SQL API. The REMOTE_CRAWLER_HOSTNAME and ORACLE_HOME variables are used to compose arguments for the wk_crw.register_remote_crawler API.

5. Verify and complete the remote crawler profile configuration.

   Be sure to enter the correct values for both variables. To verify that the registration has completed correctly, log on to the Ultra Search administration tool. Click the Remote Crawler Profiles subtab in the Crawler tab. You should see the host name of the remote crawler host you have just registered in the remote crawler Profile List. Click Edit to complete the configuration process for the remote crawler profile.

What To Do if You Make a Mistake

If you enter any wrong values for the register.sql script, then you must unregister the remote crawler using the unregister.sql script. Invoke the unregister script the same way as you invoke the registration script. The unregister.sql script calls the wk_crw.unregister_remote_crawler PL/SQL API.

After you have successfully unregistered the remote crawler, you can rerun the register.sql script.