11.6. Search Tutorial

11.6.1.1. Core search metadata

The first task is to implement the MetadataProvider.java interface, providing the core search metadata - the object's locale, title and summary blurb. All the methods in this interface have a DomainObject as the first argument. The object supplied as the value for this argument will be an instance (or subtype) of the object type specified when registering the provider with the MetadataProviderRegistry.

package com.example.binder;

import com.arsdigita.search.MetadataProvider;
import com.arsdigita.domain.DomainObject;
import com.arsdigita.util.StringUtils;

import java.util.Locale;

public class NoteMetadataProvider implements MetadataProvider {

     public Locale getLocale(DomainObject dobj) {
         Note note = (Note)dobj;
         // Note doesn't store the locale yet, so we just return null
         return null;
     }

     public String getTitle(DomainObject dobj) {
         Note note = (Note)dobj;
         return note.getTitle();
     }

     public String getSummary(DomainObject dobj) {
         Note note = (Note)dobj;
         // Truncate body text & remove any HTML.
         return StringUtils.truncateString(note.getBody(),
                                           200,
                                           true);
     }

     ...

11.6.1.2. Supplementary search metadata

The next set of optional methods allow for provision of auditing data that will be useful for narrowing search results, namely creation and modification date and the party who performed these two actions. This information can be trivially provided if the domain object already using com.arsdigita.auditing package:

    ...

    public Date getCreationDate(DomainObject dobj) {
         Note note = (Note)dobj;
         BasicAuditTrail audit = BasicAuditTrail.retrieveForACSObject(note);
         return audit == null ? null : audit.getCreationDate();
    }

    public Party getCreationParty(DomainObject dobj) {
         Note note = (Note)dobj;
         BasicAuditTrail audit = BasicAuditTrail.retrieveForACSObject(note);
         return audit == null ? null : audit.getCreationParty();
    }

    public Date getLastMofidiedDate(DomainObject dobj) {
         Note note = (Note)dobj;
         BasicAuditTrail audit = BasicAuditTrail.retrieveForACSObject(note);
         return audit == null ? null : audit.getLastModifiedDate();
    }

    public Party getLastMofidiedParty(DomainObject dobj) {
         Note note = (Note)dobj;
         BasicAuditTrail audit = BasicAuditTrail.retrieveForACSObject(note);
         return audit == null ? null : audit.getLastModifiedParty();
    }

    ...

11.6.1.3. Content provision

The remaining method to be implemented in the MetadataProvider interface is the one that actually provides the searchable content. There are currently three formats in which searchable content can be provided, each of which are identified by a static constant in the com.arsdigita.search.ContentType class. Each search indexer will support a different set of formats, so applications should implement as many formats as make sense.

• TEXT - plain text, with no markup. Equivalent to text/plain mime type.

• RAW - an arbitrary document format such as HTML, OpenOffice, PDF, RTF. The indexer will auto detect which format and extract content for building the search index.

• XML - a well formed XML document containing arbitrary elements. The indexer will extract content from the elements, keeping track of its XPath, enabling searches to be restricted by element name.

The Lucene implementation in WAF supports the text content type, and InterMedia supports the RAW and XML formats. The ContentProvider interface defines the API for providing content. The Note object allows its body text attribute to store HTML, so there can be two implements of ContentProvider, one for TEXT, and the other for HTML. These are typically written as package private, inner classes of the MetadataProvider implementation

    ...

    class TextContentProvider implements ContentProvider {
        privte Note m_note;

        public TextContentProvider(Note note) {
          m_note = note;
        }

        public String getTag() {
          return "Body Text";
        }

        public ContentType getType() {
          return ContentType.TEXT;
        }

        public byte[] getBytes() {
          String body = m_note.getBody();
          // Strip out html tags
          return StringUtils.htmlToText(body).getBytes();
        }
    }

    ....

    ...

    class HTMLContentProvider implements ContentProvider {
        privte Note m_note;

        public HTMLContentProvider(Note note) {
          m_note = note;
        }

        public String getTag() {
          return "Body Text";
        }

        public ContentType getType() {
          return ContentType.RAW;
        }

        public byte[] getBytes() {
          String body = m_note.getBody();
          // Wrap the body HTML in a header and footer
          return ("<html><head><title>" + 
            m_note.getTitle() + 
            "</title></head><body>" +
            body + 
            "</body></html>").getBytes();
        }
    }

    ...

Finally to the getContent method in the MetadataProvider interface is used to wire in the supported ContentProvider implementations. This method returns an array of ContentProvider objects for each type, for example, allowing an object which '0..n' file attachments to return each file as raw content.

         ...

    public ContentProvider[] getContent(DomainObject dobj,
                                        ContentType type) {
        Note note = (Note)dobj;
        
        if (type == ContentType.TEXT) {
          return new ContentProvider[] {
             new TextContentProvider(note)
          };
        } else if (type == ContentType.RAW) {
          return new ContentProvider[] {
             new HTMLContentProvider(note)
          };
        } else {
          return null;
        }
    }

11.6.1.4. Metadata provider registration

The search service maintains a registry of which metadata provider adapters to use for each object type. To activate searching of the Note domain object, its adapter must be registered. The registration process is typically done upon startup from the init(DomainInitEvent e) method of com.arsdigita.runtime.Initializer. When determining which adapter to use for extracting metadata, the search service will travel up the object type inheritance tree until it finds a registered adapter. Thus if an application has a number of object types all inheriting from a common parent, it may be sufficient to register the metadata provider against the parent type.

package com.example.binder;

import com.arsdigita.runtime.CompoundInitializer;
import com.arsdigita.runtime.DomainInitEvent;

import com.arsdigita.search.MetadataProviderRegistry;

public class NoteInitializer extends CompoundInitializer {

    public void init(DomainInitEvent evt) {
        super.init(evt);

        MetadataProviderRegistry.registerAdapter(
           Note.BASE_DATA_OBJECT_TYPE,
           new NoteMetadataProvider());
    }
}

11.6.2.1. Basic search form

The first step in building a search form is to create a form containing a text entry widget for the query string. The QueryComponent class is a general purpose, abstract Bebop container implementing the QueryGenerator interface. This interface provides a mechanism for retrieving a query specification using the current page state without requiring any knowledge about the structure of the data entry form (for that matter, there might not be any form at all!).

The BaseQueryComponent class is a simple subclass of QueryComponent providing a widget for specifying the query string and APIs for adding filter components (more on these later). This is the component to start with when creating a search UI for an application. The only pre-requisite is that is be contained within a Bebop form.

       QueryComponent query = new BaseQueryComponent();

       Form form = new Form("search");
       form.add(m_query):
       form.add(new Submit("Search notes"));

       add(m_query);

11.6.2.2. Displaying results

The next stage is to add functionality for processing the query specification and displaying the results. The ResultsPane takes care of both of these tasks, only requiring an implementation of the QueryGenerator interface be passed into its constructor, which of course is already fulfilled by the QueryComponent class.

       ResultPane results = new ResultPane(query);
       add(results);

11.6.2.3. Filtering results

Since search is a system wide service, the result of the previous stage is a component that searches every single object type for which there is a search metadata provider registered. For internal application search, a filter is required to restrict results to one or more object types. There is a choice of two classes that can be used for this task, both part of the com.arsdigita.search.ui.filters package.

• ObjectTypeFilterComponent a static component that restricts to the list of object types passed into its constructor.

• ObjectTypeFilterWidget a dynamic widget that presents the list of object types passed into its constructor in a form, enabling the user to restrict the search.

For the binder application, there is only a single object type, Note, so the ObjectTypeComponent is most appropriate.

       FilterComponent objTypeFilter = 
          new ObjectTypeFilterComponent(Note.BASE_DATA_OBJECT_TYPE));
       query.add(objTypeFilter);

11.6.2.4. Note search component

These three stages now all combine to form a NoteSearchComponent that can be dropped into pages in the Binder application (or indeed any other application wishing to Note objects.

package com.example.binder.ui;

import com.example.binder.Note;

import com.arsdigita.search.ui.BaseQueryComponent;
import com.arsdigita.search.ui.QueryComponent;
import com.arsdigita.search.ui.ResultPane;
import com.arsdigita.search.ui.FilterComponent;
import com.arsdigita.search.ui.ObjectTypeFilterComponent;

import com.arsdigita.bebop.Form;
import com.arsdigita.bebop.SimpleContainer;

import com.arsdigita.bebop.form.Submit;

public class NoteSearhComponent extends SimpleContainer {

    private QueryComponent m_query;
    private FilterComponent m_typeFilter;
    private ResultsPane m_results;

    public NoteSearchComponent() {
       super("note:search", Note.XML_NS);

       m_typeFilter = new ObjectTypeFilterComponent(Note.BASE_DATA_OBJECT_TYPE);
       m_query = new BaseQueryComponent();
       m_query.add(m_typeFilter);

       m_results = new ResultsPane(m_query);

       Form form = new Form("search");
       form.add(m_query):
       form.add(new Submit("Search notes"));

       add(m_query);
       add(m_results);
    }
}