001: /*
002: * Copyright 2004-2006 the original author or authors.
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016:
017: package org.compass.core;
018:
019: import org.compass.core.util.Parameter;
020:
021: /**
022: * A highlighter tool that can highlight hits in a given text based on an
023: * executed query.
024: *
025: * @see org.compass.core.CompassHits#highlighter(int)
026: *
027: * @author kimchy
028: */
029: public interface CompassHighlighter {
030:
031: /**
032: * Controls the way text will be tokenized in order to perform the highlight
033: * operation.
034: *
035: * @author kimchy
036: */
037: public static final class TextTokenizer extends Parameter {
038:
039: private static final long serialVersionUID = -2884363380650216389L;
040:
041: private TextTokenizer(String name) {
042: super (name);
043: }
044:
045: /** Forces tokenization of the text using the analyzer. */
046: public static final TextTokenizer ANALYZER = new TextTokenizer(
047: "ANALYZER");
048:
049: /** Forces tokenization of the text using the tem vector information. */
050: public static final TextTokenizer TERM_VECTOR = new TextTokenizer(
051: "TERM_VECTOR");
052:
053: /**
054: * Will use term vector if available to tokenize the text, otherwise
055: * will use analyzer.
056: */
057: public static final TextTokenizer AUTO = new TextTokenizer(
058: "AUTO");
059:
060: public static String toString(TextTokenizer textTokenizer) {
061: if (textTokenizer == CompassHighlighter.TextTokenizer.ANALYZER) {
062: return "analyzer";
063: } else if (textTokenizer == CompassHighlighter.TextTokenizer.TERM_VECTOR) {
064: return "term_vector";
065: } else if (textTokenizer == CompassHighlighter.TextTokenizer.AUTO) {
066: return "auto";
067: }
068: throw new IllegalArgumentException(
069: "Can't find text tokenizer for [" + textTokenizer
070: + "]");
071: }
072:
073: public static CompassHighlighter.TextTokenizer fromString(
074: String textTokenizer) {
075: if ("analyzer".equalsIgnoreCase(textTokenizer)) {
076: return CompassHighlighter.TextTokenizer.ANALYZER;
077: } else if ("term_vector".equalsIgnoreCase(textTokenizer)) {
078: return CompassHighlighter.TextTokenizer.TERM_VECTOR;
079: } else if ("auto".equalsIgnoreCase(textTokenizer)) {
080: return CompassHighlighter.TextTokenizer.AUTO;
081: }
082: throw new IllegalArgumentException(
083: "Can't find text tokenizer for [" + textTokenizer
084: + "]");
085: }
086: }
087:
088: /**
089: * Sets the highlighter that will be used out the ones set in the
090: * configuration. The highlighters are groups of pre-set configurations for
091: * the sepcified highlighter. The default one is called <code>default</code>.
092: *
093: * @param highlighterName
094: * The name of the highlighter that will be used
095: * @return the higlighter
096: * @throws CompassException
097: */
098: CompassHighlighter setHighlighter(String highlighterName)
099: throws CompassException;
100:
101: /**
102: * Sets the analyzer that will be used if analysis of the text is needed
103: * (see {@link TextTokenizer}).
104: *
105: * @param analyzerName
106: * The analyzer name that will be used.
107: * @return the highlighter
108: * @throws CompassException
109: */
110: CompassHighlighter setAnalyzer(String analyzerName)
111: throws CompassException;
112:
113: /**
114: * Sets the analyzer that will be used if analysis of the text is needed
115: * (see {@link TextTokenizer}). Uses the resource to derive the analyzer
116: * that will be used (works also with per resource property analyzer).
117: *
118: * @param resource The resource to derive the analyzer from
119: * @return the highlighter
120: * @throws CompassException
121: */
122: CompassHighlighter setAnalyzer(Resource resource)
123: throws CompassException;
124:
125: /**
126: * Sets the separator string that will be used to combine different
127: * fragments in {@link #fragmentsWithSeparator(String)}. If not set, will
128: * use the separator configured for the chosen highlighter.
129: *
130: * @param separator
131: * The separator used
132: * @return the highlighter
133: * @throws CompassException
134: */
135: CompassHighlighter setSeparator(String separator)
136: throws CompassException;
137:
138: /**
139: * Sets the maximum number of bytes that will be analyzed for highlighting.
140: * If not set, will use the value configured for the chosen highlighter.
141: *
142: * @param maxBytesToAnalyze
143: * The maximum number of bytes analyzed for highlighting
144: * @return the highlighter
145: * @throws CompassException
146: */
147: CompassHighlighter setMaxBytesToAnalyze(int maxBytesToAnalyze)
148: throws CompassException;
149:
150: /**
151: * Sets the maximum number of fragments that can be returned or combined to
152: * a separator. If not set, will use the value configured for the chosen
153: * highlighter.
154: *
155: * @param maxNumFragments
156: * The maximum number if fragments
157: * @return the highlighter
158: * @throws CompassException
159: */
160: CompassHighlighter setMaxNumFragments(int maxNumFragments)
161: throws CompassException;
162:
163: /**
164: * Sets how the text will be tokenized for highlighting. If not set, will
165: * use the value configured for the chosen highlighter.
166: *
167: * @param textTokenizer
168: * How the text will be tokenized for highlighting
169: * @return the highlighter
170: * @throws CompassException
171: */
172: CompassHighlighter setTextTokenizer(
173: CompassHighlighter.TextTokenizer textTokenizer)
174: throws CompassException;
175:
176: /**
177: * Returns the best highlighted fragment for the given property name /
178: * meta-data. The highlighted text will be retrived from the index, so it
179: * must be stored.
180: * <p>
181: * Note, if there are more than one resource property name / meta-data with
182: * the same name, the text will be taken from the first one.
183: * <p>
184: * The name can either be the actual resource property or meta-data value,
185: * or the path to the given resource property (alias.rProperty), or the
186: * class property (alias.cProperty) or the path to the meta-data
187: * (alias.cProperty.metaData)
188: *
189: * @param propertyName
190: * The resource property name / meta-data.
191: * @return The best fragment text highlighted.
192: * @throws CompassException
193: */
194: String fragment(String propertyName) throws CompassException;
195:
196: /**
197: * Returns the best highlighted fragment for the given property name /
198: * meta-data. The given text will be used for highlight. Handy when the text
199: * is not stored in the index.
200: * <p>
201: * The name can either be the actual resource property or meta-data value,
202: * or the path to the given resource property (alias.rProperty), or the
203: * class property (alias.cProperty) or the path to the meta-data
204: * (alias.cProperty.metaData)
205: *
206: * @param propertyName
207: * The resource property name / meta-data.
208: * @param text
209: * The text to be highlighted.
210: * @return The best fragment text highlighted.
211: * @throws CompassException
212: */
213: String fragment(String propertyName, String text)
214: throws CompassException;
215:
216: /**
217: * Returns the best highlighted fragments for the given property name /
218: * meta-data. The highlighted text will be retrived from the index, so it
219: * must be stored.
220: * <p>
221: * Note, that the number of fragments will be between <code>0</code> and
222: * <code>maxNumFragments</code>.
223: * <p>
224: * Note, if there are more than one resource property name / meta-data with
225: * the same name, the text will be taken from the first one.
226: * <p>
227: * The name can either be the actual resource property or meta-data value,
228: * or the path to the given resource property (alias.rProperty), or the
229: * class property (alias.cProperty) or the path to the meta-data
230: * (alias.cProperty.metaData)
231: *
232: * @param propertyName
233: * The resource property name / meta-data.
234: * @return The best fragments highlighted.
235: * @throws CompassException
236: */
237: String[] fragments(String propertyName) throws CompassException;
238:
239: /**
240: * Returns the best highlighted fragments for the given property name /
241: * meta-data. The given text will be used for highlight.
242: * <p>
243: * Note, that the number of fragments will be between <code>0</code> and
244: * <code>maxNumFragments</code>.
245: * <p>
246: * The name can either be the actual resource property or meta-data value,
247: * or the path to the given resource property (alias.rProperty), or the
248: * class property (alias.cProperty) or the path to the meta-data
249: * (alias.cProperty.metaData)
250: *
251: * @param propertyName
252: * The resource property name / meta-data.
253: * @param text
254: * The text to be highlighted.
255: * @return The best fragments highlighted.
256: * @throws CompassException
257: */
258: String[] fragments(String propertyName, String text)
259: throws CompassException;
260:
261: /**
262: * Returns the best highlighted fragments for the given property name /
263: * meta-data, separated with the given separator. The highlighted text will
264: * be retrived from the index, so it must be stored.
265: * <p>
266: * Note, that the number of fragments will be between <code>0</code> and
267: * <code>maxNumFragments</code>.
268: * <p>
269: * Note, if there are more than one resource property name / meta-data with
270: * the same name, the text will be taken from the first one.
271: * <p>
272: * The name can either be the actual resource property or meta-data value,
273: * or the path to the given resource property (alias.rProperty), or the
274: * class property (alias.cProperty) or the path to the meta-data
275: * (alias.cProperty.metaData)
276: *
277: * @param propertyName
278: * The resource property name / meta-data.
279: * @return The best fragments highlighted and separated.
280: * @throws CompassException
281: */
282: String fragmentsWithSeparator(String propertyName)
283: throws CompassException;
284:
285: /**
286: * Returns the best highlighted fragments for the given property name /
287: * meta-data, separated with the given separator. The given text will be
288: * used for highlight.
289: * <p>
290: * Note, that the number of fragments will be between <code>0</code> and
291: * <code>maxNumFragments</code>.
292: * <p>
293: * The name can either be the actual resource property or meta-data value,
294: * or the path to the given resource property (alias.rProperty), or the
295: * class property (alias.cProperty) or the path to the meta-data
296: * (alias.cProperty.metaData)
297: *
298: * @param propertyName
299: * The resource property name / meta-data.
300: * @param text
301: * The text to be highlighted.
302: * @return The best fragments highlighted and separated.
303: * @throws CompassException
304: */
305: String fragmentsWithSeparator(String propertyName, String text)
306: throws CompassException;
307:
308: /**
309: * Returns the best highlighted fragment of each matching <i>multi</i> resource
310: * property name / meta-data (i.e.: when there is more then one property of the
311: * same name). The highlighted texts will be retrived from the index, so it must
312: * be stored.
313: * <p>
314: * Note, that the number of returned fragments is not limited by
315: * <code>maxNumFragments</code> value.
316: * <p>
317: * The name can either be the actual resource property or meta-data value,
318: * or the path to the given resource property (alias.rProperty), or the
319: * class property (alias.cProperty) or the path to the meta-data
320: * (alias.cProperty.metaData)
321: *
322: * @param propertyName
323: * The resource property name / meta-data.
324: * @return The best fragment texts highlighted.
325: * @throws CompassException
326: */
327: String[] multiResourceFragment(String propertyName)
328: throws CompassException;
329:
330: /**
331: * Returns the best highlighted fragment of each matching <i>multi</ib> resource
332: * property name / meta-data (i.e.: when there is more then one property of the
333: * same name). The given texts will be used for highlight. Handy when the texts
334: * are not stored in the index.
335: * <p>
336: * Note, that the number of returned fragments is not limited by
337: * <code>maxNumFragments</code> value.
338: * <p>
339: * The name can either be the actual resource property or meta-data value,
340: * or the path to the given resource property (alias.rProperty), or the
341: * class property (alias.cProperty) or the path to the meta-data
342: * (alias.cProperty.metaData)
343: *
344: * @param propertyName
345: * The resource property name / meta-data.
346: * @param texts
347: * Texts to be highlighted.
348: * @return The best fragment texts highlighted.
349: * @throws CompassException
350: */
351: String[] multiResourceFragment(String propertyName, String[] texts)
352: throws CompassException;
353:
354: /**
355: * Returns the best highlighted fragments for the given <i>multi</i> property
356: * name / meta-data, separated with the given separator. The highlighted text
357: * will be retrived from the index, so it must be stored.
358: * <p>
359: * Note, that the number of separeted fragments is not
360: * limited by <code>maxNumFragments</code> value.
361: * <p>
362: * The name can either be the actual resource property or meta-data value,
363: * or the path to the given resource property (alias.rProperty), or the
364: * class property (alias.cProperty) or the path to the meta-data
365: * (alias.cProperty.metaData)
366: *
367: * @param propertyName
368: * The resource property name / meta-data.
369: * @return The best fragments highlighted and separated.
370: * @throws CompassException
371: */
372: String multiResourceFragmentWithSeparator(String propertyName)
373: throws CompassException;
374:
375: /**
376: * Returns the best highlighted fragments for the given <i>multi</i> property
377: * name / meta-data, separated with the given separator. The given texts will
378: * be used for highlight.
379: * <p>
380: * Note, that the number of fragments contained in returned string is not
381: * limited by <code>maxNumFragments</code> value.
382: * <p>
383: * The name can either be the actual resource property or meta-data value,
384: * or the path to the given resource property (alias.rProperty), or the
385: * class property (alias.cProperty) or the path to the meta-data
386: * (alias.cProperty.metaData)
387: *
388: * @param propertyName
389: * The resource property name / meta-data.
390: * @param texts
391: * Texts to be highlighted.
392: * @return The best fragments highlighted and separated.
393: * @throws CompassException
394: */
395: String multiResourceFragmentWithSeparator(String propertyName,
396: String[] texts) throws CompassException;
397:
398: }
|