|
Oracle® Ultra Search User’s Guide
10g (9.0.4) Part No. B10896-01 |
|
|
|
|
Oracle® Ultra Search User’s Guide
10g (9.0.4) Part No. B10896-01 |
|
|
|
|
This chapter contains the following topics:
To use Oracle Ultra Search, you must install the following components with the Oracle Universal Installer:
Ultra Search backend (server component)
Ultra Search repository
Ultra Search crawler
Ultra Search middle tier
Ultra Search administration tool
Ultra Search query API
|
Note: By default, the Ultra Search crawler resides in the ORACLE_HOME of the database that contains the Ultra Search repository. You can install additional Ultra Search crawler components on other Oracle homes, usually on remote hosts. These are called remote crawlers, and they provide an effective way to deal with the scalability of the system. |
The Ultra Search backend (server component) can be installed on any already existing database that is Oracle Database release 9.0.1.4 or higher with Oracle Text installed.
ORACLE_HOME refers to the Oracle home directory containing the Ultra Search backend (server component) or middle tier bits.
REMOTE_ORACLE_HOME refers to the Oracle home directory containing the Ultra Search remote crawler bits.
The following section describes the Ultra Search system requirements.
Ultra Search hardware requirements very 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.
|
See Also: Oracle Text Application Developer's Guide and Oracle9i Database Performance Tuning Guide and Reference |
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 (server component). 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.
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 OracleAS infrastructure or database and the Ultra Search backend (server component).
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.
The Ultra Search backend (server component) is included as part of the Oracle database. It is installed during the Oracle database installation. It is installed in the same Oracle home directory as the database server tier.
The Ultra Search backend consists of the following:
Ultra Search data dictionary and PL/SQL packages
Ultra Search crawler Java classes
Ultra Search remote crawler
Ultra Search product libraries
Start up the Oracle Universal Installer (OUI) on the relevant host. After choosing the destination Oracle home name and full path, choose the option "Oracle9i Server." Ultra Search backend (server component) is installed with the Oracle database by default.
Start up the OUI on the relevant host. After choosing the destination Oracle home name and full path, choose the option "OracleAS Infrastructure 10g" Ultra Search backend (server component) is installed with the OracleAS infrastructure by default.
During the installation of OracleAS or the Oracle database server, the Ultra Search backend is installed. The following activity occurs during this process:
All Ultra Search backend files are copied into a directory named "ultrasearch". This directory resides immediately under the ORACLE_HOME of the designated database installation.
The database user WKSYS with a randomized password is created. You should change this password later for security purposes. All Ultra Search database objects are installed in this user's schema.
Various PL/SQL scripts are run against the database as user WKSYS. These scripts install and create various database objects.
|
See Also: "Changing Ultra Search Schema Passwords" for information on changing theWKSYS password
See your installation guide for information on setting necessary environment variables. |
The Ultra Search crawler uses the Oracle Text INSO filter ctxhx, which requires that your shared library path environment variable contain the $ORACLE_HOME/ctx/lib path. Without that, filtering fails for any binary document.
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.
After you have installed all Ultra Search components, you can optionally configure the Oracle database. This is a post-installation operation.
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. You can use RepCA to convert a 9.2.0.4 database to an iAS 9.0.4 metadata repository.
Configure the Oracle-OID link
Secure search functionality requires that the Ultra Search database is Oracle version 10.1.0 or higher and that the Ultra Search database is linked to a compatible instance of OID. 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 OID, 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.
|
See Also: Oracle9i Database Administrator's Guide for details on configuring the database to use Oracle Identity Management and OID |
Step 2: Restart the Oracle listener.
In the previous step, you configured the Oracle Database to use Identity Management. That process involved configuring the Oracle Home for directory usage. You must make sure to restart the Oracle listener to inherit the changes made to the 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 OID, you can install or upgrade the Ultra Search backend (server component) 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:
cd to $ORACLE_HOME/ultrasearch/admin
Login to the Ultra Search database using SQL*Plus as user WKSYS
Invoke the SQL script: @wk0prepxdb.sql
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-OID 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:
Login to the Ultra Search database using SQL*Plus as user WKSYS
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 invokingWK_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-OID 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:
Deploy Ultra Search query (sample.ear).
Edit the OC4J jazn.xml file to connect to OID. 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>
Restart OC4J.
Edit applications/ultrasearch_query/META-INF/orion-application.xml to turn on JAZN LDAP.
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>
Enable mod_osso in Apache.
Access http://<hostname>:<port>/ultrasearch/query/usearch.jsp to see the login function, and test secure search.
The Ultra Search backend (server component) can be installed on top of an existing Oracle 9i or later database. This can be done in two ways:
Install Oracle Portal on to a database with the Oracle Portal Configuration Assistant (OPCA). This will also install Ultra Search.
Use repCA to create an Oracle 10g Application Metadata Repository. As part of this process, Ultra Search is installed. This is probably the easiest way, but it comes with an overhead of having all OracleAS component schemas also installed on the target database.
|
Note: This feature is supported on the OracleAS release only.Because the repCA approach is discussed in the "Using an Existing Database for the OracleAS Metadata Repository" section of the Oracle Application Server 10g Installation Guide, this section covers only the database install with OPCA. |
The database has the following requirements:
The Java development kit (JDK) must be release 1.2.207 or higher.
The Oracle database must be Oracle9i release 1 (9.0.1.4) or higher.
The initialization parameter file must have JOB_QUEUE_PROCESSES set to two or higher.
Oracle Text must be installed in the database. Oracle Text provides the text indexing and search capabilities required to index and query data retrieved from your data sources, such Web sites or database tables.
|
Note: To run the crawler, Ultra Search requires a Java 1.2 compliant runtime environment (JDK) to be installed on the database computer. |
Follow these steps to install the backend (server component) on an existing Oracle9i database:
Launch the Oracle Portal Configuration Assistant (OPCA) to install Portal into the customer database. OPCA also installs the Ultra Search schema and database objects. If OPCA detects that the Ultra Search system schema WKSYS already exists, and the Ultra Search release is not the latest release, then it asks you to choose from the following three options:
Deinstall/Reinstall: This drops the existing WKSYS user, creates a new WKSYS user, and reloads the Ultra Search packages. All data collected by Ultra Search is deleted.
Migrate: This asks you to follow the instructions on the Ultra Search migration document for manual migration.
Abort: This stops OPCA from loading Ultra Search PL/SQL database packages into the existing database.
|
Note: You should immediately change theWKSYS password to avoid security problems. For details, see "Changing Ultra Search Schema Passwords".
OPCA configures OracleAS to work with Ultra Search. Configuration involves the following files: |
Transfer files and configure the database. Ultra Search requires that certain files exist on the database tier’s file system. Because the database tier might exist in a physically unreachable place, and because neither the Oracle Universal Installer nor OPCA have access to the remote database tier’s file system, you must manually copy the necessary files. In the ORACLE_HOME/ultrasearch/setup/ directory, there are several files including setupDB.jar, setupDB.bat, setupDB.csh, and setupDB.sh. Copy these files to the ORACLE_HOME of your remote database tier.
Set the files to the correct location by running the following scripts for your operating system.
For Windows: Edit setupDB.bat using any text editor. After the line "set ORACLE_HOME=" put the directory name where you installed the Oracle database. Save the change and run setupDB.bat by double clicking setupDB.bat or by running setupDB in the command prompt.
For UNIX: Run setupDB.sh under the Bourne shell prompt. The system sets the current directory as ORACLE_HOME and asks for the path to your JDK_HOME. If the default path to the jar executable or Java executable is not correct, then the system asks for the path to JDK. If you do not have JDK installed, then download the latest JDK and run setupDB.sh again.
|
Note: To run this script, the executable bit ofsetupDB.sh should be turned on.
|
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.
The Ultra Search middle tier includes the following:
Ultra Search administration tool
Ultra Search Java query API
Ultra Search sample query applications
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 (server component) 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: 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 Ultra Search middle tier |
The Ultra Search administration tool and the Ultra Search query applications are J2EE-compliant Web applications. These are three tier architecture applications. Figure 2-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 2-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.
To use the administration tool, your browser must be Netscape version 4.0 or Microsoft Internet Explorer version 4.0 or higher.
Choose the installation option. Start up OUI on the relevant host. Choose to install the Oracle9i client. Make sure to choose the "Administrator Install" or the "Custom Install" option. The OUI prompts for an Oracle home directory in which to install the middle tier. This directory is referred to as $ORACLE_HOME.
OUI automatically configures the Ultra Search middle tier with Oracle J2EE container (OC4J). Proceed to "Editing the ultrasearch.properties File" on page 2-24.
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 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.
Continue with the installation until OracleAS 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). Proceed directly "Editing the data-sources.xml File".
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:
|
|
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 |
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: OracleAS 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 <application-server> tag, add the following:
<application name="UltrasearchAdmin" path="$ORACLE_HOME/ultrasearch/webapp/ultrasearch_admin.ear" /> <application name="UltrasearchQuery" path="$ORACLE_HOME/ultrasearch/sample.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 <orion-application> tag, add the following:
<library path="$ORACLE_HOME/ultrasearch/lib/ultrasearch_query.jar" /> <library path="$ORACLE_HOME/ultrasearch/webapp/config" /> <library path="$ORACLE_HOME/jlib/uix2.jar" /> <library path="$ORACLE_HOME/jlib/share.jar" /> <library path="$ORACLE_HOME/jlib/regexp.jar" /> <library path="$ORACLE_HOME/lib/mail.jar" /> <library path="$ORACLE_HOME/lib/activation.jar" /> <library path="$ORACLE_HOME/lib/xmlparserv2.jar" /> <library path="$ORACLE_HOME/jdbc/lib/nls_charset12.zip" /> <library path="$ORACLE_HOME/jdbc/lib/classes12.jar" />
The preceding libraries are required for the Ultra Search administration tool and query Web applications to run.
|
Note: $ORACLE_HOME/ultrasearch/webapp/config contains the ultrasearch.properties file. For more information, see "Editing the ultrasearch.properties File".
|
For default-web-site.xml
Under <web-site> tag, add the following:
<web-app application="UltrasearchAdmin" name="admin" root="/ultrasearch/admin" /> <web-app application="UltrasearchQuery" name="query" root="/ultrasearch/query" /> <web-app application="UltrasearchPortlet" name="query" root="/provider/ultrasearch" />
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.
|
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
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. |
|
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 ".
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" />
Modify modOC4J configuration files. Add the following to mod_oc4j.conf:
Oc4jMount /ultrasearch/admin_sso/* OC4J_Portal
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>
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:
|
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
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 sample.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 |
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 |
|
Caution: Storing clear text passwords indata-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 Oracle Application Server Containers for J2EE Security Guide.
|
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:5521:isearch" min-connections="3" max-connections="30" inactivity-timeout="30"> <property name="cacheScheme" value="1"/> </data-source>
There are three types of caching schemes:
DYNAMIC_SCHEME = 1
FIXED_WAIT_SCHEME = 2
FIXED_RETURN_NULL_SCHEME = 3
For the database release, follow the same directions as earlier. However, the data-sources.xml file is slightly different:
<data-source class="oracle.jdbc.pool.OracleDataSource" name="UltraSearchDS" location="jdbc/UltraSearchPooledDS" username="wk_test" password="wk_test" url="jdbc:oracle:thin:@dlsun1517.us.oracle.com:5521:dczade4" connectionCachingEnabled="true"/>
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 Oracle9i 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
With the OracleAS release, start the Web server using the Oracle Enterprise Manager Application Server Control.
|
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/j2ee/home/oc4j.jar -config $ORACLE_HOME/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:
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 (server component), you should have created a new Ultra Search instance owner. 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.
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 root query directory is $ORACLE_HOME/ultrasearch/sample/query/.
The URL root for the query is http://hostname.domainname:port/ultrasearch/query/.
The OracleAS query (query sample pages that use the OracleAS query API and include usearch.jsp and search.jsp) is in $ORACLE_HOME/ultrasearch/sample/query/.
The URL root for the OracleAS query is in http://hostname.domainname:port/ultrasearch/query/.
(For example: access search.jsp with http://hostname.domainname:port/ultrasearch/query/search.jsp.)
The Oracle Database query (query JSP that uses the 9i query API and includes gsearch.jsp) is in $ORACLE_HOME/ultrasearch/sample/query/9i/.
The URL root for the Oracle Database query is in http://hostname.domainname:port/ultrasearch/query/9i/.
Portlet is in $ORACLE_HOME/ultrasearch/sample/query/portlet/.
The URL root for Portlet is in http://hostname.domainname:port/ultrasearch/query/portlet/.
Taglib is in $ORACLE_HOME/ultrasearch/sample/query/tag/.
The URL root for taglib is in http://hostname.domainname:port/ultrasearch/query/tag/.
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.
The Ultra Search remote crawler is part of the Ultra Search backend (server component). 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 the Oracle home. You should have been prompted by the Oracle Universal Installer to enter this directory. The Oracle home directory is referred to as $REMOTE_ORACLE_HOME.
If you choose not to install the Oracle HTTP Server during the OracleAS 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).
The only configuration needed for an Ultra Search remote crawler host is to register the host with the Ultra Search system. The registration process is done by running a SQL script on the Ultra Search remote crawler host. The SQL script connects over SQL*Plus to the OracleAS middle tier and registers the remote crawler host.
Locate the correct Oracle home.
The Ultra Search middle tier is installed under a common directory known as the Oracle home. If you have installed other Oracle products prior to the Ultra Search middle tier, 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.
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.
Start SQL*Plus.
The SQL script is located in /ultrasearch/tools/remotecrawler/scripts/common/register.sql under $REMOTE_ORACLE_HOME.
Be sure to run the correct version of SQL*Plus, because multiple versions can reside on the same host if you have previously installed some Oracle products. On UNIX platforms, make sure that the correct values for PATH, ORACLE_HOME and TNS_ADMIN variables are set. On Windows platforms, choose the correct menu item from the Start menu.
After you have identified how to run the correct SQL*Plus client, you must log on to the Ultra Search database. To do this, you might need to configure an Oracle Net service setting for the Ultra Search database.
|
See Also: Oracle9i Net Services Administrator's Guide for information on how to configure a service setting |
After SQL*Plus is running, log on to the database using the schema and password that you located in Step 2.
Invoke the registration script.
Starting up SQL*Plus as the WKSYS super-user and enter the following:
@full_path_of_registration_script
For example, if value for $REMOTE_ORACLE_HOME on a UNIX host is /home/oracle9i, then enter the following at the SQL*Plus prompt:
@/home/oracle9i/ultrasearch/tools/remotecrawler/scripts/unix/register.sql
If you are running SQL*Plus on Windows, and $REMOTE_ORACLE_HOME is in d:\Oracle\Oracle9i, then enter the following at the SQL*Plus prompt:
@d:\Oracle\Oracle9i\ultrasearch\tools\remotecrawler\scripts\winnt\register.sql
The registration script prompts you for two variables. The following is a list of the variables and their descriptions:
REMOTE_CRAWLER_HOSTNAME: The DNS host name of the remote crawler host.
ORACLE_HOME: The Oracle home located in Step 1. For example, /u01/oracle9i on a UNIX host or D:/u01/oracle9i on a Windows host. (Be careful to use forward slashes for Windows hosts.)
The registration script invokes the wk_crw.register_remote_crawler PL/SQL API. The REMOTE_CRAWLER_HOSTNAME and ORACLE_HOME variables are used to compose arguments for the wk_crw.register_remote_crawler API.
Verify and complete the remote crawler profile configuration.
Be sure to enter the correct values for both variables. To verify that the registration has completed correctly, log on to the Ultra Search administration tool. Click the Remote Crawler Profiles subtab in the Crawler tab. You should see the host name of the remote crawler host you have just registered in the remote crawler profile list. Click Edit to complete the configuration process for the remote crawler profile.
If you enter any wrong values for the register.sql script, then you must unregister the remote crawler using the unregister.sql script. Invoke the unregister script the same way as you invoke the registration script. The unregister.sql script calls the wk_crw.unregister_remote_crawler PL/SQL API. After you have successfully unregistered the remote crawler, you can rerun the register.sql script.
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.
Make sure the hosting mode is enabled. Also, make sure the subscriber is created in the OID server.
|
See Also: OracleAS Portal Configuration Guide section F.2 Enabling Hosting on an Out-of-Box Portal for instructions on how to enable the hosting mode, and section F.4 Adding Subscribers for instructions on how to add a subscriber to the SSO/OID |
For each subscriber, run the following scripts to configure Ultra Search in the OID 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 <the OID user DN> -password <password of the user ’orcladmin’> -subscriber <the DN of the subscriber>
The OID 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 OID subscriber context:
ORACLE_HOME/ultrasearch/setup/usca.sh -action remove_subscriber -user <the OID user DN> -password <password of the user ’orcladmin’> -subscriber <the DN of the subscriber>
|
 Copyright © 2002, 2003 Oracle Corporation All rights reserved |
|