KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > help > search > LuceneSearchParticipant


1 /*******************************************************************************
2  * Copyright (c) 2006, 2007 IBM Corporation and others.
3  * All rights reserved. This program and the accompanying materials
4  * are made available under the terms of the Eclipse Public License v1.0
5  * which accompanies this distribution, and is available at
6  * http://www.eclipse.org/legal/epl-v10.html
7  *
8  * Contributors:
9  * IBM Corporation - initial API and implementation
10  *******************************************************************************/
11 package org.eclipse.help.search;
12
13 import java.net.URL JavaDoc;
14 import java.util.ArrayList JavaDoc;
15 import java.util.HashSet JavaDoc;
16 import java.util.Set JavaDoc;
17
18 import org.apache.lucene.document.Document;
19 import org.apache.lucene.document.Field;
20 import org.eclipse.core.runtime.FileLocator;
21 import org.eclipse.core.runtime.IStatus;
22 import org.eclipse.core.runtime.Path;
23 import org.eclipse.core.runtime.Platform;
24 import org.eclipse.help.internal.util.ResourceLocator;
25 import org.osgi.framework.Bundle;
26
27 /**
28  * Participant in the help search. A plug-in can contribute instance of LuceneSearchParticipant to
29  * <code>"org.eclipse.help.search.luceneSearchParticipant"</code> extension point. Search
30  * participant is responsible for adding the content of documents it is responsible for into the
31  * help system's search index. Once in the index, the document becomes searchable and can produce
32  * 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 to
35  * the default indexer (which are essentially all documents that are not of HTML format). In this
36  * case, the help system knows about the documents because they are in TOC but does not know how to
37  * index them. Because of the non-HTML format, help search participants are normally accompanied by
38  * the help content producers that are responsible for transforming the unknown format into HTML on
39  * 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 the
43  * 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 are
47  * completely unknown to the help system. Search participants are responsible for providing a set of
48  * documents they know about and are not supposed to declare file extensions they can handle. They
49  * are also responsible for opening these documents when asked because the help system will not be
50  * able to open them in any meaningful way. </li>
51  * </ol>
52  *
53  * @since 3.2
54  */
55 public abstract class LuceneSearchParticipant {
56
57     private static final HashSet JavaDoc EMPTY_SET = new HashSet JavaDoc();
58
59     private String JavaDoc id;
60
61     /**
62      * Initializes the participant with the unique identifier from the registry. The method is
63      * called by the help system - subclasses are not supposed to call it.
64      *
65      * @param id
66      * the unique identifier of this participant
67      */
68
69     public final void init(String JavaDoc id) {
70             this.id = id;
71     }
72
73     /**
74      * Returns the unique identifier of this participant.
75      *
76      * @return the unique id
77      */
78     public String JavaDoc getId() {
79         return id;
80     }
81
82     /**
83      * Adds the document to the search index.
84      *
85      * @param index
86      * the abstract representation of the help index that is currently running. Indexing
87      * known file types in participants that manage documents outside the TOC can be
88      * delegated to the index.
89      * @param pluginId
90      * the plug-in that owns the document
91      * @param name
92      * the name of the document to index
93      * @param url
94      * the url of the document to index
95      * @param id
96      * the unique id associated with this document
97      * @param doc
98      * the Lucene document to add searchable content to
99      * @return the status of the indexing operation. A successful operation should return
100      * <code>Status.OK</code>.
101      */
102     public abstract IStatus addDocument(ISearchIndex index, String JavaDoc pluginId, String JavaDoc name, URL JavaDoc url, String JavaDoc id,
103             Document doc);
104
105     /**
106      * Returns all the documents that this participant knows about. This method is only used for
107      * participants that handle documents outside of the help system's TOC.
108      *
109      * @param locale
110      * the index locale
111      *
112      * @return a set of hrefs for documents managed by this participant.
113      */
114     public Set JavaDoc getAllDocuments(String JavaDoc locale) {
115         return EMPTY_SET;
116     }
117
118     /**
119      * Returns a set of identifiers of plug-ins that contribute indexable documents. This method is
120      * only used for participants that handle documents outside of the help system's TOC.
121      *
122      * @return a set of contributing plug-in ids
123      */
124
125     public Set JavaDoc 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 pluginId
133      * the identifier of the originating plug-in
134      * @param fileName
135      * the source file name
136      * @param locale
137      * the locale to use when resolving nl variable
138      * @return the plug-in relative file name with resolved variables
139      */
140
141     protected static String JavaDoc resolveVariables(String JavaDoc pluginId, String JavaDoc fileName, String JavaDoc locale) {
142         if (fileName.indexOf('$') == -1)
143             return fileName;
144         ArrayList JavaDoc prefix = ResourceLocator.getPathPrefix(locale);
145         Bundle bundle = Platform.getBundle(pluginId);
146         if (bundle == null)
147             return fileName;
148         URL JavaDoc url = ResourceLocator.find(bundle, new Path(fileName), prefix);
149         URL JavaDoc root = FileLocator.find(bundle, new Path(""), 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 title
157      * the title string
158      * @param doc
159      * the Lucene document
160      */
161
162     protected void addTitle(String JavaDoc title, Document doc) {
163         doc.add(new Field("title", title, Field.Store.NO, Field.Index.TOKENIZED)); //$NON-NLS-1$
164 doc.add(new Field("exact_title", title, Field.Store.NO, Field.Index.TOKENIZED)); //$NON-NLS-1$
165 doc.add(new Field("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 search
170      * participants that bring additional documents into the index when
171      * <code>getAllDocuments(String)</code> have a chance to open the document when it is part of
172      * the search results. The default implementation returns <code>false</code> indicating that
173      * the help system should open the document. In most cases this is wrong for most of XML files
174      * that are in some interesting way.
175      *
176      * @param id
177      * a participant-specific identifier that completely represents a search result
178      *
179      * @return <code>true</code> if the file has been opened correctly or <code>false</code> to
180      * allow the help system to try to open the document.
181      */
182
183     public boolean open(String JavaDoc id) {
184         return false;
185     }
186
187     /**
188      * Signals to the participant that the indexing operation has finished and that cached resources
189      * can be disposed to free up memory. The participant itself is still kept around (hence this is
190      * semantically different from <code>dispose</code>).
191      */
192     public void clear() {
193     }
194 }
195
Popular Tags