This chapter explains basic concepts and use of the Administration API. It contains the following topics:
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."
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.
To open an interactive session, enter the ses_home/bin/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://ses_host:ses_port/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.2.2.0 Copyright (c) 2006, 2010, Oracle and/or its affiliates. All rights reserved. Password: SES>getAPIVersion 11.2.2.2.0 SES>export index <?xml version="1.0" encoding="UTF-8"?> <search:config productVersion="11.2.2.2.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 $
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, include the password in 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.2.2.0 Copyright (c) 2006, 2010, Oracle and/or its affiliates. All rights reserved. Password: 11.2.2.2.0 $ searchadmin --CONNECTION=http://myhost:7777/search/api/admin/AdminService --PASSWORD=password export index Search Admin Command Line - Release 11.2.2.2.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.2.2.0" xmlns:search="http://xmlns.oracle.com/search"> <search:index> <search:indexingBatchSize>250</search:indexingBatchSize> <search:indexingMemorySize>275</search:indexingMemorySize> </search:index> </search:config> $
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.
For example, create a file named remotehosts.lst and enter the information related to multiple instances in it as shown below:
--USERNAME=searchsys --CONNECTION=http://ses_host_1:ses_port_1/search/api/admin/AdminService --USERNAME=searchsys --CONNECTION=http://ses_host_2:ses_port_2/search/api/admin/AdminService
This command opens connections using the remotehosts.lst file:
$ searchadmin --CONNECTION_LIST=remotehosts.lst
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.2.2.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.
| Command | Description |
|---|---|
|
|
Provides the |
|
|
Describes |
|
|
Provides the command syntax for |
|
|
Describes the status codes that are displayed after an operation is performed on multiple objects by |
|
|
Describes the settings of the |
|
|
Describes the settings of the |
|
|
Describes the settings of the |
The following is a summary of the searchadmin command syntax.
searchadmin [--USERNAME=admin] [--PASSWORD=password] [{--CONNECTION=connection] | --CONNECTION_LIST=filename}] [operation]
or
searchadmin [-u admin] [-p password] [{-c connection | -m filename}] [operation]
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 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.
The name of the connection file. The path can be absolute or relative to the current directory.
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.
Note:
To enter special characters as part of asearchadmin command, you may have to enclose the value in quotes, or prefix the character with backslashes as escape characters, or use both.
If the command argument value contains spaces, then enclose it in double quotes. For example: --NAME="Special Collection".
To use the percent (%) and underscore (_) wildcard characters as literals for key patterns in operations such as createAll and deleteAll, prefix the wildcard character with two backslashes (\\) on a Linux or a UNIX system and prefix it with a single backslash (\) on a Windows system.
For example, on a Linux or a UNIX system, escape the wildcard character _ in the object named web_source using the syntax --NAME=web\\_source. The same functionality can be achieved on a Windows system using the syntax --NAME=web\_source.
In single job mode, also enclose the values containing these characters in double quotes. For example, on a Linux or a UNIX system, use the syntax --NAME="web\\_source" and on a Windows system, use the syntax --NAME="web\_source".
When using the short form for arguments, escape literal values starting with a dash with two backslashes in single job mode, such as -n \\-mysource. In session mode, enclose the values in quotes or escape the dash with one backslash. For example, -n \-mysource or -n "-mysource". Alternatively, use the long form for arguments, such as --NAME=-mysource. On Windows system, always use the long form for arguments in single job mode as well as in session mode.
See "Command Interface" for a discussion of session mode and single job mode.
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.
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:
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 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.
See Also:
Appendix A, "Java Example"You need to include the following JAR files in the CLASSPATH for using the Oracle SES Web services Java client:
mw_home/oracle_common/modules/oracle.webservices_11.1.1/oracle.webservices.standalone.client.jar
mw_home/search/lib/search_adminapi_wsclient.jar
For the IBM-AIX platform, you also require the JAR file:
mw_home/oracle_common/modules/glassfish.jaxb.xjc.jar
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;
}
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 );
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.2.2.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"
);
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.
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.
| Object Type | Description |
|---|---|
|
Auto suggestions configuration |
|
|
Group specific classification mappings for suggestion keywords |
|
|
Clustering configuration |
|
|
Crawler configuration |
|
|
Global crawler boundary rules |
|
|
Global crawler document types |
|
|
Indexing parameters |
|
|
Index optimization |
|
|
Language specific lexers |
|
|
Partition configuration |
|
|
HTTP proxy server configuration |
|
|
Query configuration |
|
|
Query UI configuration |
|
|
Facets configuration |
|
|
Source group configuration |
|
|
Attribute relevance ranking |
|
|
Search result list configuration |
|
|
Suggested content configuration |
|
|
Tagging configuration |
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 |
|---|---|
|
Alternate words |
|
|
Authorizations for functinality, such as, tagging, to various Oracle SES users |
|
|
Relevancy boosting URLs |
|
|
Classification configuration for categorizing suggestion keywords |
|
|
Cluster trees |
|
|
Document service instance |
|
|
Document service manager |
|
|
Document service pipeline |
|
|
Facet trees |
|
|
Identity plug-ins |
|
|
Index profiles |
|
|
Lexers |
|
|
Proxy log-ins |
|
|
Schedules |
|
|
Search attributes |
|
|
Single sign-on configuration |
|
|
Skin bundle |
|
|
Sources |
|
|
Source groups |
|
|
Source types |
|
|
Storage areas |
|
|
Suggested content provider |
|
|
Suggestions |
|
|
Suggested links |
|
|
Tags for bulk upload |
|
|
Thesaurus |
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.
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.
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.2.2.0" xmlns:search="http://xmlns.oracle.com/search">
<search:index>
<search:indexingBatchSize>250</search:indexingBatchSize>
<search:indexingMemorySize>275</search:indexingMemorySize>
</search:index>
</search:config>
Identifies the file as an XML document. The encoding of exported XML is set to UTF-8, but imported documents can have other encoding.
Contains all Oracle SES object configuration elements. This is the root element of the XML document. It contains the productVersion attribute that denotes the Oracle SES product version.
Note:
TheproductVersion attribute is optional, but it is strongly recommended to specify it, because different versions of Oracle SES may have behavioral differences in their Admin API. When the productVersion is not specified, Oracle SES assumes it to be the latest available version, that is, 11.2.2.2.
In case the productVersion is specified as 11.1.2.2 while importing an XML into an Oracle SES 11.2.2.2 instance, then Oracle SES will use the 11.1.2.2 version behavior.
For example, the earlier Oracle SES release 11.1.2.2 did not support master encryption key, but the current Oracle SES release 11.2.2.2 supports it. Thus, to provide backward compatibility, Oracle SES 11.2.2.2 handles the 11.1.2.2 encryption format correctly whenever the productVersion attribute value is specified as 11.1.2.2.0 in the input XML.
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.
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:
Both files are in the ses_home/search/xsd/admin/api directory.
Note:
Oracle SES automatically encrypts any secure information stored in it, such as password, when it is exported to a text file. For example:
<search:parameter name="Password"> <search:value encrypted="true">dc33fb22cfaf96fd592b14754f58818911acaa08e982966f</search:value> <search:description>Service Operation User password</search:description> </search:parameter>
When using a configuration file stored on a disk, any security information in it, such as password, should be typed in plain text with the encrypted property value set to false. For example:
<search:value encrypted="false">not4U2Know</search:value>
A configuration file containing unencrypted security information should be protected, or else it should be removed immediately after use.
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 |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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."
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]
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
The message logs can help you debug problems executing an operation.
The searchadmin command stores log messages in the directory:
wls_domain_home/ses_domain_name/servers/search_server1/logs
The WebLogic server for Web services stores log messages in the directory:
wls_domain_home/ses_domain_name/servers/AdminServer/logs
Oracle SES 11.2.2.2 uses ODL as the default logger. The earlier Oracle SES release (11.1.2.2) used log4j as the default logger. Oracle SES 11.2.2.2 stores logger configurations for ODL logs in the script file ses_home/bin/clexecutor.sh. You can update this file to configure the following parameters for the logger:
LOG_FORMAT: The log format to use. The available values are: ODL-XML, ODL10-XML, and ODL-Text. Default is ODL-Text.
LOG_MAX_FILE_SIZE: The maximum size in bytes for each log file. When a log file reaches this size, it is archived, and a new log file is created. Default is 104857600 bytes.
LOG_ROTATION_FREQUENCY: The frequency, in minutes, for archiving the old log file and creating a new one. This value must be either a number (that is, minutes), or one of the following values (case-insensitive): hourly, daily, or weekly. Default is daily.
Note:
If a value is specified for theLOG_MAX_FILE_SIZE parameter, then Oracle SES ignores the value specified for the LOG_ROTATION_FREQUENCY parameter.LOG_LEVEL: Sets the log level in the form of a number. ODL logs only those records with a level equal to or higher than the specified log level value. The meaningful name for each log level is as follows:
| Log Level | Name |
|---|---|
| 0 | TRACE |
| 2 | DEBUG |
| 4 | INFO (NOTIFICATION) |
| 6 | WARN |
| 8 | ERROR (SEVERE) |
| 10 | FATAL (INCIDENT_ERROR) |
LOG_AUTOFLUSH_LEVEL: Sets the log level for auto-flushing. The ODL allows log records to be buffered, till it encounters a log record with a level equal to or higher than the specified auto-flush level, and at that time ODL automatically flushes the buffer. The available values are: TRACE, DEBUG, NOTIFICATION, WARN, ERROR, and FATAL. Default is NOTIFICATION.
Note:
The log level can also be changed using the Administration API (<logLevel> child element of the <crawlerSettings> element of the sources object). Oracle SES uses the log level that is more granular of the two (configured in clexecutor.sh file and configured using Administration API).Use these operations to manage creatable administration objects:
Table 1-6 Operations on Creatable Objects
| Operation | Description |
|---|---|
|
|
Creates an object from an XML file. |
|
|
Creates all the objects of a particular type from an XML file. |
|
|
Deletes a single object. |
|
|
Deletes all objects of a particular type. |
|
|
Deletes a list of objects of a particular type. |
|
|
Returns the XML description of an object. |
|
|
Returns the XML descriptions of all objects of a particular type. |
|
|
Returns the XML descriptions of a list of objects of a particular type. |
|
|
Sets the parameters of an object from an XML file. |
|
|
Sets the parameters of all objects of a particular type from an XML file. |
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 |
|---|---|
|
|
Enables an object. Objects that can be enabled have a |
|
|
Disables an object. Objects that can be disabled have a |
|
|
Returns the current state of all objects of a particular type as an XML document. |
|
|
Returns the state of an object as an XML document. |
|
|
Returns the state of a list of objects of a particular type as an XML document. |
|
|
Initiates the starting process of an object. |
|
|
Initiates the stopping process of an object. |
Operations that involve multiple objects, such as createAll, deleteAll and deleteList, return status codes for each processed object, as described in Table 1-8.
| Status Code | Description |
|---|---|
|
|
The object cannot be created. |
|
|
The object was successfully created. |
|
|
The object cannot be deleted. |
|
|
The object was successfully deleted. |
|
|
The object already existed. The operation ignored the pre-existing object. |
|
|
The object already existed. The operation overwrote the pre-existing object. |
|
|
The object was ignored because it was in an invalid state. |
|
|
The object did not exist. The operation created the object. |
|
|
The object did not exist. The operation ignored the object. |
|
|
The object cannot be updated. |
|
|
The object was successfully updated. |