Sample Web Services Query Application Readme

This page describes how to deploy and use the sample Web Services query application for Oracle Secure Enterprise Search (SES). The application is a simple query tool that demonstrates the main features available through the Oracle SES Web Services API. You can use this application as a reference when building your own search application using the API.

Compatibility

The sample application is compatible with Oracle Secure Enterprise Search release 10.1.8.0 or 10.1.8.1. It should work with later versions as well.

Installing the Sample Web Services Query Application

The sample application can be deployed in any OC4J container using the sample.ear file included in this distribution. For example, in OC4J 10g Release 3, deploy it by invoking the following command in a command shell in the $ORACLE_HOME/j2ee/home directory:

java -jar admin_client.jar deployer:oc4j:opmn:<oc4j_host>:<rmi_request_port>/<oc4j_instance> oc4jadmin <oc4jpwd> -deploy -file sample.ear -deploymentName ses_query -bindAllWebApps

where:

oc4j_host is the server host name for the OC4J instance on which the sample application is to be deployed
rmi_request_port is specified in $ORACLE_HOME/opmn/conf/opmn.xml as the request attribute in the port element
oc4j_instance is the name of the OC4J instance into which the application is to be deployed
oc4jpwd is the password for the OC4J administrator

Note: This is only one of several methods that can be used to deploy the application. See the OC4J documentation for more information.

The deployment name used here is ses_query, but that could be anything you choose. After successful deployment, all files associated with the deployment (including the JSP source files) are in the $ORACLE_HOME/j2ee/<oc4j_instance>/applications/ses_query directory on the OC4J host.

Deploying into an existing SES installation

Secure Enterprise Search uses oc4j as its own lightweight web server. It therefore makes sense for many users to install to the existing oc4j installation.

Before doing this you must determine the RMI port being used. This is NOT the same as the standard SES port. The RMI port for SES is defined in <installation_dir>/oc4j/j2ee/OC4J_SEARCH/config/rmi.xml. The default is port 5740.

The ear file can be deployed by the following command, assuming that <installation_dir>/jdk/bin is in your PATH variable, and that your current working directory is the location of the ear file. Replace 5740 with your RMI port if different, and replace oc4jpassword with the SES admin password chosen at installation.

java -jar <installation_dir>/oc4j/j2ee/home/admin_client.jar deployer:oc4j:localhost:5740 oc4jadmin oc4jpassword -deploy -file sample.ear -deploymentName ses_query -bindAllWebApps http-web-site

Configuring the Sample Web Services Query Application

After deployment, the sample application must be configured with the Oracle SES server Web Services endpoint.

Configuring the Web Services Endpoint

To configure the Web Services endpoint, the web.xml file must be populated with the Oracle SES host name and port number.

Locate the web.xml file under the deployment directory of the sample application. (In the example, it would be located in the $ORACLE_HOME/j2ee/<oc4j_instance>/applications/ses_query/sample/WEB-INF directory.)
In web.xml there are two context-param elements with param-name child elements whose contents are searchEndpointHost and searchEndpointPort, respectively. Add the Oracle SES host name and port number as the content of the corresponding param-value elements.

This step will need to be repeated if the application is re-deployed (for example after editing some of the files). You can avoid having to change the deployed file each time by unpacking the ear archive, editing the web.xml file inside the ear and repacking it.

jar xvf sample.ear jar xvf sample.war

Now edit WEB-INF/web.xml, and repack the archive with:

jar cvf sample.war WEB-INF *.jsp *.jspf img css about.html jar cvf sample.ear META-INF sample.war

Restarting OC4J

After installing the JSTL and configuring the Web Services endpoint, the OC4J instance on which the application was deployed must be restarted. If you have deployed to an existing SES installation's OC4J, then you can do this with the command

searchctl restart

External Dependencies

The sample application depends on the http_client.jar library. This library is provided with OC4J, and the sample application is configured with the path to this library. Depending on where the sample application is deployed, however, this path may need to be modified. To modify the path for http_client.jar, edit the META-INF/orion-application.xml file in the directory where the sample application was deployed, and update the library-path element with the correct path to http-client.jar. Note: this step should not be necessary if deploying to an existing SES OC4J installation.

Accessing the Application

After the sample application has been deployed and configured, the sample query application can be accessed at the URL http://<oc4j_host>:<oc4j_port>/sample/search. Here oc4j_host is the OC4J host as described above, and oc4j_port is the port number for the OC4J instance on which the sample application was deployed.

When the search page has loaded, you should see a query box and Search button. Run a search by entering text in the query box and clicking Search. The search results will appear below the search box. Search results can be sorted by relevance, or by recency within relevance, by clicking on the provided links. The sorting links are visible only if the query returns at least one result.

In addition, the sample application provides the following features:

Links to restrict search to source groups
Status bar indicating estimated hit count for the query
RSS feed for the query (labeled XML)
Suggested links for the query term
Alternate keywords for the query term
Link to the out-of-box search application provided with Oracle SES (Out-of-Box UI)
About link pointing to a generic information page

After the sample query application has been deployed, the application's JSP code (in the $ORACLE_HOME/j2ee/<oc4j_instance>/applications/ses_query/sample directory) can be browsed for further details. Start with the search.jsp file. The code is liberally commented and should be self-explanatory.

Troubleshooting and Known Issues

Application Log File

If the web services application fails, you will probably just see a generic error, referring you to the application log file for more details. This log file will be in in the application deployments tree. For example in the standard SES OC4J installation as used above, the file will be: <install_dir>oc4j/j2ee/OC4J_SEARCH/application-deployments/ses_query/application.log

Proxy Settings

If your OC4J has a web proxy configured, you may encounter problems. This is especially likely if you are using the installed SES OC4J. You may need to delete your proxy from the Global Settings admin page before you can successfully use the Web Services Sample. Obviously this will cause any crawls to fail which rely on the proxy. This problem is currently being investigated.

Internationalization Issues

There are some known issues associated with multibyte characters caused by a bug in OC4J. These issues have been resolved in OC4J release 10.1.3, but they could appear in earlier releases of OC4J. Specifically, if the sample application is deployed in an earlier release of OC4J:

Query strings containing multibyte characters might not be encoded correctly.
Multibyte characters in the response page might be rendered incorrectly.
Multibyte characters in cached documents might be rendered incorrectly.