1 package com.atlassian.bonnie;
2
3 import java.io.IOException;
4
5 import org.apache.lucene.document.Document;
6 import org.apache.lucene.index.IndexReader;
7 import org.apache.lucene.index.IndexWriter;
8 import org.apache.lucene.search.IndexSearcher;
9
10 /**
11 * A connection to a Lucene index. Supports reads, writes, searches, batch updates, and truncates.
12 */
13 public interface ILuceneConnection
14 {
15 public interface SearcherAction
16 {
17 /**
18 * Perform search. The searcher is managed which means you must not
19 * close the searcher.
20 */
21 public void perform(IndexSearcher searcher) throws IOException;
22 }
23
24 public interface ReaderAction
25 {
26 /**
27 * Perform index reading.
28 */
29 public Object perform(IndexReader reader) throws IOException;
30 }
31
32 public interface WriterAction
33 {
34 /**
35 * Perform index writing.
36 */
37 public void perform(IndexWriter writer) throws IOException;
38 }
39
40 public interface BatchUpdateAction
41 {
42 /**
43 * Perform batch update operation. Use this action for multi-step
44 * operations where you want to acquire a write lock for the duration of
45 * the operation.
46 */
47 public void perform() throws Exception;
48 }
49
50 void withSearch(SearcherAction action) throws LuceneException;
51
52 /**
53 * Idempotent operation. Just for querying, do not delete documents with
54 * this action use {@link #withReaderAndDeletes(ReaderAction)} to perform
55 * index deletes.
56 */
57 Object withReader(ReaderAction action) throws LuceneException;
58
59 /**
60 * Delete stuff in the index.
61 */
62 void withReaderAndDeletes(ReaderAction action) throws LuceneException;
63
64 /**
65 * Add (write) documents to the index
66 */
67 void withWriter(WriterAction action) throws LuceneException;
68
69 /**
70 * Perform an Atomic delete and add. Shouldn't perform too many writes, for multiple writes use
71 * {@link #withBatchUpdate(com.atlassian.bonnie.ILuceneConnection.BatchUpdateAction)} as
72 * it will use the batch mode configuration, speeding up the writes.
73 */
74 void withDeleteAndWrites(ReaderAction readerAction, WriterAction action) throws LuceneException;
75
76 /**
77 * Perform multiple writes to the index. Holds a writeLock on the index for
78 * the whole time, and will use the {@link Configuration batch
79 * configuration} settings.
80 * <p/>
81 * Update actions performed within a batch update won't be visible to other
82 * readers or searchers until the batch is complete. Be aware this also
83 * applies to actions within a batch! That is, a read operation inside a
84 * batch will not see the changes made by earlier updates in that batch.
85 */
86 void withBatchUpdate(BatchUpdateAction action);
87
88 /**
89 * Perform an optimize on the index. Holds a writeLock and can take a long
90 * time (depending on the size of the index, how much optimization needs to
91 * be done... and whether a virus-checker is installed :) ).
92 */
93 void optimize() throws LuceneException;
94
95 /**
96 * Closes the reader and the writer. Calling any method on the API after
97 * closing the connection will throw {@link LuceneConnectionClosedException}.
98 */
99 void close() throws LuceneException;
100
101 /**
102 * Returns the number of {@link Document documents} in the index.
103 */
104 int getNumDocs();
105
106 /**
107 * Returns true if the index has been created. This means that the index
108 * directory itself exists AND has been initialised with the default
109 * required index files.
110 *
111 * @return true
112 * @deprecated since 3.2 index creation is handled by the implementation, so this
113 * method now always returns true.
114 */
115 boolean isIndexCreated();
116
117 /**
118 * Create or recreate the underlying directory the index is contained in.
119 * Blow away any indexes that currently live there.
120 */
121 void recreateIndexDirectory();
122
123 /**
124 * Get the current Searcher from the ILuceneConnection.
125 * <p/>
126 * Do not forget to call the Searcher's close() method once the searcher is no longer neeeded.
127 *
128 * @deprecated since 3.2 because the searcher shouldn't be leaked
129 * @see #withSearch(SearcherAction)
130 */
131 IndexSearcher leakSearcher();
132
133 /**
134 * Removes all documents from the index.
135 *
136 * @throws LuceneException if there was a problem removing the index
137 */
138 void truncateIndex() throws LuceneException;
139
140 /**
141 * Provide configuration for the index writers used by implementations of this interface.
142 *
143 * @see DefaultConfiguration
144 */
145 public interface Configuration
146 {
147 int getInteractiveMergeFactor();
148 int getInteractiveMaxMergeDocs();
149 int getInteractiveMaxBufferedDocs();
150 int getBatchMergeFactor();
151 int getBatchMaxMergeDocs();
152 int getBatchMaxBufferedDocs();
153 int getMaxFieldLength();
154 boolean isCompoundIndexFileFormat();
155 }
156
157 /**
158 * The Bonnie default configuration. Preserves backward compatibility for old Confluence settings.
159 */
160 static final Configuration DEFAULT_CONFIGURATION = new DefaultConfiguration();
161 }