Package org.eclipse.help.search

Class SearchParticipant

java.lang.Object
org.eclipse.help.search.SearchParticipant
Direct Known Subclasses:
SearchParticipantXML
public abstract class SearchParticipant extends Object
Participant in the help search. A plug-in can contribute instance of SearchParticipant to "org.eclipse.help.search.searchParticipant" extension point. Search participant is responsible for adding the content of documents it is responsible for into the help system's search index. Once in the index, the document becomes searchable and can produce search hits. There are two ways of using the participant:
  1. For adding documents that are part of the help's TOC that have content formats not known to the default indexer (which are essentially all documents that are not of HTML format). In this case, the help system knows about the documents because they are in TOC but does not know how to index them. Because of the non-HTML format, help search participants are normally accompanied by the help content producers that are responsible for transforming the unknown format into HTML on the fly.

    When used in this mode, search participants must be registered with file extensions they handle. Based on the file extension mapping, they will be the first to get a chance at indexing the document with the matching extension.

  2. For adding documents that are outside of the help's TOC. In this case, the documents are completely unknown to the help system. Search participants are responsible for providing a set of documents they know about and are not supposed to declare file extensions they can handle. They are also responsible for opening these documents when asked because the help system will not be able to open them in any meaningful way.
Since:
3.5

  • Constructor Details

    • SearchParticipant

      public SearchParticipant()

  • Method Details

    • init

      public final void init(String id)
      Initializes the participant with the unique identifier from the registry. The method is called by the help system - subclasses are not supposed to call it.
      Parameters:
      id - the unique identifier of this participant

    • getId

      public final String getId()
      Returns the unique identifier of this participant.
      Returns:
      the unique id

    • addDocument

      public abstract IStatus addDocument(IHelpSearchIndex index, String pluginId, String name, URL url, String id, ISearchDocument doc)
      Adds the document to the search index.
      Parameters:
      index - the abstract representation of the help index that is currently running. Indexing known file types in participants that manage documents outside the TOC can be delegated to the index.
      pluginId - the plug-in that owns the document
      name - the name of the document to index
      url - the url of the document to index
      id - the unique id associated with this document
      doc - the document to add searchable content to
      Returns:
      the status of the indexing operation. A successful operation should return Status.OK.

    • getAllDocuments

      public Set<String> getAllDocuments(String locale)
      Returns all the documents that this participant knows about. This method is only used for participants that handle documents outside of the help system's TOC.
      Parameters:
      locale - the index locale
      Returns:
      a Set of String of hrefs for documents managed by this participant.

    • getContributingPlugins

      public Set<String> getContributingPlugins()
      Returns a set of identifiers of plug-ins that contribute indexable documents. This method is only used for participants that handle documents outside of the help system's TOC.
      Returns:
      a Set of String of contributing plug-in ids

    • resolveVariables

      protected static String resolveVariables(String pluginId, String fileName, String locale)
      A utility method that resolves a file name that contains '$'-based substitution variables.
      Parameters:
      pluginId - the identifier of the originating plug-in
      fileName - the source file name
      locale - the locale to use when resolving nl variable
      Returns:
      the plug-in relative file name with resolved variables

    • addTitle

      protected void addTitle(String title, ISearchDocument doc)
      A utility method that adds a title to the document.
      Parameters:
      title - the title string
      doc - the document

    • open

      public boolean open(String id)
      Help system does not know how to open documents outside of the system's TOC. Global search participants that bring additional documents into the index when getAllDocuments(String) have a chance to open the document when it is part of the search results. The default implementation returns false indicating that the help system should open the document. In most cases this is wrong for most of XML files that are in some interesting way.
      Parameters:
      id - a participant-specific identifier that completely represents a search result
      Returns:
      true if the file has been opened correctly or false to allow the help system to try to open the document.

    • clear

      public void clear()
      Signals to the participant that the indexing operation has finished and that cached resources can be disposed to free up memory. The participant itself is still kept around (hence this is semantically different from dispose).