Oracle® Secure Enterprise Search Administration API Guide 11g Release 2 (11.2.1) Part Number E17595-04 |
|
|
View PDF |
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 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 $
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> $
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
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 |
---|---|
|
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]
Administrator user name, which is searchsys
by default.
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.
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:
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
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"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
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.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"
);
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.
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 |
|
Document service instance |
|
Document service manager |
|
Document service pipeline |
|
Facet tree |
|
Identity plug-ins |
|
Proxy log-ins |
|
Schedules |
|
Search attributes |
|
Sources |
|
Source groups |
|
Source types |
|
Suggested links |
|
Thesaurus |
Footnote 1 These objects cannot be created or modified in Oracle Fusion Applications.
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.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>
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.
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:
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.
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".
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]
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
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.
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.
Table 1-8 Status Codes
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. |