Skip Headers

Oracle® Ultra Search User's Guide
10g Release 1 (10.1)

Part Number B10731-02
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Feedback

Go to previous page
Previous
Go to next page
Next
View PDF

3 Installing and Configuring Ultra Search

This chapter contains the following topics:

Ultra Search Requirements

This section describes the Ultra Search system requirements.

Hardware Requirements

Ultra Search hardware requirements are based on the quantity of data that you plan to process using Ultra Search. Ultra Search uses Oracle Text as its indexing engine and the Oracle database as its repository.

Sufficient RAM  Along with the resource requirements for the database and the Text indexing engine, also consider the memory requirements of the Ultra Search crawler. The Ultra Search crawler is a pure Java program. Out of the box, when the crawler is launched, the JVM is configured to start with 25MB and grow to 256MB. When crawling very large amounts of data, these values might need to be adjusted.

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 backend. However, you might want to install and run this on the same host as the Ultra Search backend. Regardless of your choice, allocate enough memory for the J2EE engine. Oracle 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 3GB of disk space for the Oracle Application Server infrastructure or database and the Ultra Search backend.

  • 15MB of disk space for the Ultra Search middle tier on top of the Web server's disk requirements.

  • For each remote crawler host, the same amount of disk space as needed to install the Ultra Search backend.

  • Disk space for a large TEMPORARY tablespace. As a general guideline, create a TEMPORARY tablespace as large as possible, 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 must explicitly create. All data that is collected and processed as part of crawling and indexing 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 recommends using Oracle Application Server.

Installing the Ultra Search Backend

The Ultra Search backend consists of the following:

Database Release

The Ultra Search backend is installed as part of the Oracle Database Server install, which is accomplished using the Oracle Universal Installer (OUI). For more information, see the Oracle Universal Installer Concepts Guide.

Oracle Application Server Release

The Ultra Search backend is installed as part of the Oracle Application Server Metadata Repository (MR) creation; it can also be installed as a standalone component.

Installing As Part of Oracle Application Server Metadata Repository Creation

The Ultra Search backend is installed as part of the Oracle Application Server Metadata Repository (MR) creation. You can create the Metadata Repository using the Oracle Universal Installer (OUI), or you can create the MR on top of an existing customer database using RepCA (Repository Creation Assistant). For more information, refer to the Oracle9i Application Server Installation Guide and the Oracle Application Server Repository Creation Assistant guide, respectively.

IMPORTANT: If you are using RepCA to create the Metadata Repository, before you can use Ultra Search you need to perform the following post-install configuration steps:

  1. If not already present, install JDK 1.4.1 or later on the system on which the MR was installed.

  2. Go to the ultrasearch/admin directory of the RepCA CD. Then execute the wkrepca.sql script with SQL*Plus. You will have to connect as the wksys user and pass to the script the path to the JDK 1.4.1 or later Java executable. For example:

    sqlplus wksys/schema_password @repca_cd/ultrasearch/admin/wkrepca.sql
              /usr/local/jdk1.4/bin/java
    
    

    This will tell the Ultra Search backend where to find the Java executable.

Installing Into an Existing Database

Oracle Application Server MR can be installed on top of an existing database; this is the preferred way of installing Ultra Search into an existing database. Although doing so carries the overhead of installing every other Oracle Application Server component's schema, it does give you the benefits of Oracle Application Server infrastructure (well defined High Availability practices, automated IM integration and re-association, and so on). Nevertheless, you can install just Ultra Search into an existing database.

Let's assume ORACLE_HOME is where you want to install the Ultra Search backend. To install into an existing database, follow these steps:

  1. If $ORACLE_HOME/ultrasearch already exists, back it up by renaming it (for example, $ORACLE_HOME/ultrasearch.old)

  2. Copy repca_dir/ultrasearch to $ORACLE_HOME/ultrasearch, where repca_dir represents the topmost directory on the RepCA CD, containing the ultrasearch directory.

  3. Change the current directory to $ORACLE_HOME/ultrasearch/admin.

  4. If the Ultra Search schema, wksys, already exists on the target database, then uninstall it by executing:

    sqlplus /nolog @$ORACLE_HOME/ultrasearch/admin/wk0deinstall.sql "sys" syspw cstr
    
    

    Following is the meaning of each parameter:

  5. Next, run the SQL*Plus script wk0setup.sql. For example:

    sqlplus /nolog @$ORACLE_HOME/ultrasearch/admin/wk0setup.sql $ORACLE_HOME
       cstr "sys" syspw "as sysdba" wksyspw tblspc tmptblspc "portal"
       cfs "oui" psep jdbcdrv jdbcnls jexec ctxhx jdbc_node 
       jdbc_all $ORACLE_HOME
    
    

    where the various parameters are as follows (parameters should be enclosed in quotes to avoid misinterpretation):

    • cstr—TNS alias preceded with '@' (for example, @inst1), this parameter can also be passed in as a single white space (' ')

    • syspw—password for the sys database user/schema

    • wksyspw—password to be used for the Ultra Search schema wksys

    • tblspc—tablespace for wksys

    • tmptblspc—temporary tablespace for wksys

    • cfs—if ORACLE_HOME is on a Cluster File System (CFS) then 'true'; else 'false'

    • psep—path separator (for example, on UNIX this is ':', on Windows it is ';')

    • jdbcdrv—path to JDBC drivers, classes12.zip (for example, $ORACLE_HOME/jdbc/lib/classes12.zip)

    • jdbcnls—path to nls_charset12.zip or orai18.jar (for example, $ORACLE_HOME/jdbc/lib/nls_charset12.zip)

    • jexec—Java executable path (for example, /packages/jdk1.4.1/bin/java). Note that this has to point to a JDK 1.4.1 or later installation

    • ctxhx—path to INSOFILTER, ctxhx (for example, $ORACLE_HOME/ctx/bin/ctxhx)

    • jdbc_node—thin JDBC connect string, and only the part after the '@' (for example, host:port:sid); note that in case of RAC, this connect string must be to the current node

    • dbc_all— same as JDBC_NODE, but in case of RAC with CFS true, this JDBC string should include all the RAC nodes (hint: use TNS syntax)


See Also:

"Changing Ultra Search Schema Passwords" for information on changing the wksys password.

See your installation guide for information on setting environment variables.

Post-Installation Tasks for the Ultra Search Backend

This section covers Ultra Search backend post-installation tasks.

Enabling Ultra Search to Process Binary Files

The Ultra Search crawler uses the Oracle Text INSO filter, ctxhx, for processing of binary files. These are non text, non HTML files like PDF files, Microsoft Word files, and so on. For Ultra Search to be able to use the INSO filter, the shared library path environment variable must contain the $ORACLE_HOME/ctx/lib path.

At installation, the Oracle Installer automatically sets the variable to include $ORACLE_HOME/ctx/lib. However, if, after the installation, you restart the database, then you must manually set your shared library path environment variable to include $ORACLE_HOME/ctx/lib before starting the Oracle process. You must restart the database to pick up the new value for filtering to work.

For example, on UNIX set the $LD_LIBRARY_PATH environment variable to include $ORACLE_HOME/ctx/lib, and on Windows set the $PATH environment variable to include $ORACLE_HOME/bin.

Configure the Oracle Database for Ultra Search

After you have installed all Ultra Search components, you can optionally configure the Oracle database. See "Configuring the Oracle Server for Ultra Search" for more information.

Configure a Secure Ultra Search Installation

Step 1: Check the database version requirements and configure Oracle Identity Management.

Before you can set up a secure Ultra Search installation, you must do the following:

  • Install or upgrade the Oracle database to 9.2.0.4 or higher. The middle tier and IM (identity management) version should be 9.0.4 or higher. If you have a 9.2.0.4 database, you can use RepCA to convert a 9.2.0.4 database to an Oracle Application Server 9.0.4 metadata repository.

  • Install and configure the Oracle Internet Directory

    The middle tier and IM (identity management) version should be 9.0.4 or higher.

  • Register the database to Oracle Internet Directory.

    You can use repCA to register the database to Oracle Internet Directory. After registration, you need to perform these manual steps:

    • Add the distinguished name of the database to the database server parameter file, as an RDBMS_SERVER_DN initialization parameter value.

    • Restart the database, so that the new initialization parameter takes effect.

  • Configure the Oracle-Oracle Internet Directory SSL link. To establish a secure connection between database and Oracle Internet Directory, follow the instructions in the following books:

    • Configuring Oracle Internet Directory for SSL: "Chapter 13, Secure Sockets Layer (SSL) and the Directory," in the Oracle 9.2 release of the Oracle Internet Directory Administrator's Guide

    • Configuring the database for SSL: Chapter 15, "Managing Enterprise User Security" (Part II, Task 1 - Task 3), in the Oracle Database 9.2 release of the Oracle Advanced Security Administrator's Guide

Secure search functionality requires that the Ultra Search database is Oracle version 9.2.0.4 or higher and that the Ultra Search database is linked to a compatible instance of Oracle Internet Directory. This is necessary because Ultra Search utilizes XML DB functionality, which requires a certain version of Oracle. XML DB, in turn, requires a live link to Oracle Internet Directory, through which it retrieves all LDAP principal information. The Oracle-Oracle Internet Directory link must be running at all times for secure search to work. To set up this link, configure the Oracle Database to use Oracle Identity Management.

Step 2: Restart the Oracle listener.

In the previous step, you configured the Oracle Database to use Identity Management. That process involved configuring ORACLE_HOME for directory usage. You must make sure to restart the Oracle listener to inherit the changes made to ORACLE_HOME. Restart the listener, if you have not already done so.

Step 3: Install or upgrade Ultra Search, if necessary.

After you have configured the Ultra Search database to work with Oracle Internet Directory, you can install or upgrade the Ultra Search backend into the Oracle Server, if you have not already done so.

Step 4: Create the /sys/apps/ultrasearch folder.

Immediately after installation or upgrade, you must run a SQL script to create the /sys/apps/ultrasearch folder in the XML DB repository. This folder stores all Ultra Search ACLs in XML DB.

To create the /sys/apps/ultrasearch folder, do the following:

  1. cd to $ORACLE_HOME/ultrasearch/admin

  2. Login to the Ultra Search database using SQL*Plus as user WKSYS

  3. Invoke the SQL script: @wk0prepxdb.sql


See Also:

"Changing Ultra Search Schema Passwords" for information on changing the WKSYS password

Upon termination, the wk0prepxdb.sql script lists all Ultra Search-related XML DB resources by running the following SQL:

SELECT any_path FROM resource_view WHERE any_path LIKE '%ultrasearch%';

Execution of that SQL statement must show two rows:

/sys/apps/ultrasearch
/sys/apps/ultrasearch_acl.xml

If you do not see this confirmation, then this step has failed, and you cannot proceed. Recheck that all previous steps were performed correctly.

Step 5: Turn on secure search functionality in Ultra Search.

Because there is currently no way to programatically verify a proper Oracle-Oracle Internet Directory installation, the secure search functionality in Ultra Search is turned off by default. You must explicitly turn on this feature after completing all previous steps.

Step 6: Turn On Secure Search in the Query Application.

To turn on secure search functionality in Ultra Search:

  1. Login to the Ultra Search database using SQL*Plus as user WKSYS

  2. Invoke the following PL/SQL API: exec WK_ADM.SET_SECURE_MODE(1)

The argument (1) indicates that you are turning on secure search.

After you have turned on secure search functionality, you can create Ultra Search instances that are secure search-enabled.


Note:

At any subsequent point in time, you can turn off security by invoking WK_ADM.SET_SECURE_MODE(0). Doing so designates that any instances created after that will not support secure searches. However, existing secure search-enabled instances are not modified. Hence, if the Oracle-Oracle Internet Directory link ceases to function, you cannot perform searches on crawled documents that are secured.

Ultra Search supports secure searches, which return only documents satisfying the search criteria that the search user is allowed to view. To turn on secure search in the query application, follow these steps:

  1. Deploy Ultra Search query (ultrasearch_query.ear).

  2. Edit the OC4J jazn.xml file to connect to Oracle Internet Directory. For example:

    <jazn provider="LDAP" default-realm="us" location="ldap://localhost:3060">
         <property name="ldap.user" value="orcladmin"/> 
         <property name="ldap.password" value="!welcome"/> 
         </jazn>
    
    
  3. Restart OC4J.

  4. Edit applications/ultrasearch_query/META-INF/orion-application.xml to turn on JAZN LDAP.

  5. Edit applications/ultrasearch_query/query/WEB-INF/web.xml to enable login functionality in usearch.jsp. For example:

    <init-param> 
    <param-name>login enabled</param-name> 
    <param-value>true</param-value> 
    </init-param> 
    
    
  6. Enable mod_osso in Apache.

  7. Access http://hostname:port/ultrasearch/query/usearch.jsp to see the login function, and test secure search.


    See Also:

    "Secure Search"

Backend Reconfiguration After a Database Character Set Change

If the database character set has been changed after Ultra Search installation, you must reconfigure the Ultra Search backend so that it can adapt to the new character set.

Two SQL scripts (wk0prefcheck.sql and wk0idxcheck.sql), located in $ORACLE_HOME/ultrasearch/admin/, are used for this reconfiguration:

  • wk0prefcheck.sql is invoked under wksys to reconfigure default cache character set and index preferences.

  • wk0idxcheck.sql is needed for reconfiguring instance(s) created before the database character set change (for example, the default instance). This script must be invoked by the instance owner, and wk0prefcheck.sql must be run first, as it depends on reconfigured default settings generated by wk0prefcheck.sql.

    Running wk0idxcheck.sql also drops and recreates the Oracle Text index used by Ultra Search. If there are already data sources indexed, you must force a recrawl of all of the data sources.

    wk0idxcheck.sql must be run once for each instance. For example, if there are two instances, "inst1" and "inst2," owned by "owner1" and "owner2," respectively, then wk0idxcheck.sql should be run twice: once by "owner1" and once by owner2.

Configuring the Default Ultra Search Instance

The Ultra Search installer creates a default out of the box Ultra Search instance based on the default Ultra Search test user. So, you can test Ultra Search functionality based on the default instance after installation.

The default instance name is WK_INST. It is created based on the database user WK_TEST. The default user password is WK_TEST.

For security purposes, WK_TEST is locked after the installation. The administrator should login to the database as DBA role, unlock the WK_TEST user account, and set the password to be WK_TEST. (The password expires after the installation.) If the password is changed to anything other than WK_TEST, then you must also update the cached schema password using administration tool Edit Instance page after you change the password in the database.

The default instance is also used by the Ultra Search sample query application. Make sure to update the data-sources.xml file.

Installing the Ultra Search Middle Tier on Web Server Hosts

The Ultra Search middle tier includes the following:

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

For the database release, the Ultra Search middle tier is installed with the Ultra Search backend during the database server install. This is also part of the database client install. The Ultra Search middle tier is installed and configured with Oracle J2EE container (OC4J).


See Also:

Oracle9i Application Server Administrator's Guide for information on how to change the Infrastructure Services (for example, a different Oracle Internet Directory or Metadata Repository) used by an Ultra Search middle tier

Web Applications Concepts

The Ultra Search administration tool and the Ultra Search query applications are J2EE-compliant Web applications. These are three tier architecture applications. Figure 3-1 shows the relationship between the browser (the first tier), the Web server and the servlet engine (the middle tier), and the Oracle Database (the third tier).

The Web server accepts requests from the browser and forwards the requests to the servlet engine for processing. The Ultra Search middle tier then communicates with the Oracle database through the JDBC, as in Figure 3-1.

You can use any browser to access the Ultra Search administration tool or Ultra Search sample query application. The URLs are described in the following section.

Figure 3-1 Oracle Ultra Search Architecture

Description of isrch010.gif follows
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 with the Oracle Database Release

The Ultra Search middle tier is installed as part of the Oracle Database Server install, which is accomplished using the Oracle Universal Installer (OUI).

The Oracle Universal Installer automatically configures the Ultra Search middle tier. For more information, see the Oracle Universal Installer Concepts Guide.

However, with a software-only or an advanced database installation, you must manually configure the Ultra Search administration tool by editing the file $ORACLE_HOME/ultrasearch/webapp/config/ultrasearch.properties. Two items in this file are configured incorrectly. You must replace %THIN_JDBC_CONN_STR% with a JDBC string to the database, and replace %DOMAIN% with the domain name.

Use the following command to start the Ultra Search middle tier. You must run this command manually to bring up the Ultra Search middle tier after installation.

$ORACLE_HOME/bin/searchctl start

Use this command to stop the Ultra Search middle tier:

$ORACLE_HOME/bin/searchctl stop

Installing the Middle Tier with the Oracle Application Server Release

Start the OUI on the relevant host. Choose the destination ORACLE_HOME name and full path, and complete the following steps:

  1. Choose the option "OracleAS Application Server 10g" and click Next.

  2. Choose the option "B. Portal and Wireless" and click Next.

  3. On the "Configuration Options" screen, make sure "OracleAS Portal" is checked. This allows the Oracle Portal Configuration Assistant (OPCA) to configure Oracle HTTP Server and OC4J with Ultra Search. If you uncheck this option, then you must follow the instructions under "Configuring the Middle Tier with Oracle HTTP Server and OC4J" to set up Oracle HTTP Server and OC4J manually.

  4. Continue with the installation until Oracle Application Server is successfully installed.


    Note:

    If you decide to use a third party J2EE container or a servlet engine, then uncheck the option "OracleAS Portal" on the "Configuration Options" 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 files are copied under the $ORACLE_HOME.

If you checked the "OracleAS Portal" option on the "Configuration Options" Oracle Installer screen, then the configuration steps in the following section are automatically performed by the Oracle Portal Configuration Assistant (OPCA).

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

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


See Also:

Configuring the Middle Tier with Oracle HTTP Server and OC4J


Note:

For Oracle Database, Oracle Containers for J2EE (OC4J) is configured by default. You can still configure the HTTP Server and OC4J, but they will be in a different ORACLE_HOME.

To deploy Ultra Search Web applications, you must have a J2EE 1.2 container. Oracle recommends using Apache Web server and 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:

    Oracle Application Server Containers for J2EE documentation for more information on deploying EAR and WAR applications and for the more advanced functionality of OC4J
    • For server.xml, under the <application-server> tag, add the following:

      <application name="UltrasearchAdmin" path="$ORACLE_HOME/ultrasearch/webapp/ultrasearch_admin.ear" /> 
      
      <application name="UltrasearchQuery" path="$ORACLE_HOME/ultrasearch/ultrasearch_query.ear" /> 
      
      <application name="UltrasearchPortlet" 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 your own query Web pages. For more information on this directory, see "Testing the Ultra Search Sample Query Applications".
    • For application.xml, under the <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/jdbc/lib/nls_charset12.zip" />
      <library path="$ORACLE_HOME/jlib/repository.jar"/>
      <library path="$ORACLE_HOME/jlib/ohw.jar"/>
      <library path="$ORACLE_HOME/jlib/ldapjclnt9.jar"/>
      <library path="$ORACLE_HOME/j2ee/home/jazn.jar"/>
      <library path="$ORACLE_HOME/portal/jlib/ptlshare.jar"/>
      <library path="$ORACLE_HOME/portal/jlib/pdkjava.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

      Under <web-site> tag, add the following:

      <web-app application="UltrasearchQuery" name="query" 
           root="/ultrasearch/query" />
      <web-app application="UltrasearchQuery" name="welcome"
           root="/ultrasearch" />
      <web-app application="UltrasearchAdmin" name="admin"
           root="/ultrasearch/admin" />
      <web-app application="UltrasearchAdmin" name="admin_sso"
           root="/ultrasearch/admin_sso" />
      <web-app application="UltrasearchAdmin" name="ohw"
           root="/ultrasearch/ohw" />
      
      

      The preceding lines describe which Web application (WAR file) in the Ultra Search EAR files is 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.

      • For 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:port/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.
  2. Modify modOC4J configuration files. Add the following to $ORACLE_HOME/Apache/Apache/conf/mod_oc4j.conf:

    Oc4jMount /ultrasearch/             OC4J_Portal 
    Oc4jMount /ultrasearch/*            OC4J_Portal 
    Oc4jMount /ultrasearch/query        OC4J_Portal 
    Oc4jMount /ultrasearch/query/*      OC4J_Portal 
    Oc4jMount /ultrasearch/ohw          OC4J_Portal 
    Oc4jMount /ultrasearch/ohw/*        OC4J_Portal 
    Oc4jMount /ultrasearch/admin_sso    OC4J_Portal 
    Oc4jMount /ultrasearch/admin_sso/*  OC4J_Portal 
    Oc4jMount /ultrasearch/admin        OC4J_Portal 
    Oc4jMount /ultrasearch/admin/*      OC4J_Portal 
    
    
  3. Ultra Search sample pages require JDBC connections to the database as the instance owner. Due to JServ limitations in the Oracle9i release, the user name, password and connection string used to create the JDBC connection are hard-coded inside the sample JSP code. To configure the JSP to query a specific instance, edit the JSP source code, and replace the user name, password, and connection string values. All sample JSP source code is in the OC4J applications directory.

    The following files contain user name, password, and connection string values:

    • 9i/gsearch.jsp

    • 9i/display.jsp

    • 9i/gsearchf.jsp

    • 9i/gutil.jsp

    • 9i/mail.jsp


      Note:

      The Oracle9i 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:

Single sign-on is available only with the Oracle Identity Management infrastructure.

To configure the Ultra Search administration tool with the Oracle Single Sign-On (SSO) server, you must also follow these steps in addition to the configuration in "Configuring the Middle Tier 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="UltrasearchAdmin" name="admin" root="/ultrasearch/admin_sso" /> 
      
      
  2. Modify modOC4J configuration files. Add the following to mod_oc4j.conf:

    Oc4jMount /ultrasearch/admin_sso/*  OC4J_Portal 
    
    
  3. Confirm the following:

    • $ORACLE_HOME/Apache/Apache/conf/httpd.conf includes oracle_apache.conf

    • $ORACLE_HOME/Apache/Apache/conf/oracle_apache.conf includes ultrasearch.conf

    • $ORACLE_HOME/ultrasearch/webapp/config/ultrasearch.conf has the following content:

      # add alias for ultra search online help and welcome page

      Alias /ultrasearch/doc/ "/private/nli/ora9ias/ultrasearch/doc/"

      Alias /ultrasearch/ "/private/nli/ora9ias/ultrasearch/sample/"

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

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 deploy in a standard J2EE 1.2 container. It does not contain information on the configuration of each J2EE 1.2 container.


See Also:

Deploying the Administration Tool

The Ultra Search administration tool is a J2EE-compliant Web application ($ORACLE_HOME/ultrasearch/webapp/ultrasearch_admin.ear). You can use Enterprise Manager to deploy/undeploy this Web application.

To see the file structure of ultrasearch_admin, run the following command:

jar -tvf ultrasearch_admin.ear 
          META-INF/ 
          META-INF/application.xml 
          META-INF/orion-application.xml 
          admin.war 
          admin_sso.war 
          ohw.war 
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 following command:

jar tf ultrasearch_query.ear 

   META-INF/application.xml 
   META-INF/orion-application.xml 
   query.war 
   welcome.war 
   rewriter/SampleRewriter.java 
   agent/SampleAgent.java 
   agent/README.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/ldap/jlib/ldapclnt9.jar 
$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 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, user name, password equal to the Ultra Search instance owner's database user name, and password and URL equal to the JDBC connection string in the form of "jdbc:oracle:thin:@database_host: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 following 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 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, user name, password equal to the Ultra Search instance owner's database user name, 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


Caution:

Storing clear text passwords in data-sources.xml poses a security risk. Avoid this by using password indirection to specify the password. This lets you enter the password in jazn-data.xml, which automatically gets encrypted, and point to it from data-sources.xml. For more information, see "Creating An Indirect Password" in Oracle9iAS Containers for J2EE Security Guide.
Oracle Application Server Infrastructure  The Ultra Search Oracle Application Server 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 user name and password, database_host is the host name of the back end database computer, 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 user name, 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.

If you are adding the data source for the default Ultra Search instance user wk_test, then make sure to unlock wk_test first.

<data-source 
   class="oracle.jdbc.pool.OracleConnectionCacheImpl" 
   name="UltraSearchDS" 
   location="jdbc/UltraSearchPooledDS" 
   username="wk_test" 
   password="wk_test" 
   url="jdbc:oracle:thin:@localhost:1521: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:

Oracle Database

The data-sources.xml file is located in the $ORACLE_HOME/oc4j/j2ee/OC4J_SEARCH/config directory.

Editing the ultrasearch.properties File

The $ORACLE_HOME/ultrasearch/webapp/config/ultrasearch.properties file contains configuration information used by Ultra Search middle tier. You do not need to edit this file, because it is automatically configured by the Oracle installer.

Here is an example of the ultrasearch.properties file:

connection.driver=oracle.jdbc.driver.OracleDriver
connection.url=jdbc:oracle:thin:@ldap://dlsun8888.cn.oracle.com:3060/iasdb,cn=oraclecontext
oracle.net.encryption_client=REQUESTED
oracle.net.encryption_types_client=(RC4_56,DES56C,RC4_40,DES40C)
oracle.net.crypto_checksum_client=REQUESTED
oracle.net.crypto_checksum_types_client=(MD5)
oid.app_entity_cn=m16bi.sgtcnsun03.cn.oracle.com
domain=us.oracle.com

Where

  • connection.driver specifies the JDBC driver you are using.

  • connection.url specifies the database to which the middle tier connects. Ultra Search supports following formats:

    • host:port:SID (where host is the full host name of the Oracle base instance running Ultra Search, port is the listener port number for the Oracle Database instance, and SID is the Oracle Database instance ID)

    • HA-aware string (for example, TNS keyword-value syntax)

    Here is an example connection.url string:

    connection.url=jdbc:oracle.thin:@ultrasearch.us.oracle.com:1521:myInstance
    
    
  • oracle.net.encryption_client, oracle.net.encryption_types_client, oracle.net.crypto_checksum_client, and oracle.net.crypto_checksum_types_client control the properties of the secure JDBC connection made to the database. See Oracle Database JDBC Developer's Guide and Reference for more information.

  • oid.app_entity_cn specifies the Ultra Search middle tier application entity name.

  • domain specifies the common domain for the IM (identity management) machine and the Ultra Search middle tier machine. This enables delegated administrative service (DAS) list of values to work with Internet Explorer. For example, if the Ultra Search middle tier in us.oracle.com and the IM machine is uk.oracle.com, then the common domain is oracle.com. Add the following line in ultrasearch.properties: domain=oracle.com

Starting the Web Server

With the Oracle Application Server release, start the Web server using the Oracle Enterprise Manager Application Server Control.


See Also:

Oracle9i Application Server Administrator's Guide for information on the Application Server Control

With the database release, do the following:

java -jar $ORACLE_HOME/oc4j/j2ee/home/oc4j.jar -config 
$ORACLE_HOME/oc4j/j2ee/OC4J_SEARCH/config/server.xml

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:port/ultrasearch/admin/index.jsp

    where hostname.domainname is the full name of the host where you have installed the Ultra Search middle tier, and port is the default Web server port.

  • During the installation of the Ultra Search backend, a new ultrasearch instance owner, WK_TEST is created. Log on to the Ultra Search administration tool by entering the Ultra Search instance owner's database user name 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 Sample Query Applications

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

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

  • Visit http://hostname.domainname:port/ultrasearch/query/search.jsp

  • Follow the links in the Ultra Search welcome page: http://hostname.domainname:port/ultrasearch/index.html


    See Also:

    "Configuring the Middle Tier 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 sample query application is shipped as $ORACLE_HOME/ultrasearch/ultrasearch_query.ear.

The URL root for the query is http://hostname.domainname:port/ultrasearch/query/.

The URL root for the Oracle Application Server query is in http://hostname.domainname:port/ultrasearch/query/.

Portlet is shipped as $ORACLE_HOME/ultrasearch/webapp/ultrasearch_portlet.ear.

Installing the Backend 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 Backend on Remote Crawler Hosts

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

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

If you choose not to install the Oracle HTTP Server during the Oracle Application Server 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 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 Remote Crawler

The remote crawler requires a communication channel between the backend database and the remote crawler host.

There are two modes of communication: RMI and JDBC. Configuration of the remote crawler differs depending on which mechanism you use. The primary difference is that the JDBC-based mechanism requires you to supply a database user (or role) during the registration process.


See Also:

"Using the Remote Crawler" more information on the RMI and JDBC mechanisms

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 Oracle backend database and registers the remote crawler host.

  1. Locate the correct ORACLE_HOME.

    The Ultra Search middle tier is installed under a common directory known as ORACLE_HOME. If you have installed other Oracle products prior to the Ultra Search middle tier, 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 is installed.

  2. Locate the WKSYS super-user password.

    You must run the registration script as the WKSYS super-user or as a database user that has been granted super-user privileges.

  3. Start 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:

    Oracle 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.

    Start up SQL*Plus as the WKSYS super-user and enter the following:

    @full_path_of_registration_script
    
    
    

    The registration script for RMI-based remote crawling is the following:

    $REMOTE_ORACLE_HOME/ultrasearch/tools/remotecrawler/scripts/<platform>/register.sql
    
    

    The registration script for JDBC-based remote crawling is the following:

    $REMOTE_ORACLE_HOME/ultrasearch/tools/remotecrawler/scripts/<platform>/register_jdbc.sql
    
    

    For example, if the value for $REMOTE_ORACLE_HOME on a UNIX host is /home/oracle9i, then enter the following at the SQL*Plus prompt to register an RMI-based remote crawler:

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

    Likewise, if you are running SQL*Plus on Windows, and $REMOTE_ORACLE_HOME is in d:\Oracle\Oracle9i, then enter the following at the SQL*Plus prompt to register a JDBC-based remote crawler:

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

    The RMI-based registration script prompts you for three variables:

    • RMI_HOSTNAME: The remote hostname. This is where the RMI registry/daemon will run.

    • RMI_REGISTRY_PORT: The port that the RMI registry is listening on.

    • ORACLE_HOME: The Oracle home located in Step 1.

      For example, /u01/oracle9i on a UNIX host or d:/u01/oracle9i on a Windows host. (Remember to use forward slashes for Windows hosts.)

    The JDBC-based registration script prompts you for three variables:

    • LAUNCHER_NAME: An arbitrary string used to identify a JDBC-based remote crawler launcher, which is needed when you start up the JDBC-based remote crawler launcher

    • CONNECTUSER: The database user (or role) that the JDBC-based remote crawler launcher will use to establish a database connection and listen for launch events

    • ORACLE_HOME: The Oracle home located in Step 1

    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. You may optionally choose to call this API, especially if you need to register multiple remote crawlers programatically.

  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 remote crawler launcher you registered in the remote crawler profile list. For RMI-based remote crawlers, you will see the host:port combination that uniquely identifies the RMI-subsystem. For JDBC-based remote crawlers, you will see the Launcher name. Click Edit to complete the configuration process for the remote crawler profile.

Unregistering a Remote Crawler

If you enter any wrong values for the register.sql script, you should 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.

Configuring Ultra Search in a Hosted Environment

Ultra Search is configured to be non-hosted during the default install. To change to a hosted environment, perform the following steps to configure Ultra Search in the hosted environment.

Preconfiguration Tasks for a Hosted Environment

Make sure the hosting mode is enabled. Also, make sure the subscriber is created in the Oracle Internet Directory server.


See Also:

OracleAS Portal Configuration Guide section Enabling Hosting on an Out-of-Box Portal for instructions on how to enable the hosting mode, and section Adding Subscribers for instructions on how to add a subscriber to the SSO/Oracle Internet Directory

Configuring Ultra Search in the Subscriber Context

For each subscriber, run the following scripts to configure Ultra Search in the Oracle Internet Directory subscriber context. The script does the following:

  • Creates the reference objects in the subscriber context.

  • Creates default privilege group entry in the subscriber context.

  • Updates the subscriber information in the Ultra Search metadata repository.

Script usage:

ORACLE_HOME/ultrasearch/setup/usca.sh -action add_subscriber -user OID_user_DN
    -password orcladmin_password -subscriber subscriber_DN

The Oracle Internet Directory user must have the 'iASAdmins' privilege. Before you run the script, make sure you have the execute permission on the script, and setup the ORACLE_HOME environment variable.

The following example configures Ultra Search in the subscriber 'dc=us, dc=oracle, dc=com':

ORACLE_HOME/ultrasearch/setup/usca.sh -action add_subscriber -user
  'cn=orcladmin' -password welcome1 -subscriber 'dc=us,dc=oracle,dc=com'

To drop the subscriber, first perform the following script to remove Ultra Search entries from the Oracle Internet Directory subscriber context:

ORACLE_HOME/ultrasearch/setup/usca.sh -action remove_subscriber 
    -user OID_user_DN -password orcladmin_password -subscriber subscriber_DN