Enterprise search applications

Enterprise search applications can access collections, issue queries, and process query results.

See the Javadoc documentation for examples of the search and index APIs.

To create an enterprise search application with the search and index APIs:

Instantiate an implementation of a SearchFactory object.

Use the SearchFactory object to obtain a SearchService object.

The SearchService object is configured with the connection information that is necessary to communicate with the search engine. With the SearchService object, you can access searchable collections. Configure the SearchService object with the Watson Content Analytics administrator user name and password, host name, and port. Configuration parameters are set in a java.util.Properties object. The parameters are then passed to the getSearchService factory method that generates the SearchService object.

Tip: Search server authentication is enabled by default. To disable authentication:

Back up and open the $ES_NODE_ROOT/master_config/searchserver/dock/dock.xml file in a text editor that supports UTF-8.
Change the value of the <portSecurity> element to false and save the file.
Restart Watson Content Analytics by entering the following commands:
```
esadmin system stop
esadmin system start
```

Watson Content Analytics applications support Secure Sockets Layer (SSL) version 3. However, applications that use SSL must include a reference to an existing keystore. WebSphere® Application Server provides a utility called iKeyman.exe in the Java™ Runtime Environment bin directory that can be used for working with keystores.

With SSL, you can establish a security-enabled website on the Internet or on your private intranet. A browser that does not support HTTP over SSL cannot request URLs that use HTTPS.

When you request a search and index API service, such as SearchService searchService = factory.getSearchService(Properties);, you can use any of the following properties for a service object. The property names are case sensitive.

Table 1. Property values for service API objects
Property name	Expected value
protocol	HTTP or HTTPS for SSL. The default is HTTP. If the protocol is HTTPS, the host name must be fully qualified and the port must be the SSL port. The default port is 443.
trustStore	The fully qualified path to the keystore. If the operating system is Windows, the backslashes must be escaped with a double backslash, for example, `c:\\temp\\WASWebContainer.jks`. Restriction: If the protocol is HTTPS, the trustStore value must not be empty. An exception is thrown if the trustStore property is null.
trustPassword	The password to access the keystore. Restriction: If the protocol is HTTPS, then the trustPassword value must not be empty. An exception is thrown if the trustPassword property is null.
proxyHost	The host name of the proxy server.
proxyPort	The port number for the proxy server.
proxyUser	If the proxy server requires HTTP basic authentication, this is the user name for that login request.
proxyPassword	The password for the user that is specified by the proxyUser parameter.
timeout	How much time can elapse before the request to the search server (ESSearchServer) times out.

Obtain a Searchable object.
After you obtain a SearchService object, you can use it to obtain one or more Searchable objects. Each search and index API searchable object is associated with one collection. You can also use the SearchService object to obtain a federator object. A federator object is a special kind of Searchable object that enables you to submit a single query across multiple Searchable objects (collections) at the same time.

When you request a Searchable object, you need to identify your application by using an application ID. Contact your Watson Content Analytics administrator for the appropriate application ID.
Issue queries.
The enterprise search application passes search queries to the search runtime on the search server.
After the Searchable object is obtained, you issue a query to that Searchable object. To issue a query to the Searchable object:
1. Create a Query object.
2. Customize the Query object.
3. Submit the Query object to the Searchable object.
4. Get the query results, which are specified in a ResultSet object.
Process query results.
Process queries with the ResultSet interface object and the Result interface object. The search and index APIs have a variety of methods for interacting with the ResultSet interface and individual Result interface objects.

The search and index APIs are a factory-based Java API. All of the objects that are used in the enterprise search application are created by calling search and index API object-factory methods or are returned by calling methods of factory-generated objects. You can easily switch between search and index API implementations by loading different factories.

The search and index API implementation in Watson Content Analytics is provided by the com.ibm.es.api.search.RemoteSearchFactory class.

Use the following search and index API packages to create an enterprise search application:

com.ibm.siapi: Root package
com.ibm.es.api.browse: Contains taxonomy browsing interfaces
com.ibm.siapi.common: Common SIAPI interfaces
com.ibm.siapi.search: Interfaces for searching collections
com.ibm.siapi.search.facets: Interfaces for faceted search

Obtaining a SearchFactory object

To create a search and index API enterprise search application, obtain the implementation of the SearchFactory object as in the following example:

Class cls = Class.forName("com.ibm.es.api.search.RemoteSearchFactory");
SearchFactory factory = (SearchFactory) cls.newInstance();

Obtaining a SearchService object

Use the SearchFactory object to obtain a SearchService object. With the SearchService object, you can access searchable collections.

Configure the SearchService object with the host name, port, and, if WebSphere global security is enabled, a valid WebSphere user name and password for the search server.

Configuration parameters are set in a java.util.Properties object. The parameters are then passed to the getSearchService factory method that generates the SearchService object. The following example shows how to obtain a SearchService object:

Properties configuration = new Properties();
configuration.setProperty("hostname", "es.mycompany.com");
configuration.setProperty("port", "80");
configuration.setProperty("username", "websphereUser");
configuration.setProperty("password", "webspherePassword");
SearchService searchService =
	factory.getSearchService(configuration);

Obtaining a Searchable object

Use the SearchService object to obtain a Searchable object. A Searchable object is associated with a searchable collection. With a Searchable object, you can issue queries and get information about the associated collection. Each collection has an ID.

When you request a Searchable object, you need to identify your application by using an application ID. Contact your Watson Content Analytics administrator for the appropriate application ID.

The following example shows how to obtain a Searchable object:

ApplicationInfo appInfo = factory.createApplicationInfo
("my_application_id","my_password");
Searchable searchable = 
	searchService.getSearchable(appInfo, "some_collection_id");

Call the getAvailableSearchables method to obtain all of the Searchable objects that are available for your application.

Searchable[] searchables = 
	searchService.getAvailableSearchables(appInfo);

Issuing queries

After the Searchable object is obtained, you issue a query to that Searchable object. To issue a query to the Searchable object:

Create a Query object.
Customize the Query object.
Submit the Query object to the Searchable object.
Get the query results, which are specified in a ResultSet object.

The following example shows how to issue a query:

String queryString = "big apple";
Query query = factory.createQuery(queryString);
query.setRequestedResultRange(0, 10);
ResultSet resultSet = searchable.search(query);

Processing query results

With the ResultSet interface and Result interface, you can process query results, as in the following example:

Result[] results = resultSet.getResults();
for ( int i = 0 ; i < results.length ; i++ ) {
	System.out.println
( "Result " + i + ": " + results[i].getDocumentID()
	 + " - " + results[i].getTitle() );
}