org.apache.lucene.index
Class IndexModifier

java.lang.Object
  extended by org.apache.lucene.index.IndexModifier

public class IndexModifier
extends java.lang.Object

A class to modify an index, i.e. to delete and add documents. This class hides IndexReader and IndexWriter so that you do not need to care about implementation details such as that adding documents is done via IndexWriter and deletion is done via IndexReader.

Note that you cannot create more than one IndexModifier object on the same directory at the same time.

Example usage:

    Analyzer analyzer = new StandardAnalyzer();
    // create an index in /tmp/index, overwriting an existing one:
    IndexModifier indexModifier = new IndexModifier("/tmp/index", analyzer, true);
    Document doc = new Document();
    doc.add(new Field("id""1", Field.Store.YES, Field.Index.UN_TOKENIZED));
    doc.add(new Field("body""a simple test", Field.Store.YES, Field.Index.TOKENIZED));
    indexModifier.addDocument(doc);
    int deleted = indexModifier.delete(new Term("id""1"));
    System.out.println("Deleted " + deleted + " document");
    indexModifier.flush();
    System.out.println(indexModifier.docCount() " docs in index");
    indexModifier.close();

Not all methods of IndexReader and IndexWriter are offered by this class. If you need access to additional methods, either use those classes directly or implement your own class that extends IndexModifier.

Although an instance of this class can be used from more than one thread, you will not get the best performance. You might want to use IndexReader and IndexWriter directly for that (but you will need to care about synchronization yourself then).

While you can freely mix calls to add() and delete() using this class, you should batch you calls for best performance. For example, if you want to update 20 documents, you should first delete all those documents, then add all the new documents.

Author:
Daniel Naber

Field Summary
protected  Analyzer analyzer
           
protected  Directory directory
           
protected  IndexReader indexReader
           
protected  IndexWriter indexWriter
           
protected  java.io.PrintStream infoStream
           
protected  int maxBufferedDocs
           
protected  int maxFieldLength
           
protected  int mergeFactor
           
protected  boolean open
           
protected  boolean useCompoundFile
           
 
Constructor Summary
IndexModifier(Directory directory, Analyzer analyzer, boolean create)
          Open an index with write access.
IndexModifier(java.io.File file, Analyzer analyzer, boolean create)
          Open an index with write access.
IndexModifier(java.lang.String dirName, Analyzer analyzer, boolean create)
          Open an index with write access.
 
Method Summary
 void addDocument(Document doc)
          Adds a document to this index.
 void addDocument(Document doc, Analyzer docAnalyzer)
          Adds a document to this index, using the provided analyzer instead of the one specific in the constructor.
protected  void assureOpen()
          Throw an IllegalStateException if the index is closed.
 void close()
          Close this index, writing all pending changes to disk.
protected  void createIndexReader()
          Close the IndexWriter and open an IndexReader.
protected  void createIndexWriter()
          Close the IndexReader and open an IndexWriter.
 void delete(int docNum)
          Deprecated. Use deleteDocument(int) instead.
 int delete(Term term)
          Deprecated. Use deleteDocuments(Term) instead.
 void deleteDocument(int docNum)
          Deletes the document numbered docNum.
 int deleteDocuments(Term term)
          Deletes all documents containing term.
 int docCount()
          Returns the number of documents currently in this index.
 void flush()
          Make sure all changes are written to disk.
 java.io.PrintStream getInfoStream()
           
 int getMaxBufferedDocs()
           
 int getMaxFieldLength()
           
 int getMergeFactor()
           
 boolean getUseCompoundFile()
           
protected  void init(Directory directory, Analyzer analyzer, boolean create)
          Initialize an IndexWriter.
 void optimize()
          Merges all segments together into a single segment, optimizing an index for search.
 void setInfoStream(java.io.PrintStream infoStream)
          If non-null, information about merges and a message when getMaxFieldLength() is reached will be printed to this.
 void setMaxBufferedDocs(int maxBufferedDocs)
          The maximum number of terms that will be indexed for a single field in a document.
 void setMaxFieldLength(int maxFieldLength)
          The maximum number of terms that will be indexed for a single field in a document.
 void setMergeFactor(int mergeFactor)
          Determines how often segment indices are merged by addDocument().
 void setUseCompoundFile(boolean useCompoundFile)
          Setting to turn on usage of a compound file.
 java.lang.String toString()
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

indexWriter

protected IndexWriter indexWriter

indexReader

protected IndexReader indexReader

directory

protected Directory directory

analyzer

protected Analyzer analyzer

open

protected boolean open

infoStream

protected java.io.PrintStream infoStream

useCompoundFile

protected boolean useCompoundFile

maxBufferedDocs

protected int maxBufferedDocs

maxFieldLength

protected int maxFieldLength

mergeFactor

protected int mergeFactor
Constructor Detail

IndexModifier

public IndexModifier(Directory directory,
                     Analyzer analyzer,
                     boolean create)
              throws java.io.IOException
Open an index with write access.

Parameters:
directory - the index directory
analyzer - the analyzer to use for adding new documents
create - true to create the index or overwrite the existing one; false to append to the existing index
Throws:
java.io.IOException

IndexModifier

public IndexModifier(java.lang.String dirName,
                     Analyzer analyzer,
                     boolean create)
              throws java.io.IOException
Open an index with write access.

Parameters:
dirName - the index directory
analyzer - the analyzer to use for adding new documents
create - true to create the index or overwrite the existing one; false to append to the existing index
Throws:
java.io.IOException

IndexModifier

public IndexModifier(java.io.File file,
                     Analyzer analyzer,
                     boolean create)
              throws java.io.IOException
Open an index with write access.

Parameters:
file - the index directory
analyzer - the analyzer to use for adding new documents
create - true to create the index or overwrite the existing one; false to append to the existing index
Throws:
java.io.IOException
Method Detail

init

protected void init(Directory directory,
                    Analyzer analyzer,
                    boolean create)
             throws java.io.IOException
Initialize an IndexWriter.

Throws:
java.io.IOException

assureOpen

protected void assureOpen()
Throw an IllegalStateException if the index is closed.

Throws:
java.lang.IllegalStateException

createIndexWriter

protected void createIndexWriter()
                          throws java.io.IOException
Close the IndexReader and open an IndexWriter.

Throws:
java.io.IOException

createIndexReader

protected void createIndexReader()
                          throws java.io.IOException
Close the IndexWriter and open an IndexReader.

Throws:
java.io.IOException

flush

public void flush()
           throws java.io.IOException
Make sure all changes are written to disk.

Throws:
java.io.IOException

addDocument

public void addDocument(Document doc,
                        Analyzer docAnalyzer)
                 throws java.io.IOException
Adds a document to this index, using the provided analyzer instead of the one specific in the constructor. If the document contains more than setMaxFieldLength(int) terms for a given field, the remainder are discarded.

Throws:
java.lang.IllegalStateException - if the index is closed
java.io.IOException
See Also:
IndexWriter.addDocument(Document, Analyzer)

addDocument

public void addDocument(Document doc)
                 throws java.io.IOException
Adds a document to this index. If the document contains more than setMaxFieldLength(int) terms for a given field, the remainder are discarded.

Throws:
java.lang.IllegalStateException - if the index is closed
java.io.IOException
See Also:
IndexWriter.addDocument(Document)

deleteDocuments

public int deleteDocuments(Term term)
                    throws java.io.IOException
Deletes all documents containing term. This is useful if one uses a document field to hold a unique ID string for the document. Then to delete such a document, one merely constructs a term with the appropriate field and the unique ID string as its text and passes it to this method. Returns the number of documents deleted.

Returns:
the number of documents deleted
Throws:
java.lang.IllegalStateException - if the index is closed
java.io.IOException
See Also:
IndexReader.deleteDocuments(Term)

delete

public int delete(Term term)
           throws java.io.IOException
Deprecated. Use deleteDocuments(Term) instead.

Deletes all documents containing term. This is useful if one uses a document field to hold a unique ID string for the document. Then to delete such a document, one merely constructs a term with the appropriate field and the unique ID string as its text and passes it to this method. Returns the number of documents deleted.

Returns:
the number of documents deleted
Throws:
java.lang.IllegalStateException - if the index is closed
java.io.IOException
See Also:
IndexReader.deleteDocuments(Term)

deleteDocument

public void deleteDocument(int docNum)
                    throws java.io.IOException
Deletes the document numbered docNum.

Throws:
java.lang.IllegalStateException - if the index is closed
java.io.IOException
See Also:
IndexReader.deleteDocument(int)

delete

public void delete(int docNum)
            throws java.io.IOException
Deprecated. Use deleteDocument(int) instead.

Deletes the document numbered docNum.

Throws:
java.lang.IllegalStateException - if the index is closed
java.io.IOException
See Also:
IndexReader.deleteDocument(int)

docCount

public int docCount()
Returns the number of documents currently in this index.

Throws:
java.lang.IllegalStateException - if the index is closed
See Also:
IndexWriter.docCount(), IndexReader.numDocs()

optimize

public void optimize()
              throws java.io.IOException
Merges all segments together into a single segment, optimizing an index for search.

Throws:
java.lang.IllegalStateException - if the index is closed
java.io.IOException
See Also:
IndexWriter.optimize()

setInfoStream

public void setInfoStream(java.io.PrintStream infoStream)
If non-null, information about merges and a message when getMaxFieldLength() is reached will be printed to this.

Example: index.setInfoStream(System.err);

Throws:
java.lang.IllegalStateException - if the index is closed
See Also:
IndexWriter.setInfoStream(PrintStream)

getInfoStream

public java.io.PrintStream getInfoStream()
                                  throws java.io.IOException
Throws:
java.io.IOException
See Also:
setInfoStream(PrintStream)

setUseCompoundFile

public void setUseCompoundFile(boolean useCompoundFile)
Setting to turn on usage of a compound file. When on, multiple files for each segment are merged into a single file once the segment creation is finished. This is done regardless of what directory is in use.

Throws:
java.lang.IllegalStateException - if the index is closed
See Also:
IndexWriter.setUseCompoundFile(boolean)

getUseCompoundFile

public boolean getUseCompoundFile()
                           throws java.io.IOException
Throws:
java.io.IOException
See Also:
setUseCompoundFile(boolean)

setMaxFieldLength

public void setMaxFieldLength(int maxFieldLength)
The maximum number of terms that will be indexed for a single field in a document. This limits the amount of memory required for indexing, so that collections with very large files will not crash the indexing process by running out of memory.

Note that this effectively truncates large documents, excluding from the index terms that occur further in the document. If you know your source documents are large, be sure to set this value high enough to accomodate the expected size. If you set it to Integer.MAX_VALUE, then the only limit is your memory, but you should anticipate an OutOfMemoryError.

By default, no more than 10,000 terms will be indexed for a field.

Throws:
java.lang.IllegalStateException - if the index is closed
See Also:
IndexWriter.setMaxFieldLength(int)

getMaxFieldLength

public int getMaxFieldLength()
                      throws java.io.IOException
Throws:
java.io.IOException
See Also:
setMaxFieldLength(int)

setMaxBufferedDocs

public void setMaxBufferedDocs(int maxBufferedDocs)
The maximum number of terms that will be indexed for a single field in a document. This limits the amount of memory required for indexing, so that collections with very large files will not crash the indexing process by running out of memory.

Note that this effectively truncates large documents, excluding from the index terms that occur further in the document. If you know your source documents are large, be sure to set this value high enough to accomodate the expected size. If you set it to Integer.MAX_VALUE, then the only limit is your memory, but you should anticipate an OutOfMemoryError.

By default, no more than 10,000 terms will be indexed for a field.

Throws:
java.lang.IllegalStateException - if the index is closed
See Also:
IndexWriter.setMaxBufferedDocs(int)

getMaxBufferedDocs

public int getMaxBufferedDocs()
                       throws java.io.IOException
Throws:
java.io.IOException
See Also:
setMaxBufferedDocs(int)

setMergeFactor

public void setMergeFactor(int mergeFactor)
Determines how often segment indices are merged by addDocument(). With smaller values, less RAM is used while indexing, and searches on unoptimized indices are faster, but indexing speed is slower. With larger values, more RAM is used during indexing, and while searches on unoptimized indices are slower, indexing is faster. Thus larger values (> 10) are best for batch index creation, and smaller values (< 10) for indices that are interactively maintained.

This must never be less than 2. The default value is 10.

Throws:
java.lang.IllegalStateException - if the index is closed
See Also:
IndexWriter.setMergeFactor(int)

getMergeFactor

public int getMergeFactor()
                   throws java.io.IOException
Throws:
java.io.IOException
See Also:
setMergeFactor(int)

close

public void close()
           throws java.io.IOException
Close this index, writing all pending changes to disk.

Throws:
java.lang.IllegalStateException - if the index has been closed before already
java.io.IOException

toString

public java.lang.String toString()
Overrides:
toString in class java.lang.Object


Copyright © 2000-2008 Apache Software Foundation. All Rights Reserved.