The support lets you use directly the Lucene entities like the Document and/ Term classes in order to manipulate the index. In this case, you have the responsability to create the documents to add or update and the term. The latters are then passed to the addDocument(s) and updateDocument(s) methods. In this case, the template has the responsability to handle the underlying Lucene resources in order to manage the operation.

Related to the adding, the support provides the ability to add only one document with the addDocument methods. In order to add several documents, addDocuments methods are provided too.

The following example shows how to create a Lucene document and add it to the index using the addDocument method:

Document document = new Document();
document.add(new Field("field", "a sample 1", Field.Store.YES, Field.Index.ANALYZED));
document.add(new Field("sort", "2", Field.Store.YES, Field.Index.NOT_ANALYZED));
getLuceneIndexTemplate().addDocument(document);

The following example shows how to create a list of Lucene documents and add it to the index using the addDocuments method:

List<Document> documents = new ArrayList<Document>();

Document document1 = new Document();
document1.add(new Field("field", "a sample 1", Field.Store.YES, Field.Index.ANALYZED));
document1.add(new Field("sort", "1", Field.Store.YES, Field.Index.NOT_ANALYZED));
documents.add(document1);

Document document2 = new Document();
document2.add(new Field("field", "a sample 2", Field.Store.YES, Field.Index.ANALYZED));
document2.add(new Field("sort", "2", Field.Store.YES, Field.Index.NOT_ANALYZED));
documents.add(document2);

getLuceneIndexTemplate().addDocuments(documents);

In the case of updating documents, the template does a smart update because it checks if the term corresponds exactly to a document in the case of the updateDocument method and at least to one document in the case of the updateDocuments method.

The update methods of the template use internally the update methods of the index writer. These latters make a delete of documents based on the specified term and then add the document. Thus, the corresponding methods of the template follow the same mechanism.

The following code shows the use of the updateDocument method:

Document document = new Document();
document.add(new Field("field", "a Lucene sample", Field.Store.YES, Field.Index.ANALYZED));
document.add(new Field("sort", "2", Field.Store.YES, Field.Index.NOT_ANALYZED));
getLuceneIndexTemplate().updateDocument("field:lucene", document);

The following code shows the use of the updateDocuments method in order to update several documents with one operation of the template:

List<Document> documents = new ArrayList<Document>();

Document document1 = new Document();
document1.add(new Field("field", "a sample", Field.Store.YES, Field.Index.ANALYZED));
document1.add(new Field("sort", "1", Field.Store.YES, Field.Index.NOT_ANALYZED));
documents.add(document1);

Document document2 = new Document();
document2.add(new Field("field", "a Lucene sample", Field.Store.YES, Field.Index.ANALYZED));
document2.add(new Field("sort", "2", Field.Store.YES, Field.Index.NOT_ANALYZED));
documents.add(document2);

getLuceneIndexTemplate().updateDocuments("field:sample", documents);

The delete methods follow the same mechanisms of the update methods according the checks of documents. Both deleteDocument and deleteDocuments are provided by the template in order to delete one or more documents.

The following code shows the use of deleteDocument and deleteDocuments methods:

getLuceneIndexTemplate().deleteDocument("field:lucene");
getLuceneIndexTemplate().deleteDocuments("field:sample");

The template of the Lucene support provides too the ability to use an abstraction layer in the process of Lucene document creation. The main advantages of this approach consists in the handling of resources according to the exception eventually thrown during the document creation. The template supports both simple document creators and input stream based document creators.

The template offers the possibility to use this mechanism with addDocument(s) and updateDocument(s) methods. We will describe now this feature.

The following code describes the content of the simplest document creator, which provides a simple way to create a Lucene document:

public interface DocumentCreator {
    Document createDocument() throws Exception;
}

The following code shows the way to use the DocumentCreator interface with the addDocument method of the template:

getLuceneIndexTemplate().addDocument(new DocumentCreator() {
    public Document createDocument() throws Exception {
        Document document = new Document();
        document.add(new Field("field", "a Lucene sample", Field.Store.YES, Field.Index.ANALYZED));
        document.add(new Field("sort", "2", Field.Store.YES, Field.Index.NOT_ANALYZED));
        return document;
    }
});

The InputStreamDocumentCreator interface provides a dedicated entity in order to create a Lucene document from an InputStream. When using this interface, you need to specify how to obtain the InputStream and to create a document from this InputStream.

The template has the responsability to correctly handle the InputStream and to close it in every case. The following code describes the content of the InputStreamDocumentCreator interface:

public interface InputStreamDocumentCreator {
    InputStream createInputStream() throws IOException;
    Document createDocumentFromInputStream(InputStream inputStream) throws Exception;
}

The following code shows the way to use the InputStreamDocumentCreator interface with the addDocument method of the template:

template.addDocument(new InputStreamDocumentCreator() {
    public InputStream createInputStream() throws IOException {
        ClassPathResource resource = new ClassPathResource(
                     "/org/springframework/lucene/index/core/test.txt");
        return resource.getInputStream();
    }

    public Document createDocumentFromInputStream(InputStream inputStream) throws Exception {
        String contents = IOUtils.getContents(inputStream);

        Document document = new Document();
        document.add(new Field("field", contents, Field.Store.YES, Field.Index.ANALYZED));
        document.add(new Field("sort", "2", Field.Store.YES, Field.Index.NOT_ANALYZED));
        return document;
    }
});

Finally the support provides an entity in order to create a list of Lucene documents to be added, the DocumentsCreator interface. It is similar to the DocumentCreator interface. The following code describes this interface:

public interface DocumentsCreator {
    List<Document> createDocuments() throws Exception;
}

The following code shows the way to use the DocumentsCreator interface with the addDocuments method of the template:

template.addDocuments(new DocumentsCreator() {
    public List<Document> createDocuments() throws Exception {
        List<Document> documents = new ArrayList<Document>();

        Document document1 = new Document();
        document1.add(new Field("field", "a Lucene sample", Field.Store.YES, Field.Index.ANALYZED));
        document1.add(new Field("sort", "1", Field.Store.YES, Field.Index.NOT_ANALYZED));
        documents.add(document1);

        Document document2 = new Document();
        document2.add(new Field("field", "a sample", Field.Store.YES, Field.Index.ANALYZED));
        document2.add(new Field("sort", "2", Field.Store.YES, Field.Index.NOT_ANALYZED));
        documents.add(document2);

        return documents;
    }
});

There are two approaches in order to specify an analyzer during the indexing process. On one hand, you can set a global analyzer for the template which is used as default analyzer. Thus, with methods without an analyzer parameter, the global analyzer of the template is used. The following code describes the use of this approach:

Document document = new Document();
document.add(new Field("field", "a sample 1", Field.Store.YES, Field.Index.ANALYZED));
document.add(new Field("sort", "2", Field.Store.YES, Field.Index.NOT_ANALYZED));
getLuceneIndexTemplate().addDocument(document);

In the code above, the default analyzer injected in the template is used to add the document. If no analyzer is defined, an exception is thrown.

The support provides too methods with a analyzer parameter. In this case, the specified analyzer is used instead of the default one. The following code describes the use of this approach with the same operation:

SimpleAnalyzer analyzer = new SimpleAnalyzer();

Document document = new Document();
document.add(new Field("field", "a sample 1", Field.Store.YES, Field.Index.ANALYZED));
document.add(new Field("sort", "2", Field.Store.YES, Field.Index.NOT_ANALYZED));
getLuceneIndexTemplate().addDocument(document, analyzer);

TODO: describe the use of optimize, getXXX methods

The aim of the indexing template is to integrate and hide the use of Lucene API in order to make easy the indexing. This entity provides to the developer all the common operations in this context. However, if you need to go beyond these methods, the template enables to provide the underlying reader and writer entities in order to use it explicitely.

The feature is based on the ReaderCallback and WriterCallback interfaces described above. When using the entity, you need to implement respectively the doWithReader and doWithWriter methods which gives you the underlying instance corresponding the reader and the writer. These latter can be used in your indexing.

The Lucene support continues however to handle and manage these resources. The code below describes the content of the interface ReaderCallback:

public interface ReaderCallback {
    Object doWithReader(IndexReaderWrapper reader) throws Exception;
}

The code below describes the content of the interface WriterCallback:

public interface WriterCallback {
    Object doWithWriter(IndexWriterWrapper writer) throws Exception;
}

This entity can be used as parameter of the read and writer methods of the template, as shown in the following code:

getLuceneIndexTemplate().write(new WriterCallback() {
    public Object doWithWriter(IndexWriterWrapper writer) throws Exception {
        Document document = new Document();
        document.add(new Field("field", "a sample", Field.Store.YES, Field.Index.ANALYZED));
		
        writer.addDocument(document);

        return null;
    }
});

When using the underlying writer, the analyzer specified for the index template is not used. You need to explicitely specify it on your calls or configure it on the index factory used. In the latter case, the analyzer is set during the creation of the writer.