01: /*
02: * Copyright 2004-2006 the original author or authors.
03: *
04: * Licensed under the Apache License, Version 2.0 (the "License");
05: * you may not use this file except in compliance with the License.
06: * You may obtain a copy of the License at
07: *
08: * http://www.apache.org/licenses/LICENSE-2.0
09: *
10: * Unless required by applicable law or agreed to in writing, software
11: * distributed under the License is distributed on an "AS IS" BASIS,
12: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13: * See the License for the specific language governing permissions and
14: * limitations under the License.
15: */
16:
17: package org.compass.core;
18:
19: /**
20: * Holds hits returned from a search performed by compass. Can be used within a
21: * transaction context. For hits to be used outside of a transactional context,
22: * the {@link #detach()} and {@link #detach(int, int)} can be used.
23: * <p/>
24: * Also allows for highlighting using {@link #highlighter(int)}, and any highlighting
25: * operation (that returns a single <code>String</code>) will be cached within the
26: * hits (and also moved to the detached hits, if {@link #detach(int, int)} is called),
27: * and can be used by {@link CompassHitsOperations#highlightedText(int)}.
28: *
29: * @author kimchy
30: */
31: public interface CompassHits extends CompassHitsOperations {
32:
33: /**
34: * Detaches a seperate <code>CompassHits</code>, holds all the data. The
35: * detached hits preloads all the data, so it can be used outside of a
36: * transaction. NOTE: Be carefull when using the method, since it will take
37: * LONG time to load a large hits result set.
38: *
39: * @return A detached hits.
40: * @throws CompassException
41: */
42: CompassDetachedHits detach() throws CompassException;
43:
44: /**
45: * Detaches a seperate <code>CompassHits</code>, which starts from the
46: * given from parameter, and has the specified size. The detached hits
47: * preloads all the data, so it can be used outside of a transaction.
48: *
49: * @param from The index that the sub hits starts from.
50: * @param size The size of the sub hits.
51: * @return A detached sub hits.
52: * @throws CompassException
53: */
54: CompassDetachedHits detach(int from, int size)
55: throws CompassException, IllegalArgumentException;
56:
57: /**
58: * Returns the highlighter that maps the n'th hit.
59: * <p/>
60: * Note, that any highlighting operation (that returns a single <code>String</code>)
61: * will be cached within the hits (and also moved to the detached hits, if
62: * {@link #detach(int, int)} is called), and can be used by
63: * {@link CompassHitsOperations#highlightedText(int)}.
64: *
65: * @param n The n'th hit.
66: * @return The highlighter.
67: * @throws CompassException
68: */
69: CompassHighlighter highlighter(int n) throws CompassException;
70:
71: /**
72: * Closes the hits object. Note that it is an optional operation since it
73: * will be closed transperantly when the transaction is closed.
74: * <p/>
75: * It is provided for more controlled resource management
76: *
77: * @throws CompassException
78: */
79: void close() throws CompassException;
80: }
|