|Oracle® Ultra Search User's Guide
10g Release 1 (10.1)
Part Number B10731-01
This chapter contains the following topics:
Oracle Ultra Search hardware requirements are based on the quantity of data that you plan to process using Oracle Ultra Search. Oracle Ultra Search uses Oracle Text as its indexing engine and the Oracle database as its repository.
Along with the resource requirements for the database and the Text indexing engine, also consider the memory requirements of the Oracle Ultra Search crawler. The Oracle 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 Oracle 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 Oracle Ultra Search backend. However, you might want to install and run this on the same host as the Oracle 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.
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 Oracle Ultra Search backend.
15MB of disk space for the Oracle 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 Oracle 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 Oracle Ultra Search instance user's tablespace.
The Oracle 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 Oracle Ultra Search instance user. Make sure to assign that tablespace as the default tablespace of the Oracle Ultra Search instance user.
Oracle Ultra Search database schema—data dictionary and PL/SQL packages
Oracle Ultra Search crawler—Java program plus supporting files, libraries, and so forth.)
Oracle Ultra Search remote crawler—a crawler residing on a remote Oracle home
The Oracle 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, please refer to the Oracle Universal Installer Concepts Guide.
The Oracle 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.
The Oracle 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 Oracle Application Server 10g 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 Oracle Ultra Search you need to perform the following post-install configuration steps:
If not already present, install JDK 1.4.1 or later on the system on which the MR was installed.
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 Oracle Ultra Search backend where to find the Java executable.
Oracle Application Server MR can be installed on top of an existing database; this is the preferred way of installing Oracle 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 Oracle Ultra Search into an existing database.
ORACLE_HOME is where you want to install the Oracle Ultra Search backend. To install into an existing database, follow these steps:
$ORACLE_HOME/ultrasearch already exists, back it up by renaming it (for example,
$ORACLE_HOME/ultrasearch, where repca_dir represents the topmost directory on the RepCA CD, containing the
Change the current directory to
If the Oracle 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:
Next, execute 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 Oracle Ultra Search schema
tmptblspc—temporary tablespace for
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,
jdbcnls—path to nls_charset12.zip or orai18.jar (for example,
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 (for example,
jdbc_node—thin JDBC connect string, and only the part after the '@' (for example, host
: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 Oracle Ultra Search Schema Passwords" for information on changing the
See your installation guide for information on setting environment variables.
This section covers Oracle Ultra Search backend post-installation tasks.
The Oracle 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 Oracle Ultra Search to be able to use the INSO filter, the shared library path environment variable must contain the
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
After you have installed all Oracle Ultra Search components, you can optionally configure the Oracle database. See "Configuring the Oracle Server for Oracle Ultra Search" for more information.
Step 1: Check the database version requirements and configure Oracle Identity Management.
Before you can set up a secure Oracle Ultra Search installation, you must do the following:
Install or upgrade the Oracle database to 126.96.36.199 or higher. The middle tier and IM (identity management) version should be 9.0.4 or higher. If you have a 188.8.131.52 database, you can use
RepCA to convert a 184.108.40.206 database to an Oracle Application Server 9.0.4 metadata repository.
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, please 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 Oracle Ultra Search database is Oracle version 220.127.116.11 or higher and that the Oracle Ultra Search database is linked to a compatible instance of Oracle Internet Directory. This is necessary because Oracle 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-OID 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 Oracle Ultra Search, if necessary.
After you have configured the Oracle Ultra Search database to work with Oracle Internet Directory, you can install or upgrade the Oracle 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 Oracle Ultra Search ACLs in XML DB.
To create the
/sys/apps/ultrasearch folder, do the following:
Login to the Oracle Ultra Search database using SQL*Plus as user
Invoke the SQL script:
See Also:"Changing Oracle Ultra Search Schema Passwords" for information on changing the
Upon termination, the
wk0prepxdb.sql script lists all Oracle 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:
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 Oracle Ultra Search.
Because there is currently no way to programatically verify a proper Oracle-OID installation, the secure search functionality in Oracle 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 Oracle Ultra Search:
Login to the Oracle Ultra Search database using SQL*Plus as user
Invoke the following PL/SQL API:
(1) indicates that you are turning on secure search.
After you have turned on secure search functionality, you can create Oracle Ultra Search instances that are secure search-enabled.
Note:At any subsequent point in time, you can turn off security by invoking
Oracle 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:
Deploy Oracle Ultra Search query (
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>
applications/ultrasearch_query/META-INF/orion-application.xml to turn on JAZN LDAP.
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>
mod_osso in Apache.
/ultrasearch/query/usearch.jsp to see the login function, and test secure search.
See Also:"Secure Search "
If the database character set has been changed after Oracle Ultra Search installation, you must reconfigure the Oracle Ultra Search backend so that it can adapt to the new character set.
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
wk0idxcheck.sql also drops and recreates the Oracle Text index used by Oracle 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.
The Oracle Ultra Search installer creates a default out of the box Oracle Ultra Search instance based on the default Oracle Ultra Search test user. So, you can test Oracle 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
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 Oracle Ultra Search sample query application. Make sure to update the
The Oracle Ultra Search middle tier includes the following:
Oracle Ultra Search administration tool
Oracle Ultra Search Java query API
Oracle Ultra Search sample query applications
For the Oracle Application Server release, the Oracle 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 Oracle Ultra Search middle tier with the Application Server install.
For the database release, the Oracle Ultra Search middle tier is installed with the Oracle Ultra Search backend during the database server install. This is also part of the database client install. The Oracle Ultra Search middle tier is installed and configured with Oracle J2EE container (OC4J).
See Also:Oracle Application Server 10g 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 Oracle Ultra Search middle tier
The Oracle Ultra Search administration tool and the Oracle 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 Oracle 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 Oracle Ultra Search administration tool or Oracle Ultra Search sample query application. The URLs are described in the following section.
Figure 3-1 Oracle Ultra Search Architecture
To use the administration tool, your browser must be Netscape version 4.0 or Microsoft Internet Explorer version 4.0 or higher.
The Oracle 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 Oracle Ultra Search middle tier. For more information, see the Oracle Universal Installer Concepts Guide.
Use the following command to start the Oracle Ultra Search middle tier. You must run this command manually to bring up the Oracle Ultra Search middle tier after installation.
Use this command to stop the Oracle Ultra Search middle tier:
Start the OUI on the relevant host. Choose the destination
ORACLE_HOME name and full path, and complete the following steps:
Choose the option "OracleAS Application Server 10g" and click Next.
Choose the option "B. Portal and Wireless" and click Next.
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 Oracle 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.
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 Oracle Ultra Search EAR File on a Third Party Middle Tier". Upon completion of this step, all middle tier files are copied under the
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.
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
To deploy Oracle Ultra Search Web applications, you must have a J2EE 1.2 container. Oracle recommends using Apache Web server and OC4J.
See Also:"Deploying the Oracle Ultra Search EAR File on a Third Party Middle Tier" if you use a third party J2EE container or servlet engine
For OC4J configuration, modify the following OC4J configuration files:
$ORACLE_HOME/j2ee/OC4J_Portal/config/. The configuration of OC4J works with Oracle 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
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 Oracle Ultra Search EAR file, as well as define where this EAR files is.
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 Oracle Ultra Search administration tool and query Web applications to run.
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 Oracle Ultra Search EAR files is deployed.
The application field describes the application name. It should match the application name in
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
Note:The virtual path for a particular Web application is defined in three files:
Modify modOC4J configuration files. Add the following to
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
Oracle 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:
Note:The Oracle9i JSP files are being deprecated. It is not necessary to configure them if you do not plan to use them.
Note:Single sign-on is available only with the Oracle Identity Management infrastructure.
To configure the Oracle 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 ".
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" />
xml, under <web-site> tag, add the following:
<web-app application="UltrasearchAdmin" name="admin" root="/ultrasearch/admin_sso" />
Modify modOC4J configuration files. Add the following to
Oc4jMount /ultrasearch/admin_sso/* OC4J_Portal
Confirm the following:
$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>
Because Oracle 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 Oracle Ultra Search WAR file name, the predefined URL root, and the Java library required. The following section explains the Oracle 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.
The Oracle 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
Oracle Ultra Search sample query applications are Web applications contained in the
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
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
war. This file is a servlet 2.2 compliant Web application. Deploy it alone with any servlet 2.2 engine. The context root for
/ultrasearch/query. It is defined in the
xml of the
ear file. You can change it by editing this file.
The following are the Java libraries needed for Oracle 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
Oracle 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
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 Oracle 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
Oracle Ultra Search Portlet is a Web application contained in the
ear file. This file is compliant to the J2EE 1.2 standard. This file is similar to
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
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
/provider/ultrasearch/. It is defined in the
xml of the
ear file. You can change it by editing this file.
The following Java libraries are needed for the Oracle 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
Oracle 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
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 Oracle 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
Caution:Storing clear text passwords in
The Oracle 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
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 Oracle 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,
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 Oracle Ultra Search instance user
wk_test, then make sure to unlock
<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
There are three types of caching schemes:
DYNAMIC_SCHEME = 1
FIXED_WAIT_SCHEME = 2
FIXED_RETURN_NULL_SCHEME = 3
data-sources.xml file is located in the
$ORACLE_HOME/ultrasearch/webapp/config/ultrasearch.properties file contains configuration information used by Oracle 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
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
connection.driver specifies the JDBC driver you are using.
connection.url specifies the database to which the middle tier connects. Oracle Ultra Search supports following formats:
host:port:SID (where host is the full host name of the Oracle base instance running Oracle 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
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 Oracle Ultra Search middle tier application entity name.
domain specifies the common domain for the IM (identity management) machine and the Oracle Ultra Search middle tier machine. This enables delegated administrative service (DAS) list of values to work with Internet Explorer. For example, if the Oracle 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
See Also:Oracle Application Server 10g 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
Check that the Web Server is running.
Test your changes by attempting to log on to the administration tool:
where hostname.domainname is the full name of the host where you have installed the Oracle Ultra Search middle tier, and port is the default Web server port.
During the installation of the Oracle Ultra Search backend, a new ultrasearch instance owner,
WK_TEST is created. Log on to the Oracle Ultra Search administration tool by entering the Oracle 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 Oracle Ultra Search administration tool successfully, then you have completed the Oracle Ultra Search administration tool configuration process.
After you verify that the Oracle Ultra Search administration tool is working, you should be able to run the Oracle Ultra Search sample query applications.
To test the Oracle Ultra Search sample query applications, do one of the following:
Follow the links in the Oracle Ultra Search welcome page:
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
The URL root for the query is
The URL root for the Oracle Application Server query is in
Portlet is shipped as
The Oracle 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 Oracle Ultra Search database.
The Oracle Ultra Search remote crawler is part of the Oracle Ultra Search backend. Therefore, the installation procedure is the same as installing the Oracle Ultra Search backend
On each remote crawler host, the Oracle 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
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:
$REMOTE_ORACLE_HOME/ultrasearch/tools/remotecrawler/scripts/unix/define_env on a UNIX system or
bat on a Windows system.
%ORACLE_HOME% with the value of the
REMOTE_ORACLE_HOME environment variable.
%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.
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 Oracle Ultra Search remote crawler host. The SQL script connects over SQL*Plus to the Oracle backend database and registers the remote crawler host.
Locate the correct
The Oracle Ultra Search middle tier is installed under a common directory known as
ORACLE_HOME. If you have installed other Oracle products prior to the Oracle 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 Oracle Ultra Search middle tier is installed.
You must run the registration script as the
WKSYS super-user or as a database user that has been granted super-user privileges.
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
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 Oracle Ultra Search database. To do this, you might need to configure an Oracle Net service setting for the Oracle 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.
Invoke the registration script.
Start up SQL*Plus as the
WKSYS super-user and enter the following:
The registration script for RMI-based remote crawling is the following:
The registration script for JDBC-based remote crawling is the following:
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:
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:
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.
/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
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.
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 Oracle 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.
If you enter any wrong values for the
sql script, you should unregister the remote crawler using the
sql script. Invoke the unregister script the same way as you invoke the registration script. The
sql script calls the
unregister_remote_crawler PL/SQL API. After you have successfully unregistered the remote crawler, you can rerun the
Oracle Ultra Search is configured to be non-hosted during the default install. To change to a hosted environment, perform the following steps to configure Oracle Ultra Search in the 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
For each subscriber, run the following scripts to configure Oracle 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 Oracle Ultra Search metadata repository.
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 Oracle 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 Oracle 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