24 Integrating the Search Service

This chapter explains how to integrate the Search service in a custom WebCenter application at design time.

For more information about managing and including search, see:

This chapter includes the following sections:

24.1 Introduction to Search

WebCenter search provides a unified, extensible framework that enables the discovery of information and people through an intuitive user interface. It honors application security settings by returning only the results a user is authorized to view. Because a search spans all accessible services—and can be extended to span your enterprise—users are not required to switch between applications to perform multiple searches. Additionally, users can save their searches for reuse. This includes searches with complex search refinement conditions.

Any WebCenter service that owns resources supports Search. This includes: announcements, discussions, documents, tags, wikis/blogs, and pages. You can use the adapter to Oracle Secure Enterprise Search (SES) instances to search resources outside of WebCenter.

If you have the Documents service in your application, then Search looks for terms in document names and in the documents themselves. The results include tags, so any matching tags on your documents and pages are also returned, with relevance based on the quality and frequency of tags.

Note:

Tag results are unaffected when you refine a search. The dates and user names used to refine a search are not provided to the search engine during tagging. You can discover more information about tags, such as who added them, in the Tag Center.

For more information about the Tag Center, see Section 23.1, "Introduction to the Tags Service."

The way that search results open differs according to the service that provides them. For example, results from the Documents service open in a new browser tab or window. Results from services that provide resource viewers, such as Discussions or Announcements, open in their resource viewers. For more information about resource viewers and the Resource Action Handling framework, see Section 4.2, "Extending Your Application with Custom Components."

24.1.1 Understanding the Search Service

WebCenter Search uses search adapters to find content created inside WebCenter applications by WebCenter services: It does not rely on Oracle Secure Enterprise Search (SES).

However, you can extend WebCenter searches to external content repositories by connecting the WebCenter application to an Oracle SES instance. Providing that the Oracle SES instance is set up to search external repositories, results from these search sources can appear alongside WebCenter application search results. Supported versions include Oracle SES 10.1.8.4 or later. You can register multiple Oracle SES connections but only one of them is active at a time.

WebCenter Spaces

In WebCenter Spaces, you can configure Oracle SES to search WebCenter services, instead of using the individual search adapters for each service. This provides a unified ranking system for all search results in WebCenter Spaces. For more information, see the section "Overriding Default Search Adapters in WebCenter Spaces" in the Oracle Fusion Middleware Administrator's Guide for Oracle WebCenter.

24.1.2 What Happens at Runtime

With the Search service, you can create, run, refine, and save custom searches. By default, WebCenter Search looks for your search terms in every searchable service available to the application (a global search). You can perform a global search from any Search task flow, or from the Search Toolbar.

In a custom WebCenter application, search results are displayed in a separate window, where you can scroll through all the results. Optionally, in the Search Results window click the More button. The results of saved searches appear in a new Search Results window.

The Search Preferences task flow lets users control which WebCenter services to search. Users also can control the order in which those services are listed in the results, and what information is included, such as the type, size, or owner of the object returned. (For information about adding the task flow, see Section 24.3.3, "Adding the Search Preferences Task Flow.")

To set search preferences in a custom WebCenter application:

  1. Log in and locate the page that contains the Search Preferences task flow.

  2. To specify the services to be searched, select one or more services on the Available Services list by checking their checkboxes, and then click the Move icon to move them to the Selected Services list.

    You can also specify the order in which the search results are displayed by clicking the move up and move down icons next to the Selected Services list.

  3. To specify the type of information to display with the search results, click the Columns tab and move one or more items from the Available Columns list to the Selected Columns list. Choose from the following:

    • Icon displays an icon representing the item type.

    • Title displays linked titles.

    • Person to display the user name of the person who owns the item.

    • Size displays the size of the item, for example, file size.

    • Date displays the date the item was added to the application.

    • Type displays the type of the item, for example image.

    You can also specify the order in which this information is displayed by clicking the move up and move down icons next to the Selected Columns list.

  4. Click OK to save your changes.

For more information about the Search service and task flows at runtime, see Oracle Fusion Middleware User's Guide for Oracle WebCenter.

Note:

You can see the Search service in action in the sample application, as described in Chapter 2, "Introduction to the WebCenter Sample Application."

24.2 Basic Configuration for the Search Service

This section provides the steps for adding the Search service to your application. It contains the following subsections:

24.2.1 Setting up Connections for the Search Service

The Search service does not require a connection. However, to incorporate Oracle Secure Enterprise Search (SES) results in your result set, you must add a connection to Oracle SES. For more information, see Section 24.3.4, "Including Oracle SES Results in WebCenter Search Results."

24.2.2 Adding the Search Service at Design Time

This section describes the Search service task flows and explains how to integrate the Search service into your application. It contains the following subsections:

24.2.2.1 Search Service Task Flows

Table 24-1 lists the Search service task flows.

Table 24-1 Search Service Task Flows

Task Flow Definition

Search

This task flow provides a rich search experience with several options for searching and features for refining and saving search results.

Search - Saved Searches

This task flow enables you to create a simple launch pad for running saved searches within the application.

Search Preferences

This task flow enables users to select which WebCenter services to search. It also provides users with a means of selecting and ordering the columns available in the search results of the Search task flow.

Search Toolbar

This task flow enables users to enter simple search criteria and run the search from the application. Search results are rendered as links.

24.2.2.2 How to Add the Search Service to Your Application

The Search Toolbar task flow offers the easiest way to add the Search service to your application To add the Search Toolbar task flow to your WebCenter application:

  1. Follow the steps described in Chapter 3, "Preparing Your Development Environment" to implement security and create a customizable page in your application.

  2. Open the page on which to add the Search service.

  3. In the Resource Palette, expand My Catalogs, WebCenter Services Catalog, and Task Flows.

  4. Drag and drop the Search Toolbar task flow onto the page.

  5. When prompted, select Region as the way to create the task flow.

    If a prompt to confirm the ADF library appears, click Add Library.

  6. Run your page with the search toolbar on it.

    In the Application Navigator, right-click this application and select Run. It may take a few moments for the operation to complete.

    Note:

    To return results, the Search service requires that other WebCenter services are included in the application.

On the Source tab of the page where you added the toolbar, you can see the Search Toolbar task flow in the page source, similar to Example 24-1.

Example 24-1 Search Toolbar Task Flow Source

      <af:form id="f1">
        <af:region value="#{bindings.searchtoolbar1.regionModel}" id="r1"/>
      </af:form>

In the Source view of the pagenamepageDef.xml file, you should see something similar to Example 24-2.

Example 24-2 pageDef.xml File with the Search Toolbar

<taskFlow id="searchtoolbar1"
     taskFlowId="/oracle/webcenter/search/controller/taskflows/
     localToolbarSearch.xml#search-toolbar"
     xmlns="http://xmlns.oracle.com/adf/controller/binding"/>

24.2.3 Setting Security for the Search Service

The query execution of individual services ensures that the user performing the search can view results. Search results are returned based on user privileges.

The Search service does not require ADF security. When unauthenticated, search queries provided by all services return only public content. However, only authenticated users of an ADF-secured WebCenter application can save searches. Unauthenticated users see the Save button grayed out (See Figure 24-2).

For information about configuring ADF security, see Section 3.5, "Implementing Security in Your Application."

24.3 Advanced Information for the Search Service

This section describes optional features available with this service. It contains the following subsections:

24.3.1 Adding the Search Task Flow

To add the Search task flow to your WebCenter application, follow the instructions provided for the Search Toolbar task flow in Section 24.2.2, "Adding the Search Service at Design Time," but instead, drag and drop the Search task flow onto the page.

In the Design view of the page, you should see something similar to Figure 24-1.

Figure 24-1 Search in Design View

Description of Figure 24-1 follows
Description of "Figure 24-1 Search in Design View"

To run the page with the Search view:

  1. In the Application Navigator, right-click the page and select Run.

    As long as the application has been ADF-secured, you should see a login page. It may take a few moments for the operation to complete.

  2. If you configured ADF security, then enter the user name and password that you provided and click Submit.

  3. You should see your page with the Search main view (Figure 24-2).

    Figure 24-2 Search Main View

    Description of Figure 24-2 follows
    Description of "Figure 24-2 Search Main View"

  4. Enter some search criteria in the field and click the Search icon.

    You should see the results displayed on the page. At this time, you get few, if any, results because the application is not populated with much besides the Search service itself.

24.3.2 Adding the Search - Saved Searches Task Flow

You can add the Search - Saved Searches task flow to provide a simple launch pad for running saved searches within the application. To add this task flow to your WebCenter application, follow the instructions provided for the Search Toolbar task flow in Section 24.2.2, "Adding the Search Service at Design Time," but instead, drag and drop the Search - Saved Searches task flow onto the page.

In the Design view of the page, you should see something similar to Figure 24-3.

Figure 24-3 Search - Saved Searches Task Flow

Description of Figure 24-3 follows
Description of "Figure 24-3 Search - Saved Searches Task Flow"

The task flow renders links that, when clicked, run a saved search.

24.3.3 Adding the Search Preferences Task Flow

By default, WebCenter searches all WebCenter services in your application. However, the Search Preferences task flow enables users to control that selection. Services that are not selected in preferences are not searched.

The Search Preferences task flow also provides a means of selecting and ordering the columns available in the results returned in the Search task flow.

To add the Search Preferences task flow to your WebCenter application, follow the instructions provided for the Search Toolbar task flow in Section 24.2.2, "Adding the Search Service at Design Time," but instead, drag and drop the Search Preferences task flow onto the page.

In the Design view of the page, you should see something similar to Figure 24-4.

Figure 24-4 Search Preferences Task Flow

Description of Figure 24-4 follows
Description of "Figure 24-4 Search Preferences Task Flow"

For information about running the Search Preferences task flow at runtime, see Section 24.1.2, "What Happens at Runtime."

24.3.4 Including Oracle SES Results in WebCenter Search Results

If you have an Oracle Secure Enterprise Search (SES) instance for searching other repositories outside of Oracle WebCenter, then you can integrate it with your application. SES results appear in the same result set as WebCenter search results.

For secure searches, your WebCenter application and your Oracle SES instance must use the same identity management system.

This section describes how to include Oracle SES results in WebCenter searches and how to validate this configuration. It contains the following subsections:

24.3.4.1 Including Oracle SES Results in WebCenter Searches

To include Oracle SES results:

  1. Add the search toolbar to a page, following Section 24.2.2, "Adding the Search Service at Design Time."

  2. In the Application Navigator, expand Application Resources.

  3. Right-click the Connections node, and select Oracle Secure Enterprise Search.

  4. Enter values for the fields in the dialog.

    For example:

    1. In Oracle WebCenter, select to create the connection in either the Application Resources or IDE Connections.

      A connection in Application Resources is available only for that application, while a connection in IDE Connections is available for all applications you create. If you plan to use the connection in other applications, then select IDE Connections to avoid the need to re-create it.

      Note:

      If you create the connection in IDE, then the connection must be added to the application later. For example, in the Resource Palette under IDE Connections, right-click the connection and select Add to Application.

    2. For Connection Name, enter a meaningful name, for example, SES_instance.

    3. For SOAP URL, enter the URL for the Oracle SES Web Services endpoint, for example:

      http://host:port/search/query/OracleSearch

    4. Under Proxy Login, for App User Name, enter the trusted entity defined for this application and the Oracle SES instance; for example, wpadmin.

      You can find (or create) the trusted entity on the Global Settings - Federation Trusted Entities page of Oracle SES.

    5. For App Password, enter the password of the Federation Trusted Entities user.

    6. Select the box for Set as default connection for the Search Service.

      This ensures that your application uses that connection to access Oracle SES. The Search service uses only one Oracle SES connection.

      Note:

      After you create a connection as the default connection, you cannot edit it so that it is not the default. To use a different default connection, you must create a new connection and mark that as the default connection.

    7. Under Testing, for User name, enter the name of a user present in both the Oracle Identity Management server configured for your WebCenter application and the Oracle Identity Management server configured for Oracle SES.

      You should see something similar to Figure 24-5.

    8. Figure 24-5 Create Oracle SES Connection Dialog

      Description of Figure 24-5 follows
      Description of "Figure 24-5 Create Oracle SES Connection Dialog"

  5. Click Test Connection.

  6. If the connection is successful, then click OK.

After you have included the Oracle SES connection in your application, you should see it in your Application Resources panel, as shown in Figure 24-6.

Figure 24-6 Oracle SES Connection in Application Resources

Description of Figure 24-6 follows
Description of "Figure 24-6 Oracle SES Connection in Application Resources"

The Oracle SES connection is now included in the connections.xml file and is the default connection in the adf-config.xml file, as shown in Example 24-3.

Example 24-3 Oracle SES Connection in adf-config.xml

<ses-properties>
  <connection>GenericSesConnection</connection>
  <data-group>oracle-sites</data-group>
</ses-properties>

The Oracle Secure Enterprise Search connection wizard does not provide a means of setting the data-group value in adf-config.xml. After the connection is established, you must set it manually. Check the data-group on your Oracle SES instance to set to the correct value.

You can also set the data-group value to be any a data source group created in your Oracle SES instance. Data source groups present a good way to segment your searchable data on Oracle SES. Given an Oracle SES instance that keeps a search index on all corporate data, you can use data source groups to make only a portion of your corporate data available to a WebCenter search. For more information on creating data groups, see the Oracle SES Administrator's Guide.

Note:

While you can set up the connections to back-end servers at design time in Oracle JDeveloper, you can later add, delete, or modify connections in your deployed environment using Enterprise Manager Fusion Middleware Control. For more information, see Oracle Fusion Middleware Administrator's Guide for Oracle WebCenter.

24.3.4.2 Validating the Oracle SES Connection

To validate the inclusion of Oracle SES results in WebCenter search:

  1. In the Application Navigator, right-click the page you created with the Search Toolbar, and click Run.

    As long as the application has been ADF-secured, you should see a login page. It may take a few moments for the operation to complete.

  2. Enter the user name and credentials that you created when you defined security.

  3. Click Submit.

    It may take a few moments for the page to load. When it completes, you should see your search toolbar.

    Figure 24-7 shows example results for the search term webcenter.

    Figure 24-7 Search Results Dialog with Oracle SES Included

    Description of Figure 24-7 follows
    Description of "Figure 24-7 Search Results Dialog with Oracle SES Included"

Note:

You can use a web service data control to call the searching function of Oracle SES. For more information, see Appendix E, "Calling Oracle SES to Search Data."

For more information on Oracle SES, see the Oracle Secure Enterprise Search documentation on the Oracle Fusion Middleware documentation library (in the WebCenter product area).

24.3.5 Using Search Service APIs

Custom components can implement Search service APIs to expose their content to a WebCenter search. For more information, see Oracle Fusion Middleware Java API Reference for Oracle WebCenter.

24.3.6 Building Adapters for the Search Service

By default, the Search service searches any WebCenter service in your application. In some cases, you may want to add other sources to your search.

You can extend WebCenter search through search adapters. WebCenter framework automatically discovers these search adapters and consolidates them in formulating search results in your custom WebCenter application. Subsequently, when you expose your custom component to the Search service in your application, it is included in the federated search.

This section describes how to extend WebCenter search through search adapters. It contains the following subsections:

24.3.6.1 How to Add a Search Source

To add a new search source, you must create Java classes for the new source to manage the incoming queries and return search results. After you add the necessary Java classes to your application, you must register them with the Search service.

When performing a search, the search framework calls QueryManager.createRowQueryHandler with a query object and a List<QName> that describes the columns sought. In return, the framework receives a QueryHandler<Row>.

A QueryHandler can be a QueryFederator or a QueryExecutor. A QueryFederator is just a collection of other QueryHandlers. With the QueryFederator, the framework can get a list of the child QueryHandlers and keep recursing until all QueryExecutors are found.

The framework calls the execute method on the QueryExecutor to get a QueryResult<Row>, which is an extension of java.util.Iterator<Row> that iterates and retrieves rows of results.

One possible implementation would be to create these classes:

  • SampleQueryManager ...

  • SampleRowQueryExecutor ...

  • SampleRowQueryResult ...

  • SampleRow ...

To add a new search source with a similar query manager:

  1. In Oracle JDeveloper, open the application in which to add the search source.

  2. Confirm that the WebCenter Common library is included in your project:

    1. Right-click your ViewController project and select Project Properties and then Libraries and Classpath.

    2. If the WebCenter Common library is not included, as shown in Figure 24-8, then click Add Library and select it.

      Figure 24-8 WebCenter Common Library

      Description of Figure 24-8 follows
      Description of "Figure 24-8 WebCenter Common Library"

    3. Click OK.

  3. Create a class called SampleQueryManager.java (Example 24-4).

    Example 24-4 SampleQueryManager.java

    package mycompany.myproduct.myapp.mycomponent.query;
import java.util.List;
import oracle.webcenter.search.QName;
import oracle.webcenter.search.Query;
import oracle.webcenter.search.QueryExecutor;
import oracle.webcenter.search.QueryManager;
import oracle.webcenter.search.Row;
public class SampleQueryManager
  implements QueryManager
{
  public SampleQueryManager()
  {
  }
  public QueryExecutor<Row> createRowQueryHandler(Query query,
                                                  List<QName> columns)
  {
    return new SampleRowQueryExecutor(query, columns);
  }
}

  4. Create a class called SampleRowQueryExecutor.java (Example 24-5).

    Example 24-5 SampleRowQueryExecutor.java

    package mycompany.myproduct.myapp.mycomponent.query;
import java.text.DateFormat;
import java.text.ParseException;
import java.text.SimpleDateFormat;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.Iterator;
import java.util.List;
import java.util.Map;
import static oracle.webcenter.search.AttributeConstants.DCMI_EXTENT;
import static oracle.webcenter.search.AttributeConstants.DCMI_MODIFIED;
import static oracle.webcenter.search.AttributeConstants.DCMI_CREATOR;
import static oracle.webcenter.search.AttributeConstants.DCMI_TITLE;
import static oracle.webcenter.search.AttributeConstants.DCMI_URI;
import static oracle.webcenter.search.AttributeConstants.DCMI_IDENTIFIER;
import static oracle.webcenter.search.AttributeConstants.WPSAPI_ICON_PATH;
import oracle.webcenter.search.QName;
import oracle.webcenter.search.Query;
import oracle.webcenter.search.QueryExecutor;
import oracle.webcenter.search.QueryHandler;
import oracle.webcenter.search.QueryResult;
import oracle.webcenter.search.Row;
public class SampleRowQueryExecutor
  implements QueryExecutor<Row>
{
  private static final int PRESET_ESTIMATED_RESULT_COUNT = 10;
  private static final int PRESET_VALUES_BATCH_SIZE = 5;
  private static final int MAX_RESULT_LIMIT = 100;
  private int m_resultStart;
  private int m_resultLimit;
  private Query m_query;
  private List<QName> m_columns;
  private Map<String, String> m_properties;
  public SampleRowQueryExecutor(Query query, List<QName> columns)
  {
    m_query = query;
    m_columns = columns;
    m_properties = new HashMap<String, String>();
    // In actuality you may want to make sure this string is translatable
    m_properties.put(QueryHandler.TITLE, "Sample");
  }
  /**
   * Create a number of rows for "batchRepeat" times.
   */
  private static void createRows(List<Row> rows, int batchRepeat)
  {
    while (batchRepeat-- > 0)
    {
      rows.add(new SampleRow("23847", "Initial Sorting of Tables", 
                             "Bar", "2006-06-08", 5120));
      rows.add(new SampleRow("4827445", "Support for facelets?", 
                             "Foo", "2006-04-17", 1400000));
      rows.add(new SampleRow("952787", "For Thomas Kincade's validation demo", 
                             "Tiger", "2006-01-09", 1300000));
      rows.add(new SampleRow("4394588", "Page not showing in WYSIWYG fashion",
                             "Ken Swartz", "2006-04-27", 3000));
      rows.add(new SampleRow("3920", "Tree table", 
                             "Scott", "2006-03-24", 1200));    
    }
  }
  /**
   * Instead of doing a query execution here, 
   * we'll just create a bunch of rows.
   */
  public QueryResult<Row> execute()
  {
    List<Row> rows = new ArrayList<Row>();
    // We want to hit a certain count here but not go over the max
    int realLimit = Math.min(MAX_RESULT_LIMIT, m_resultLimit);
    createRows(rows, (realLimit / PRESET_VALUES_BATCH_SIZE));
    // Create the QueryResult
    QueryResult<Row> ret = new SampleRowQueryResult(rows.iterator());
    ret.getProperties().put(QueryResult.ESTIMATED_RESULT_COUNT, 
                            Integer.toString(PRESET_ESTIMATED_RESULT_COUNT));
    return ret;
  }
  /**
   * Remember the result start.
   */
  public void setResultStart(int resultStart)
  {
    m_resultStart = resultStart;
  }
  /**
   * Store away the result limit to use in the execute
   * so that we only get that number of results back.
   */
  public void setResultLimit(int resultLimit)
  {
    m_resultLimit = resultLimit;
  }
  /**
   * Expose our properties map containing our title.
   */
  public Map<String, String> getProperties()
  {
    return m_properties;
  }
}

  5. Create a class called SampleRowQueryResult.java (Example 24-6).

    Example 24-6 SampleRowQueryResult.java

    package mycompany.myproduct.myapp.mycomponent.query;
import java.util.Iterator;
import oracle.webcenter.search.util.WrapperQueryResult;
import oracle.webcenter.search.Row;
public class SampleRowQueryResult extends WrapperQueryResult<Row>
{
  public SampleRowQueryResult(Iterator<Row> rows)
  {
    super(rows);
  }
}

  6. Create a class called SampleRow.java (Example 24-7).

    Example 24-7 SampleRow.java

    package mycompany.myproduct.myapp.mycomponent.query;
import java.text.DateFormat;
import java.text.ParseException;
import java.text.SimpleDateFormat;
import java.util.Calendar;
import java.util.Date;
import java.util.HashMap;
import java.util.Iterator;
import java.util.Map;
import oracle.webcenter.search.QName;
import oracle.webcenter.search.Row;
import static oracle.webcenter.search.AttributeConstants.DCMI_EXTENT;
import static oracle.webcenter.search.AttributeConstants.DCMI_MODIFIED;
import static oracle.webcenter.search.AttributeConstants.DCMI_CREATOR;
import static oracle.webcenter.search.AttributeConstants.DCMI_TITLE;
import static oracle.webcenter.search.AttributeConstants.DCMI_URI;
import static oracle.webcenter.search.AttributeConstants.DCMI_IDENTIFIER;
import static oracle.webcenter.search.AttributeConstants.WPSAPI_ICON_PATH;
public class SampleRow implements Row
{
  private Map<QName, Object> m_storage = new HashMap<QName, Object>();
  private DateFormat m_dateFormat = new SimpleDateFormat("yyyy-MM-dd");
  SampleRow(String id, String title, 
            String creator, String lastModified,
            int size)
  {
    m_storage.put(DCMI_IDENTIFIER, id);
    // Only if you have an external URL to go to
    // m_storage.put(DCMI_URI, "http://my.external.url");
    m_storage.put(DCMI_TITLE, title);
    m_storage.put(DCMI_CREATOR, creator);
    // The below path points to a path accessible in the classpath to an icon
    m_storage.put(WPSAPI_ICON_PATH, "/adf/webcenter/search_qualifier.png");
    try
    {
      Date date = m_dateFormat.parse(lastModified);
      Calendar cal = Calendar.getInstance();
      cal.setTime(date);
      m_storage.put(DCMI_MODIFIED, cal);
    }
    catch (ParseException e)
    {
      e.printStackTrace();
    }
    m_storage.put(DCMI_EXTENT, new Long(size));
  }
  public Object getObject(QName columnName)
  {
    return m_storage.get(columnName);
  }
  public Iterator<QName> getColumns()
  {
    return m_storage.keySet().iterator();
  }
}

24.3.6.2 How to Register a Custom Adapter

To register your query manager with the Search service, you must edit the service-definition.xml file. The SampleQueryManager line exposes the custom adapter's query manager implementation to the Search service so that the custom adapter is included with any search user interface.

The entry should be similar to Example 24-8.

Example 24-8 Sample Query Manager Entry in service-definition.xml

<service-definition id="mycompany.myproduct.myapp.mycomponent"
   version="11.1.1.0.0">
  <resource-view taskFlowId="/somepath/somefile.xml#someId"
                    authorizerClass="some.service.id.Authorizer1"/>
  <name>Custom Component 1</name>
  <description>Description for Custom Component 1</description>
  <search-definition xmlns="http://xmlns.oracle.com/webcenter/search"
      id="mycompany.myproduct.myapp.mycomponent.query" version="11.1.1.0.0">
  <query-manager-class>
mycompany.myproduct.myapp.mycomponent.query.SampleQueryManager
  </query-manager-class>
  </search-definition>
</service-definition>

For more information about the resource-view tag (and Oracle WebCenter's Resource Action Handling framework), see Section 4.2, "Extending Your Application with Custom Components."

24.3.6.3 Search Adapter Attributes

This section describes the attributes available for searching a service. It contains the following subsections:

24.3.6.3.1 Searchable Attributes

The WebCenter search user interface exposes searches based on three fields: keywords, date, and person. Each service, in its own search implementation, honors these fields to the best of its capabilities. At minimum, it supports the keywords field. When you define your own search adapter, you must honor these fields to the best of your adapter's capabilities, as described in Section 24.3.6.3.8, "Selectable Attributes."

24.3.6.3.2 Keywords

By default, the keyword field is in oracle.webcenter.search.TextPredicate. The field can comprise multiple words, with the service determining how to interpret multiple words. The WebCenter Search service does not tokenize before the call comes to the service, but here are some guidelines:

  • If two or more tokens are enclosed within quotes, then they should be interpreted as one word.

  • Unless the OR operator is explicitly set, it is assumed that the default conjunction among the words in the keywords field is AND.

24.3.6.3.3 Date Condition

For the Search service to support filtering of query results by last modified date, the service implementation of the WPSAPI must support the use of oracle.webcenter.search.AttributePredicate, accessible from the query object, that uses oracle.webcenter.search.AttributeConstants.DCMI_MODIFIED. The supported comparators must include the following:

  • oracle.webcenter.search.ComparatorConstants.GREATER_THAN

  • oracle.webcenter.search.ComparatorConstants.GREATER_THAN_OR_EQUALS

They may also include the following:

  • oracle.webcenter.search.ComparatorConstants.EQUALS

  • oracle.webcenter.search.ComparatorConstants.NOT_EQUALS

  • oracle.webcenter.search.ComparatorConstants.LESS_THAN

  • oracle.webcenter.search.ComparatorConstants.LESS_THAN_OR_EQUALS

The literals for comparison should be of type java.util.Calendar.

24.3.6.3.4 Complex Date Condition

You can use the BETWEEN clause for dates. The complex date condition, instead of being a simple AttributePredicate, is a ComplexPredicate that contains one GREATER_THAN AttributePredicate and one LESS_THAN AttributePredicate with an AND conjunction operator. This ComplexPredicate must apply the AND operator with the rest of the fields (that is, keywords and person).

To differentiate between this case and the default case, service authors must check on the type of the predicate that is meant for the date condition. If it is an AttributePredicate, then it is the default case. If it is a ComplexPredicate, then it is a special case.

24.3.6.3.5 Person Condition

For the Search service to support filtering of query results by person, the service implementation of the WPSAPI must support the use of oracle.webcenter.search.AttributePredicate, accessible from the query object, that makes use of the oracle.webcenter.search.AttributeConstants.WPSAPI_MODIFIER.

The comparators supported must include the following:

  • oracle.webcenter.search.ComparatorConstants.EQUALS

  • oracle.webcenter.search.ComparatorConstants.CONTAINS

  • oracle.webcenter.search.ComparatorConstants.STARTS_WITH

  • oracle.webcenter.search.ComparatorConstants.ENDS_WITH

The literals for comparison should be of type java.lang.String.

24.3.6.3.6 Complex Person Condition

Service authors must check on the type of predicate that is meant for the person condition. An AttributePredicate is the default case.

24.3.6.3.7 Access

The Search service (as a caller) expects that the query's getPredicate() method likely returns an oracle.webcenter.search.ComplexPredicate that joins an oracle.webcenter.search.TextPredicate holding the keyword, and an oracle.webcenter.search.ComplexPredicate holding the date condition, and an oracle.webcenter.search.AttributePredicate holding the person condition.

24.3.6.3.8 Selectable Attributes

The following selectable attributes/columns should be supported by your search adapter in its search implementation:

  • Title (Required)

    For each resource returned, the Search service user interface can display the title column, if provided. It is strongly recommended that the title column comes with the QName AttributeConstants.DCMI_TITLE.

  • Resource ID (Required)

    For resources to communicate a unique identifier that allows the Search service to render a link to navigate to the resource view (or any declared views) of the service, the column with the name oracle.webcenter.search.AttributeConstants.DCMI_IDENTIFIER must be returned as one of the columns accessible from a row within the QueryResult<Row>.

    The Search service extracts the DCMI_IDENTIFIER column and feeds it into the resource viewer as the value of the resourceId parameter when the link is clicked.

    If your resource view (or any declared views) requires multiple columns in the primary key, then try to bundle all of them into a composite string value for the oracle.webcenter.search.AttributeConstants.DCMI_IDENTIFIER column. The Search service treats that opaquely and passes it to your resource view, within which it may deconstruct the string into the various parts of the primary key.

  • Resource Type

    For each resource returned, the Search service user interface can display the type column, if provided. The type column comes with the QName AttributeConstants.DCMI_TYPE. If the DCMI_TYPE column is not found, then the value of the DCMI_FORMAT column is used in its place. In your resource viewer, you can make use of the resource type to aid in the rendering of a resource.

  • Resource URL (in place of Resource ID)

    In the absence of an oracle.webcenter.search.AttributeConstants.DCMI_IDENTIFIER column, the Search service constructs the link from the value of the column specified by oracle.webcenter.search.AttributeConstants.DCMI_URI. With absolute URLs, the DCMI_URI can launch a link from the search results to the URL.

    This allows for services, such as the Documents service and the Page service, to invoke the browser plug-in to render various results link targets, instead of invoking a resource view.

  • Last Modified Date

    For each resource returned, the Search service user interface can display the last modified date column, if provided. To mirror the searchable attribute of the last modified date, it is important that users can see the last modified date as a returned column in the search result.

    For most users, the last modified date is more relevant than the creation date. To have better consistency between the searchable attributes and the selectable attributes (so that users know what date to search with after seeing some values in the columns), it is strongly recommended that service authors return AttributeConstants.DCMI_MODIFIED rather than AttributeConstants.DCMI_CREATED. The last modified date is of type java.util.Calendar.

  • Creator

    For each resource returned, the Search service user interface can display the creator and last modified by column, if provided. The search user interface combines them in the same column as a list of contributors for the found resource. The QNames to use are AttributeConstants.DCMI_CREATOR and AttributeConstants.WPSAPI_MODIFIED, respectively. The creator is of type java.lang.String.

  • Icon

    For each resource returned, the Search service user interface can display the icon column, if provided. The icon column comes with the QName AttributeConstants.WPSAPI_ICON_PATH and corresponds to a valid path to an icon file that is accessible in the class path. The icon path is of type java.lang.String.

  • Size

    For each resource returned, the Search service user interface can display the size column, if provided. The size column comes with the QName AttributeConstants.DCMI_EXTENT and corresponds to the size of the resource found. The size is of type java.lang.Number.

24.3.6.4 What Happens at Runtime

When you perform a search from the main view or toolbar, it should seamlessly include your new search source. For testing purposes, be sure to enter criteria that yields a result in your newly-added search source.

The Search service invokes a resource viewer using the Resource Action Handling framework. For information about registering a resource viewer to allow custom components to be found using Search, see Section 4.2, "Extending Your Application with Custom Components."

24.3.7 Troubleshooting the Search Service

This section describes common problems and solutions for the Search service.

Problem

There is a set timeout for querying each service. If a particular service does not return search results in the allotted time, then it times out. The Announcements and Discussions services are susceptible to timeouts. (In WebCenter Spaces, the Page service and Group Spaces could have timeouts from search execution.)

Solution

To improve performance at design time, you can increase the values (in milliseconds) of timeoutMs and prepare TimeoutMs in adf-config.xml. The following is the relevant fragment of adf-config.xml, found in the Application Resources panel in the ADF META-INF folder:

<execution-properties timeoutMs="3000"prepare TimeoutMs="1000"/>

At runtime, you can configure timeouts using WLST or Enterprise Manager.