3 Using Oracle Ultra Search with Oracle Application Server

Oracle Ultra Search is included with Oracle Database and Oracle Application Server. This chapter contains information on using Oracle Ultra Search with Oracle Application Server.

Oracle Ultra Search enables Oracle Application Server Portal (OracleAS Portal) users to search multiple repositories, such as Web pages, files on disk, and public pages on other OracleAS Portal instances. It provides a portlet that can be placed on user portal pages. This portlet can be used to issue a search query and to obtain a list of results.

Oracle Ultra Search resides in the Oracle Application Server Metadata Repository (OracleAS Metadata Repository), a centralized Oracle database on the Oracle Application Server backend. The OracleAS Metadata Repository contains all the Oracle Ultra Search database objects, including the actual text index information created during crawling. The Oracle Ultra Search backend is automatically installed on the computer that hosts the OracleAS Metadata Repository.

This chapter contains the following topics:

Oracle Ultra Search Backend with Oracle Application Server
Oracle Ultra Search Middle Tier with Oracle Application Server
Configuring Oracle Ultra Search in a Hosted Environment (Optional)

Note:

This chapter contains information specific to using Oracle Ultra Search with Oracle Application Server. For information about all Oracle Ultra Search installations, and for information specific to Oracle Ultra Search with Oracle Database, see Chapter 4, "Installing Oracle Ultra Search".

Oracle Ultra Search Backend with Oracle Application Server

Oracle Ultra Search backend is installed as part of an Oracle Database Server installation. Oracle Application Server middle tier uses the Oracle Ultra Search backend. The Oracle Application Server Metadata Repository resides on the Oracle Database.

The Oracle Ultra Search release depends on the Oracle Database Server release. If the OracleAS Metadata Repository resides on Oracle Database 10g release 1 (10.1), then you have Oracle Ultra Search 10g release 1 (10.1). If the OracleAS Metadata Repository resides on Oracle9i Database Server release 2 (9.2), then you have the Oracle Ultra Search release that is shipped with the database.

If Oracle Ultra Search was not installed during the database installation, then an error will occur when creating OracleAS Metadata Repository on the database. Install Oracle Ultra Search using the Oracle Universal Installer.

Note:

The release number of Oracle Ultra Search backend version is the same as the Oracle Database version. Suppose you have Oracle Application Server release 10.1.2 and Oracle Database release 9.2. Then the Oracle Ultra Search release number will be release 9.2. There is no Oracle Internet Directory registration in Oracle Database 9.2. As a result, the orcladmin user cannot login to manage Oracle Ultra Search.

See Also:

Oracle Database Server documentation for information about installing Oracle Ultra Search at

http://www.oracle.com/technology/documentation/

Changing the Character Set of Oracle Metadata Repository

If the database character set is changed after installation, you must reconfigure the Oracle Ultra Search backend to adapt to the new character set.

To configure the middle-tier and infrastructure to work with OracleAS Metadata Repository after its character set has been changed, do the following:

Modify the character set of all Database Access Descriptors (DADs) accessing the metadata repository to the new database character set.
1. Using the Application Server Control Console, navigate to the middle-tier instance home page.
2. In the System Components section, click HTTP_Server.
3. On the HTTP_Server home page, click Administration.
4. On the HTTP_Server Administration page, select PL/SQL Properties. This opens the mod_plsql Services page.
5. Scroll to the DADs section and click the name of the DAD that you want to configure. This opens the Edit DAD page.
6. In the NLS Language field, type in a NLS_LANG value whose character set is the same as the new character set for OracleAS Metadata Repository.
7. Click OK.
8. Repeat steps e to g for all DADs accessing OracleAS Metadata Repository.
Reconfigure the Oracle Ultra Search index as follows:
1. Connect to OracleAS Metadata Repository as WKSYS and invoke the following SQL script to reconfigure the default cache character set and index preference:
```
ORACLE_HOME/ultrasearch/admin/wk0prefcheck.sql
```
2. Connect to OracleAS Metadata Repository as the default user (WKTEST) and invoke the following SQL script:
```
ORACLE_HOME/ultrasearch/admin/wk0idxcheck.sql
```
  The script requests you to enter the instance name (WK_INST). Enter "y" when prompted to go ahead with the change.This script reconfigures the instance (in this case, the default instance). It also truncates the Oracle Text index used by Oracle Ultra Search and you must force a recrawl to rebuild the index, after Recrawl Policy has been changed to Process All Documents.
3. Repeat step b for all Oracle Ultra Search instances that were created before you changed the database character set. Invoke the script as the instance owner, and then force a recrawl of all data sources, if necessary.

Oracle Ultra Search Middle Tier with Oracle Application Server

Oracle Ultra Search middle tier is part of the Oracle Application Server installation. Select the OracleAS Portal and Wireless option from the Oracle Universal Installer menu to install and configure the Oracle Ultra Search middle tier during the Oracle Application Server installation.

See Also:

Oracle Application Server Administrator's Guide for information about changing the OracleAS Infrastructure Services, such as specifying a different Oracle Internet Directory or OracleAS Metadata Repository used by an Oracle Ultra Search middle tier.

Installing the Middle Tier with Oracle Application Server

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

Select Oracle Application Server, and click Next.
Select Portal and Wireless, and click Next.
On the Configuration Options screen, ensure OracleAS Portal is selected. This option enables the OracleAS Portal Configuration Assistant (OPCA) to configure Oracle HTTP Server and OC4J with Oracle Ultra Search.

If you deselect this option, then you can use Oracle Enterprise Manager 10g to configure OracleAS Portal and OracleAS Wireless.

Continue with the installation until Oracle Application Server is successfully installed.
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 data-sources.xml.
Restart OC4J_Portal instance using the Oracle Process Manager and Notification Server.

See Also:

"Enable the Oracle Ultra Search Query Applications" for information on editing data-sources.xml

If the backend is Oracle Database 9i while you install Oracle Ultra Search middle tier from Oracle Application Server, and then later on change the backend to Oracle Database 10g or higher, you will not be able to log in to Oracle Ultra Search. To be able to log in again, you must run the following script:

$ORACLE_HOME/jdk/bin/java -jar $ORACLE_HOME/ultrasearch/lib/usca.jar
@ oh=$ORACLE_HOME action=register_backend install_type=ias oid=<OID_HOST_NAME>
@ oid_port=<OID_PORT> oid_user_dn="cn=orcladmin" oid_passwd=<orcladmin_password>

This script must be executed on the Oracle Ultra Search middle tier.

Configuring Oracle Ultra Search in a Hosted Environment (Optional)

Oracle Ultra Search by default is non-hosted during the installation.

In a hosted environment, one enterprise, such as an application service provider, makes Oracle Ultra Search available to other enterprises and stores information for them. The enterprise performing the hosting is called the default subscriber, and the enterprises that are hosted are called subscribers. To change it to a hosted environment, perform the following steps:

Make sure the hosting mode is enabled.
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 about enabling the hosting mode, and section "Adding Subscribers" for instructions about adding a subscriber to Oracle Application Server Single Sign-On and Oracle Internet Directory
Make sure you have execute permission on the usca.sh script, and setup the ORACLE_HOME environment variable. The Oracle Internet Directory user must have the iASAdmins privilege.
For each subscriber, run the usca script to configure Oracle Ultra Search in the Oracle Internet Directory subscriber context.
- For UNIX:
```
ORACLE_HOME/ultrasearch/setup/usca.sh -action add_subscriber \
-user OID_user_DN -password orcladmin_password -subscriber subscriber_DN
```
- For Windows:
```
ORACLE_HOME\ultrasearch\setup\usca.bat -action add_subscriber \
-user OID_user_DN -password orcladmin_password -subscriber subscriber_DN
```
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.
The following example illustrates how to configure 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'
```

Note:

To drop a subscriber, run the usca script to remove Oracle Ultra Search entries from the Oracle Internet Directory subscriber context. For example, the following is an example of the UNIX command:

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

Oracle Ultra Search Administrator Privilege Model in the Hosted Environment

The default subscriber and its search base are specified in the attributes of the Oracle Internet Directory cn=Common,cn=Products,cn=OracleContext entry:

orclDefaultSubscriber
orclSubscriberSearchBase

In a non-hosted environment there are no subscribers and the enterprise installing Oracle Ultra Search is the default subscriber. All Oracle Ultra Search administration groups (super-user and instance administrator groups) are created under Default Subscriber Oracle Context, such as cn=OracleContext, dc=us,dc=oracle,dc=com in the Oracle Internet Directory Information Tree.

Figure 3-1 shows an example of the Oracle Internet Directory topology of a hosted environment. There are two subscribers (A and B) and the default subscriber. Each subscriber has its own super-user privilege group associated with it. There are four Oracle Ultra Search instances created in the Oracle Ultra Search backend Install 1. Instance 1 is associated with the default subscriber. Instance 2 and Instance 3 are associated with Subscriber A. Instance 4 is associated with Subscriber B. Each Oracle Ultra Search instance has its instance administration group associated with it.

Figure 3-1 Oracle Internet Directory Topology of a Hosted Environment

Description of "Figure 3-1 Oracle Internet Directory Topology of a Hosted Environment"

Administration Privilege Model

This section describes the administrator privilege model of Oracle Ultra Search administration tool in the hosted environment. The model applies to both the Oracle Application Server Single Sign-On login mode and the non-single sign-on login mode.

In single sign-on mode, only single sign-on users can log in to the administration tool. Single sign-on users have different privileges depending on the user belonging to the default subscriber or another subscriber. If the single sign-on user belongs to the default subscriber, then the following apply:

If the single sign-on user has the super-user privileges, then the user can administer all Oracle Ultra Search instances across the default subscriber and any other subscribers (for example, Instances 1, 2, 3, and 4).
If the single sign-on user have the administrator privilege on a particular Oracle Ultra Search instance (for example, Instance 1) within the default subscriber, then the user can administer the instance (Instance 1) that is associated with the default subscriber.

If the single sign-on user belongs to a particular subscriber, then the following apply:

If the single sign-on user has the super-user privilege, then the user can only administer only Oracle Ultra Search instances within the subscriber. For example, if the user from Subscriber A has the super-user privilege, then the user can only administer Instance 2 and 3.
If the single sign-on user has the admin privilege on a particular Oracle Ultra Search instance (for example, Instance 2), then the user can administer the instance (Instance 2) that is associated with the subscriber (Subscriber A).

In non-single sign-on mode, only database users can log in to the administration tool.

If the login database user has the super-user privilege, then the user can administer all Oracle Ultra Search instances across the default subscriber and any other subscribers.
If the login database user only has the administrator privileges on a particular Oracle Ultra Search instance, then the user can administer the instance regardless of whether the instance is associated with the default subscriber or any other subscribers.

Privileges to Create and Drop an Oracle Ultra Search Instance

To create or drop an Oracle Ultra Search instance, the user must have the super-user privilege.

In single sign-on mode, the following apply:

If the login single sign-on user belongs to the default subscriber, then the user can create or drop an instance and associate the instance with any subscriber, including the default subscriber.
If the login single sign-on user belongs to particular subscriber, then an instance created by the user is associated with the subscriber. Because the user might not have access to create the instance schema in the database, the user must inform the hosting company (default subscriber) to create the database schema for the instance.

In non-single sign-on mode, the database user can create or drop an instance and associate the instance with any subscriber, including the default subscriber.

Privileges to Grant or Revoke a Super-user

To grant or revoke a super-user, log in to the administration tool as a super-user.

In single sign-on mode, the following apply:

If the login single sign-on user belongs to the default subscriber, then the user can do the following:
- Grant or revoke the super-user privilege to single sign-on users in the default subscriber.
- Grant or revoke the super-user privilege to single sign-on users in another subscriber.
If the login single sign-on user belongs to a particular subscriber, then the user can grant or revoke the super-user privilege to users with the same subscriber.

In non-single sign-on mode, only super-users can grant or revoke the super-user privilege to and from other database users.

Privileges to Grant or Revoke an Instance Administrator

To grant or revoke an instance administrator, log in to the admin tool as a super-user or an instance administrator.

In single sign-on mode, the following apply:

The login single sign-on user can grant or revoke only the instance admin privilege to single sign-on users within the same subscriber. For example, the user can grant the admin privilege on Instance 2 or Instance 3 to a single sign-on user in Subscriber A.
The login single sign-on user cannot grant or revoke the instance admin privilege to single sign-on users within a different subscriber. For example, the user cannot grant the admin privilege on Instance 2 or Instance 3 to a single sign-on user in Subscriber B.

In non-single sign-on mode, only super-users or instance administrators can grant or revoke the instance admin privilege to and from other database users.