5 Searching for Documents

This chapter has the following sections:

5.1 About Searching for Documents

The Imaging API provides the SearchService for enumerating and executing saved searches. The execution of a saved search requires the user to provide the NameId of the search and a List of SearchArguments objects for the search. The arguments form the variable portion of the WHERE clause in the search. These are passed to the SearchService. executeSavedSearch operation, which returns a Search.ResultSet. At the end of the chapter, Example 5-1 provides a code sample of the topics presented here.

5.2 Listing Saved Searches

The Imaging API provides the SearchService.listSearches methods for listing searches that are available for the logged in user. This operation accepts an Ability parameter that specifies which applications to return based the user's security settings. It returns applications based on search definition security. Ability.VIEW returns all searches to which the calling user has view permission. The Ability.MANAGE parameter returns all searches to which that user has either delete or modify permissions.

The operation returns a java.util.List of NameId objects identifying both the numerical ID and the textual name for the search.

5.3 Providing Search Arguments

A saved search may define one or more search parameters that Imaging will assemble into the WHERE clause for the search. In the Imaging API, the SearchArgument class is used to pass arguments for these parameters. The constructor for SearchArgument accepts the name of the parameter as well as SearchValue object specifying its value. The operator for the argument must be set using the SearchArgument.setOperator method.

Multiple SearchArguments are passed as a java.util.List. The order of the arguments in the list is not significant.

When calling SearchService.getSearchParameters and passing search NameId, SearchParameters are returned. This defines the parameters defined by the search and can help you build the SearchArguments necessary to execute the search. The SearchParameters also defines whether each parameter is required.

5.4 Executing a Search

The SearchService.executeSavedSearch method returns the results of the search in the form of a Search.ResultSet. The column labels are available in the Search.Result from the getColumns method, which returns an ordered java.util.List of Strings.

5.5 Parsing Search Results

The rows of the results are available from the Search.Results getResults method which returns a java.util.List of Search.Result objects. Each Search.Result represents a single document found by the search.

The search result columns are returned by the getColumnValues which is an ordered list of TypedValues. The order matches the order of the column labels list. System field values for the document are accessible from Document object returned by Search.Result.getDocument.

5.6 Execute Search Sample

Example 5-1 demonstrates the basic concepts discussed in this section.

Example 5-1 Sample Search Execution

package devguidesamples;

import java.util.ArrayList;
import java.util.List;
import java.util.Locale;

import oracle.imaging.BasicUserToken;
import oracle.imaging.ImagingException;
import oracle.imaging.NameId;
import oracle.imaging.Search;
import oracle.imaging.SearchArgument;
import oracle.imaging.SearchService;
import oracle.imaging.SearchValue;
import oracle.imaging.ServicesFactory;
import oracle.imaging.TypedValue;
import oracle.imaging.UserToken;

public class ExecuteSearchSample {
   public static void main(String[] args) {
      try { // try-catch
         UserToken credentials = new BasicUserToken("ipmuser", "ipmuserpwd");
         ServicesFactory servicesFactory = 
            ServicesFactory.login(credentials, Locale.US,
               "http://ipmhost:16000/imaging/ws");

         try { // try-finally to ensure logout
            SearchService searchService = servicesFactory.getSearchService();

            NameId invoiceSearchNameId = null;

            // List the viewable applications to confirm that "Invoices" exists
            List<NameId> searchList = 
               searchService.listSearches(Search.Ability.VIEW);
            for (NameId nameId: searchList) {
               if (nameId.getName().equals("Invoices")) {
                  invoiceSearchNameId = nameId;
               }
            }

            if (invoiceSearchNameId == null) {
               System.out.println("Invoices search not found.");
               return;
            }

            SearchValue searchValue = new SearchValue(SearchValue.Type.NUMBER, 1234);
            SearchArgument searchArgument = 
               new SearchArgument("Invoice Number", searchValue);
            searchArgument.setOperatorValue(Search.Operator.EQUAL);

            List<SearchArgument> searchArguments =
               new ArrayList<SearchArgument>();
            searchArguments.add(searchArgument);

            Search.ResultSet resultSet = searchService.executeSavedSearch(invoiceSearchNameId,searchArguments);

            // Display Column Headers
            System.out.print("DocumentId" + "  ");
            for (String column: resultSet.getColumns()) {
               System.out.print(column + "  ");
            }
            System.out.println();

            // Display result Rows
            for (Search.Result row: resultSet.getResults()) {
               System.out.println(row.getDocument().getId());
               for (TypedValue typedValue: row.getColumnValues()) {
                  System.out.print(typedValue.getStringValue() + "  ");
               }
               System.out.println();
            }
         }
         finally {
            if (servicesFactory != null) {
               servicesFactory.logout();
            }
         }
      }
      catch (ImagingException e) {
         System.out.println(e.getMessage());
      }
   }
}