Eclipse Platform Release 3.7

## 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 Summary
`SearchParticipant()`

Method Summary
`abstract IStatus` `addDocument(IHelpSearchIndex index, String pluginId, String name, URL url, String id, ISearchDocument doc)` Adds the document to the search index.
`protected void` `addTitle(String title, ISearchDocument doc)` A utility method that adds a title to the document.
`void` `clear()` Signals to the participant that the indexing operation has finished and that cached resources can be disposed to free up memory.
`Set` `getAllDocuments(String locale)` Returns all the documents that this participant knows about.
`Set` `getContributingPlugins()` Returns a set of identifiers of plug-ins that contribute indexable documents.
`String` `getId()` Returns the unique identifier of this participant.
`void` `init(String id)` Initializes the participant with the unique identifier from the registry.
`boolean` `open(String id)` Help system does not know how to open documents outside of the system's TOC.
`protected static String` `resolveVariables(String pluginId, String fileName, String locale)` A utility method that resolves a file name that contains '$'-based substitution variables.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### SearchParticipant

    public SearchParticipant()

Method Detail

### 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 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 hrefs for documents managed by this participant.

### getContributingPlugins

    public Set 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 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`).

Eclipse Platform Release 3.7

Guidelines for using Eclipse APIs.

Copyright (c) Eclipse contributors and others 2000, 2011. All rights reserved.