Web Services Interface

The Oracle SES Web services interface enables you to create client applications easily in a variety of technologies that support Simple Object Access Protocol (SOAP), such as Java and Microsoft ASP.NET. Moreover, two Web services clients are available out-of-the-box:

A Java client enables you to develop Java programs that use the Administration API.
A WebLogic test client enables you to test individual SOAP requests to the Administration API, thus facilitating development of new client applications.

Connecting to the Web Services Endpoint

The endpoint for the Web service has the following URL:

http://host:port/search/api/admin/AdminService

The host name and port number are the same ones that you use to connect to the Administration GUI.

The endpoint page provides this information:

Service Name: {http://search.oracle.com/Admin}AdminService
Port Name: {http://search.oracle.com/Admin}Admin
Address: http://host:port/search/api/admin/AdminService
WSDL: http://host:port/search/api/admin/AdminService?wsdl
Implementation class: oracle.search.admin.api.ws.OracleSearchAdminImpl

Providing Credentials

Like the command-line interface, the Web services interface has two modes of operation:

Stateful: The administrative user name and password are provided at the beginning and retained for all subsequent operations, while the client maintains the HTTP session. Use this mode when executing a sequence of operations, and thus achieve the best performance. You can provide credentials in any operation. Your application does not have to retain the password.
Stateless: The administrative user name and password are provided for each operation. Use this mode to avoid maintaining open HTTP connections when, for example, use of the application is sporadic.

Using the Web Services Java Client

Using the Java client, you can develop your own programs for managing Oracle SES instances. The Oracle Secure Enterprise Search Java API Reference describes the classes and methods.

Java Libraries

This is the Java Web services client JAR file:

ORACLE_HOME/search/lib/search_adminapi_wsclient.jar

It requires the following JAR file. Alternatively, you can use a later version of JRockit or any JDK 6 that contains a JAX-WS 2.1 implementation:

ORACLE_BASE/jrockit_160_14_R27.6.5-32/jre/lib/rt.jar

Creating a Stateful Web Services Client

The following Java code fragment creates a stateful client:

//Initialize and return a stateful admin web service client

private static AdminPortType getStatefulWebServiceClient(
  String webServiceURL,
  String userName,
  String password) throws Exception
{
  AdminService adminService = new AdminService(
    new URL( webServiceURL ),
    new QName(
      "http://search.oracle.com/Admin",
      "AdminService"
    )
  );
 
  AdminPortType adminPort = adminService.getAdmin();
 
  // Tell client proxy to maintain HTTP session for stateful behavior
  ((BindingProvider)adminPort).getRequestContext().put(
    BindingProvider.SESSION_MAINTAIN_PROPERTY, true
  );
 
  // Create credentials argument
  Credentials credentials = new Credentials();
  credentials.setUserName( userName );
  credentials.setPassword( password );
 
  adminPort.login( credentials, "en" );
 
  return adminPort;
}

Creating a Stateless Web Services Client

This Java code fragment creates a stateless client. It does not provide credentials.

// Initialize and return a stateless admin web service client
private static AdminPortType getStatelessWebServiceClient(
  String webServiceURL) throws Exception
{
  AdminService adminService = new AdminService(
    new URL( webServiceURL ),
    new QName(
      "http://search.oracle.com/Admin",
      "AdminService"
    )
  );
  return adminService.getAdmin()
}

You can use the stateless client by providing credentials for each operation.

// Get stateless web service client
adminPort = getStatelessWebServiceClient( webServiceURL );

// Create Credentials object for operation
Credentials credentials = new Credentials();
credentials.setUserName( userName );
credentials.setPassword( password );

Creating an Administrative Object

This Java code fragment creates a Web source named example.

String webSourceURL = "http://www.example.com";

String webSourceXML = 
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>" +
"<search:config productVersion=\"11.1.2.0.0\" xmlns:search=\"http://xmlns.oracle.com/search\">" +
"  <search:sources>" +
"    <search:webSource>" +
"      <search:name>example</search:name>" +
"        <search:startingUrls>" +
"          <search:startingUrl>" +
"            <search:url>" + webSourceURL + "</search:url>" +
"          </search:startingUrl>" +
"        </search:startingUrls>" +
"      </search:webSource>" +
"  </search:sources>" +
"</search:config>";
 
adminPort.createAll(
     "source",
     webSourceXML,
     "password",
     credentials,
     null,
     null,
     "en" 
);

Using the WebLogic Test Client

The WebLogic test client provides an interface for issuing SOAP messages to the Administration API and receiving a response. When you achieve the desired result, such as the creation of a data source, you can cut-and-paste the code from the test client into the application that you are developing.

Before using the test client, you should have a general understanding of Web services, XML, and SOAP.

To open the WebLogic test client:

In a browser, enter this URL to display the WebLogic Test Client home page.

http://host:port/wls_utc/
Enter the URL for the WSDL and click Test.

http://host:port/search/api/admin/AdminService?WSDL

The endpoint page provides the WSDL for your Oracle SES instance.

When you return to the Test Client home page, the URL is displayed under Recent WSDL Files, where you can simply click the WSDL service name. The WSDL is an XML-based document that describes the Web services.

Sending a Service Request

The test client provides a field for each operation and initially displays all elements permitted by the WSDL, as shown in Figure 1-1. You may use only some elements in a SOAP message, depending on the object type and the results you want to achieve. Chapter 4, "Web Service Operations," provides full descriptions of the SOAP messages for all operations.

Figure 1-1 SOAP Message for an activate Operation

Description of "Figure 1-1 SOAP Message for an activate Operation"

To open a stateful session:

Copy the following lines of code into the clipboard:

<login xmlns="http://search.oracle.com/Admin">
  <credentials xmlns="">
    <password>password</password>
    <userName>eqsys</userName>
  </credentials>
</login>

On the WebLogic Test Client page, scroll down to the login operation and click the text box.
Paste the code into the text box (Ctrl+a, Ctrl+v), then edit the password.
Click the login button to send the login SOAP message and display the service response.
If the Request Summary displays an error message, then click Re-Invoke to correct the code and resend it. Otherwise, click Show Operations to redisplay all of the Administration API operations.

Note: You cannot resend messages that contain an input XML document. You must reenter the message with escape characters for the <, >, and " symbols. See the element descriptions in Chapter 4, "Web Service Operations."

You follow the same basic steps for any operation executed in the WebLogic Test Client.

To send other SOAP messages:

Open a stateful session in the WebLogic Test Client page, as described previously. Otherwise, enter the <credentials> element in every message.
Scroll down to the operation you want to execute and enter the XML in the text box. You can edit in place or cut-and-paste from a text editor, a program development tool, the examples in this guide, or a similar source.
Click the button with the same name as the operation to send the SOAP message and display the service response.
If the Request Summary displays an error message, then click Re-Invoke to correct the code and resend it. Otherwise, click Show Operations to redisplay all of the Administration API operations.

Understanding the Service Response

The service response page has two sections:

Request Summary: Displays any errors. Otherwise, it provides a basic summary of processing the request.
Request Detail: Displays the service request that you entered, followed by the service response. Both are XML. The response is empty for operations, such as create, that operate on a single object and do not generate output. For other operations, such as export and updateAll, the response contains additional information.

The Message Log in the left panel saves all of the service responses until you clear them.

Figure 1-2 shows the Request Summary for a successful login operation, which represents the error-free response you may receive for any operation. For a failed operation, the Request Summary displays a Fault message instead of the Returned value.

Figure 1-2 Request Summary for a Successful Operation

Description of "Figure 1-2 Request Summary for a Successful Operation"