1 Using the Administration API

This chapter explains basic concepts and use of the Administration API. It contains the following topics:

Introduction to the Administration API
Command Interface
Web Services Interface
Object Types
Object Properties
Operations

Introduction to the Administration API

The Oracle SES Administration API supports management of large-scale deployments. It provides a command-line interface and a Web services interface to the same administrative tasks performed using the Oracle SES Administration GUI.

The following are the building blocks of the Administration API:

Administrative Objects: An administrative object (or simply an object) models a feature in Oracle SES that can be managed directly through the API.

An object is either creatable or universal. You can create multiple instances of a creatable object, such as a source or a schedule. You can configure, but not create, a universal object, such as the crawler settings. The administrative objects are described in Chapter 2, "Administration Object Types."
Operations: Operations perform an action on one or more objects, such as creating, deleting, starting, or stopping them. If an operation fails, then all changes are rolled back. The command-line operations are described in Chapter 3, "searchadmin Commands," and the Web services operations are described in Chapter 4, "Web Service Operations."

Command Interface

The searchadmin command provides a command-line interface to the Administration API. You can open an interactive session, or you can issue individual commands to the operating system.

You must supply the administrator password each time you issue the searchadmin command. You can include the password in the command or wait for the prompt to enter it.

Opening an Interactive Session

To open an interactive session, enter the searchadmin command at the operating system prompt. You can connect to a single instance or multiple instances.

To connect to a single instance, use the --CONNECTION option with an HTTP connection string, like the one shown here.

$ searchadmin --CONNECTION=http://myhost:7777/search/api/admin/AdminService

After providing the administrator password, you get the SES prompt. You can start entering commands to the Oracle SES Administration API. This type of connection is called session mode.

Example 1-1 shows a brief interactive session, which ends with a quit command.

Example 1-1 Issuing Commands at the SES Prompt

$ searchadmin --CONNECTION=http://myhost:7777/search/api/admin/AdminService

Search Admin Command Line - Release 11.2.1.0.0
 
Copyright (c) 2006, 2010, Oracle and/or its affiliates. All rights reserved.

Password:
 
SES>getAPIVersion
 
11.2.1.0.0
 
SES>export index
 
<?xml version="1.0" encoding="UTF-8"?>
<search:config productVersion="11.2.1.0.0" xmlns:search="http://xmlns.oracle.com/search">
   <search:index>
      <search:indexingBatchSize>250</search:indexingBatchSize>
      <search:indexingMemorySize>275</search:indexingMemorySize>
   </search:index>
</search:config>
 
SES>quit
$

Issuing Individual Commands

You can issue commands individually at the operating system prompt. You can also use this command format to create scripts and batch files, thus simplifying routine tasks. This type of connection is called single job mode.

Example 1-2 shows two commands entered at the operating system prompt. One includes the password in the command, and the other responds to the Password prompt. In a script or batch file, you must provide a password for each command.

Example 1-2 Issuing Commands at the Operating System Prompt

$ searchadmin --CONNECTION=http://myhost:7777/search/api/admin/AdminService getAPIVersion

Search Admin Command Line - Release 11.2.1.0.0
 
Copyright (c) 2006, 2010, Oracle and/or its affiliates. All rights reserved.

Password:

11.2.1.0.0
 
$ searchadmin --CONNECTION=http://myhost:7777/search/api/admin/AdminService --PASSWORD=password export index

Search Admin Command Line - Release 11.2.1.0.0
 
Copyright (c) 2006, 2010, Oracle and/or its affiliates. All rights reserved.
 

<?xml version="1.0" encoding="UTF-8"?>
<search:config productVersion="11.2.1.0.0" xmlns:search="http://xmlns.oracle.com/search">
   <search:index>
      <search:indexingBatchSize>250</search:indexingBatchSize>
      <search:indexingMemorySize>275</search:indexingMemorySize>
   </search:index>
</search:config>
 
$

Issuing Commands to Multiple Oracle SES Instances

The searchadmin command connects to the search instance defined by the CONNECTION parameter. However, you can issue commands to multiple Oracle SES instances by supplying the connection information in a text file. Then reference the file using the --CONNECTION_LIST option. Each command is executed across all instances.

This command opens connections using a file named remotehosts.lst:

$ searchadmin --CONNECTION_LIST=remotehosts.lst

Using the Help Command

The Help command provides the basic command syntax and descriptions of administrative objects. You can enter the help command in an interactive session or as an individual command, as shown here:

$ searchadmin help

Search Admin Command Line - Release 11.2.1.0.0
 
Copyright (c) 2006, 2010, Oracle and/or its affiliates. All rights reserved.

 
Usage: searchadmin [<connectionArgs>] [<operation>] [<operationArgs>]
        .
        .
        .

Table 1-1 describes the searchadmin help commands.

Table 1-1 Help Syntax

Command	Description
`help`	Provides the `searchadmin` command syntax, and lists the administrative operations.
`help` `object_type`	Describes `object_type`.
`help` `operation`	Provides the command syntax for `operation`.
`help statusCodes`	Describes the status codes that are displayed after an operation is performed on multiple objects by `createAll`, `deleteAll`, `deleteList`, or `updateAll`.
`help duplicateMethod`	Describes the settings of the `--DUPE_METHOD` parameter in the `createAll` command.
`help updateMethod`	Describes the settings of the `--UPDATE_METHOD` parameter in the `update` and `updateAll` commands.
`help notFoundMethod`	Describes the settings of the `--NOT_FOUND_METHOD` parameter in the `updateAll` command.

Command Syntax

The following is a summary of the searchadmin command syntax.

searchadmin [--USERNAME=admin] [--PASSWORD=password] [{--CONNECTION=connection] | --CONNECTION_LIST=filename}] [operation]

searchadmin [-u admin] [-p password] [{-c connection | -m filename}] [operation]

admin

Administrator user name, which is searchsys by default.

password

Password for the administrator. You are prompted for the password if you omit it from the command. If you are connecting to multiple instances, the password is used for authentication on all of them; omit this argument if they do not use the same password.

connection

Connection to an Oracle SES instance using HTTP:

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

The port number is the same as connecting to the Administration GUI.

filename

The name of the connection file. The path can be absolute or relative to the current directory.

operation

An administrative operation, as described in Chapter 3, "searchadmin Commands." Omit this argument to open an interactive session. Like the searchadmin command, the operations have a short form and a long form for many arguments.

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:

JROCKIT_HOME/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.2.1.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" 
);

Object Types

The Administration API enables you to perform a variety of operations on the administrative objects. These objects fall into two basic categories: universal and creatable.

Universal Objects

Oracle SES has one instance of each universal object out of the box. You can change the default settings, but you cannot create a new instance or delete the existing one. In the Administration GUI, you can edit the settings of universal objects on the Global Settings pages.

Table 1-2 describes the universal object types.

Table 1-2 Universal Objects

Object Type	Description
`crawlerSettings`	Global crawler configuration
`globalBoundaryRules`	Global crawler boundary rules
`globalDocumentTypes`	Global crawler document types
`index`	Indexing parameters
`indexOptimizer`	Index optimization
`partitionConfig`	Partition configuration
`queryConfig`	Query configuration
`relevanceRanking`	Attribute relevance ranking

Creatable Types

Oracle SES may have multiple instances of a creatable type out of the box, or it may have none. You can create new instances and, for most types, modify existing ones. In the Administration GUI, you can create and edit most of these objects on the Home and Search pages.

An object key uniquely identifies a particular instance of a creatable type. The key can be a single value, such as the name of a source, or a composite value, such as the jar file name and class of an identity plug-in. If an object key contains spaces, then all references must be enclosed in quotes in the command-line interface:

--NAME=this_DataSource
--NAME="This Data Source"

Table 1-3 describes the creatable objects.

Table 1-3 Creatable Object Types

Object Type	Description
`altWord`	Alternate words
`docServiceInstance`	Document service instance
`docServiceManager`^Foot 1	Document service manager
`docServicePipeline`	Document service pipeline
`facetTree`	Facet tree
`identityPlugin`^Footref 1	Identity plug-ins
`proxyLogin`	Proxy log-ins
`schedule`	Schedules
`searchAttr`	Search attributes
`source`	Sources
`sourceGroup`	Source groups
`sourceType`^Footref 1	Source types
`suggLink`	Suggested links
`thesaurus`	Thesaurus

^Footnote 1These objects cannot be created or modified in Oracle Fusion Applications.

Object Properties

All object types have properties that configure the object to operate in a particular way. An XML document describes these properties. When you create or modify an object, you submit an XML document to Oracle SES that describes the object and sets the values of its properties. When you query Oracle SES for a description of an object, it returns the information as an XML document.

XML Documents

Although you can develop XML descriptions of administration objects from the start, an easier method is to let Oracle SES do the work for you. For universal objects, you can export the description to a file for editing. For creatable objects, you can use the Administration GUI to develop an object and then export the description to a file. You can then edit the file or copy it to create similar objects. This method is particularly useful when creating or updating complex object types, such as sources.

Sample XML Document of an Administration Object

The following is a very simple example of an XML document generated by Oracle SES. It describes the universal index object:

<?xml version="1.0" encoding="UTF-8"?>
<search:config productVersion="11.2.1.0.0" xmlns:search="http://xmlns.oracle.com/search">
   <search:index>
      <search:indexingBatchSize>250</search:indexingBatchSize>
      <search:indexingMemorySize>275</search:indexingMemorySize>
   </search:index>
</search:config>

<?xml version="1.0" encoding="UTF-8"?>: Identifies the file as an XML document. The encoding of exported XML is set to UTF-8, but imported documents can have other encoding.
<search:config>: Contains all Oracle SES object configuration elements. This is the root element of the XML document.
<search:index>: Contains the configuration settings for the universal index element. You can describe administration objects in individual XML files or all objects in one XML file.

Chapter 2, "Administration Object Types," discusses the XML description of each object type.

Editing XML Files

The XML complies with the standard conventions for XML documents. You should have a working knowledge of XML before using the administration APIs.

XML is a text-based markup language, so you can use any text editor to create and edit XML files. However, an ordinary text editor cannot detect when the document is correctly formed and, more importantly, when it contains syntax errors. For that, you should use an XML editor. You can choose from professional and freeware versions that are available for download on the Web.

An XML editor can also check an XML document against the XML Schema Definition (XSD). Oracle SES has two files for the XSD:

Config.xsd: Contains the object definitions.
State.xsd: Contains the schema for the getState, getStateList, and getAllStates operations.

Both files are in ORACLE_HOME/search/xsd/admin/api.

State Properties

Some object types have state properties that provide information about the current state of the object. For example, a cluster tree has a status property that reports whether it is enabled or disabled. Both universal and creatable object types can have state properties. Chapter 2, "Administration Object Types," lists the state properties for each object type.

Oracle SES returns the current state of an object in the form of an XML document. See "XML Description of State Properties".

Table 1-4 Administrative Objects With State Properties

Object Type	State Properties
`identityPlugin`	`status`
`index`	`estimatedFragmentation`
`indexOptimizer`	`endTime`, `startTime`, `status`
`partitionConfig`	`status`
`schedule`	`lastCrawled`, `logFilePath`, `nextCrawl`, `scheduleError`, `status`

Operations

You execute various operations to manage the administration objects. Chapter 3, "searchadmin Commands," provides the syntax of these operations and command examples. The same operations are available as XML documents in the Web services interface, described in Chapter 4, "Web Service Operations."

Command Syntax

The commands have this general syntax for universal object types:

operation object_type [parameters] [options]

The syntax for creatable types includes the object key for operations performed on a single object:

operation object_type [object_key] [parameters] [options]

Note: The clustering object used in the following examples is disabled in Oracle Fusion Applications.

For example, the following command activates clustering. The clustering object is a universal object type, and the command consists only of the required operation and object_type:

activate clustering

The next command updates the clustering configuration. This command requires the path to the input XML file with the new configuration settings and an update method:

update clustering --INPUT_FILE=clustering.xml --UPDATE_METHOD=overwrite

Most parameters and some common options have a shortcut notation. The previous update command can also be expressed with this syntax:

update clustering -i clustering.xml -a overwrite

Sources are creatable, so the command to change the configuration of a source requires the object key. For sources, the object key is the name. The following command also includes the INPUT_FILE parameter.

update source --NAME="Doc Library" --UPDATE_METHOD=overwrite --INPUT_FILE=sources.xml

The shortcut notation looks like this:

update source -n "Doc Library" -a overwrite -i sources.xml

Using the Message Logs

The message logs can help you debug problems executing an operation. All messages are written to the WebLogic Server logs, which you can view in the WebLogic console.

Managing Universal Objects

Use these operations to manage universal administration objects:

Table 1-5 Operations on Universal Objects

Operation	Description
`export`	Returns the XML description of an object.
`update`	Sets the parameters of an object from an XML file.

Managing Creatable Objects

Use these operations to manage creatable administration objects:

Table 1-6 Operations on Creatable Objects

Operation	Description
`create`	Creates an object from an XML file.
`createAll`	Creates all the objects of a particular type from an XML file.
`delete`	Deletes a single object.
`deleteAll`	Deletes all objects of a particular type.
`deleteList`	Deletes a list of objects of a particular type.
`export`	Returns the XML description of an object.
`exportAll`	Returns the XML descriptions of all objects of a particular type.
`exportList`	Returns the XML descriptions of a list of objects of a particular type.
`update`	Sets the parameters of an object from an XML file.
`updateAll`	Sets the parameters of all objects of a particular type from an XML file.

Managing Object State

Use these operations to manage both universal and creatable administration objects with state properties.

Table 1-7 Operations on Objects With State Properties

Operation	Description
`activate`	Enables an object. Objects that can be enabled have a `status` state property.
`deactivate`	Disables an object. Objects that can be disabled have a `status` state property.
`getAllStates`	Returns the current state of all objects of a particular type as an XML document.
`getState`	Returns the state of an object as an XML document.
`getStateList`	Returns the state of a list of objects of a particular type as an XML document.
`start`	Initiates the starting process of an object.
`stop`	Initiates the stopping process of an object.

Status Codes for Bulk Operations

Operations that involve multiple objects, such as createAll, deleteAll and deleteList, return status codes for each processed object, as described in Table 1-8.

Table 1-8 Status Codes

Status Code	Description
`CREATE_NOT_SUPPORTED`	The object cannot be created.
`CREATE_SUCCEEDED`	The object was successfully created.
`DELETE_NOT_SUPPORTED`	The object cannot be deleted.
`DELETE_SUCCEEDED`	The object was successfully deleted.
`DUPLICATE_IGNORED`	The object already existed. The operation ignored the pre-existing object.
`DUPLICATE_OVERWRITTEN`	The object already existed. The operation overwrote the pre-existing object.
`INVALID_STATE_IGNORED`	The object was ignored because it was in an invalid state.
`NOT_FOUND_CREATED`	The object did not exist. The operation created the object.
`NOT_FOUND_IGNORED`	The object did not exist. The operation ignored the object.
`UPDATE_NOT_SUPPORTED`	The object cannot be updated.
`UPDATE_SUCCEEDED`	The object was successfully updated.