Your browser does not support JavaScript and this site utilizes JavaScript to build content and provide links to additional information. You should either enable JavaScript in your browser settings or use a browser that supports JavaScript in order to take full advantage of this site.

1 /*******************************************************************************2 * Copyright (c) 2006, 2007 IBM Corporation and others.3 * All rights reserved. This program and the accompanying materials4 * are made available under the terms of the Eclipse Public License v1.05 * which accompanies this distribution, and is available at6 * http://www.eclipse.org/legal/epl-v10.html7 *8 * Contributors:9 * IBM Corporation - initial API and implementation10 *******************************************************************************/11 package org.eclipse.help.search;12 13 importjava.net.URL;14 importjava.util.ArrayList;15 importjava.util.HashSet;16 importjava.util.Set;17 18 importorg.apache.lucene.document.Document;19 importorg.apache.lucene.document.Field;20 importorg.eclipse.core.runtime.FileLocator;21 importorg.eclipse.core.runtime.IStatus;22 importorg.eclipse.core.runtime.Path;23 importorg.eclipse.core.runtime.Platform;24 importorg.eclipse.help.internal.util.ResourceLocator;25 importorg.osgi.framework.Bundle;26 27 /**28 * Participant in the help search. A plug-in can contribute instance of LuceneSearchParticipant to29 * <code>"org.eclipse.help.search.luceneSearchParticipant"</code> extension point. Search30 * participant is responsible for adding the content of documents it is responsible for into the31 * help system's search index. Once in the index, the document becomes searchable and can produce32 * search hits. There are two ways of using the participant:33 * <ol>34 * <li> For adding documents that are part of the help's TOC that have content formats not known to35 * the default indexer (which are essentially all documents that are not of HTML format). In this36 * case, the help system knows about the documents because they are in TOC but does not know how to37 * index them. Because of the non-HTML format, help search participants are normally accompanied by38 * the help content producers that are responsible for transforming the unknown format into HTML on39 * the fly. <br>40 * <br>41 * When used in this mode, search participants must be registered with file extensions they handle.42 * Based on the file extension mapping, they will be the first to get a chance at indexing the43 * document with the matching extension.<br>44 * <br>45 * </li>46 * <li> For adding documents that are outside of the help's TOC. In this case, the documents are47 * completely unknown to the help system. Search participants are responsible for providing a set of48 * documents they know about and are not supposed to declare file extensions they can handle. They49 * are also responsible for opening these documents when asked because the help system will not be50 * able to open them in any meaningful way. </li>51 * </ol>52 * 53 * @since 3.254 */55 publicabstractclass LuceneSearchParticipant {56 57 privatestaticfinalHashSet EMPTY_SET = newHashSet();58 59 privateString id;60 61 /**62 * Initializes the participant with the unique identifier from the registry. The method is63 * called by the help system - subclasses are not supposed to call it.64 * 65 * @param id66 * the unique identifier of this participant67 */68 69 publicfinalvoid init(String id) {70 this.id = id;71 }72 73 /**74 * Returns the unique identifier of this participant.75 * 76 * @return the unique id77 */78 publicString getId() {79 return id;80 }81 82 /**83 * Adds the document to the search index.84 * 85 * @param index86 * the abstract representation of the help index that is currently running. Indexing87 * known file types in participants that manage documents outside the TOC can be88 * delegated to the index.89 * @param pluginId90 * the plug-in that owns the document91 * @param name92 * the name of the document to index93 * @param url94 * the url of the document to index95 * @param id96 * the unique id associated with this document97 * @param doc98 * the Lucene document to add searchable content to99 * @return the status of the indexing operation. A successful operation should return100 * <code>Status.OK</code>.101 */102 publicabstractIStatus addDocument(ISearchIndex index, String pluginId, String name, URL url, String id,103 Document doc);104 105 /**106 * Returns all the documents that this participant knows about. This method is only used for107 * participants that handle documents outside of the help system's TOC.108 * 109 * @param locale110 * the index locale111 * 112 * @return a set of hrefs for documents managed by this participant.113 */114 publicSet getAllDocuments(String locale) {115 return EMPTY_SET;116 }117 118 /**119 * Returns a set of identifiers of plug-ins that contribute indexable documents. This method is120 * only used for participants that handle documents outside of the help system's TOC.121 * 122 * @return a set of contributing plug-in ids123 */124 125 publicSet getContributingPlugins() {126 return EMPTY_SET;127 }128 129 /**130 * A utility method that resolves a file name that contains '$'-based substitution variables.131 * 132 * @param pluginId133 * the identifier of the originating plug-in134 * @param fileName135 * the source file name136 * @param locale137 * the locale to use when resolving nl variable138 * @return the plug-in relative file name with resolved variables139 */140 141 protectedstaticString resolveVariables(String pluginId, String fileName, String locale) {142 if (fileName.indexOf('$') == -1)143 return fileName;144 ArrayList prefix = ResourceLocator.getPathPrefix(locale);145 Bundle bundle = Platform.getBundle(pluginId);146 if (bundle == null)147 return fileName;148 URL url = ResourceLocator.find(bundle, newPath(fileName), prefix);149 URL root = FileLocator.find(bundle, newPath(""), null); //$NON-NLS-1$150 return url.toString().substring(root.toString().length());151 }152 153 /**154 * A utility method that adds a document title to the Lucene document.155 * 156 * @param title157 * the title string158 * @param doc159 * the Lucene document160 */161 162 protectedvoid addTitle(String title, Document doc) {163 doc.add(newField("title", title, Field.Store.NO, Field.Index.TOKENIZED)); //$NON-NLS-1$164 doc.add(newField("exact_title", title, Field.Store.NO, Field.Index.TOKENIZED)); //$NON-NLS-1$165 doc.add(newField("raw_title", title, Field.Store.YES, Field.Index.NO)); //$NON-NLS-1$166 }167 168 /**169 * Help system does not know how to open documents outside of the system's TOC. Global search170 * participants that bring additional documents into the index when171 * <code>getAllDocuments(String)</code> have a chance to open the document when it is part of172 * the search results. The default implementation returns <code>false</code> indicating that173 * the help system should open the document. In most cases this is wrong for most of XML files174 * that are in some interesting way.175 * 176 * @param id177 * a participant-specific identifier that completely represents a search result178 * 179 * @return <code>true</code> if the file has been opened correctly or <code>false</code> to180 * allow the help system to try to open the document.181 */182 183 publicboolean open(String id) {184 returnfalse;185 }186 187 /**188 * Signals to the participant that the indexing operation has finished and that cached resources189 * can be disposed to free up memory. The participant itself is still kept around (hence this is190 * semantically different from <code>dispose</code>).191 */192 publicvoid clear() {193 }194 }195