org.hibernate.search.mapper.orm.work

Interface SearchIndexingPlan

public interface SearchIndexingPlan

An interface for indexing entities in the context of an ORM Session.

This class is stateful: it queues operations internally to apply them at a later time.

When process() is called, or when automatic indexing is enabled and a Hibernate ORM Session flush() happens, the entities will be processed and index documents will be built and stored in an internal buffer.

When execute() is called, or when automatic indexing is enabled and a Hibernate ORM transaction is committed or a Hibernate ORM Session flush() happens outside of any transaction, the operations will be actually sent to the index.

Note that execute() will implicitly trigger processing of documents that weren't processed yet, if any, so calling process() is not necessary if you call execute() just next.

process() and execute() are mostly useful when automatic indexing is disabled, to control the indexing process explicitly.

Method Summary

Modifier and Type	Method and Description
void	addOrUpdate(Object entity) Add or update a document in the index if the entity type is mapped to an index (Indexed), and re-index documents that embed this entity (through IndexedEmbedded for example).
void	delete(Object entity) Delete the entity from the index if the entity type is mapped to an index (Indexed), and re-index documents that embed this entity (through IndexedEmbedded for example).
void	execute() Write all pending changes to the index now, without waiting for a Hibernate ORM flush event or transaction commit.
void	process() Extract all data from objects passed to the indexing plan so far, creates documents to be indexed and put them into an internal buffer, without writing them to the indexes.
void	purge(Class<?> entityClass, Object providedId) Delete the entity from the index.
void	purge(String entityName, Object providedId) Delete the entity from the index.

Method Detail

addOrUpdate

void addOrUpdate(Object entity)

Add or update a document in the index if the entity type is mapped to an index (Indexed), and re-index documents that embed this entity (through IndexedEmbedded for example).

Parameters:

entity - The entity to add or update in the index.

Throws:

SearchException - If the entity type is not indexed, neither directly (Indexed) nor through another indexed type that embeds it (IndexedEmbedded for example).

delete

void delete(Object entity)

Delete the entity from the index if the entity type is mapped to an index (Indexed), and re-index documents that embed this entity (through IndexedEmbedded for example).

Parameters:

entity - The entity to delete from the index.

Throws:

SearchException - If the entity type is not indexed, neither directly (Indexed) nor through another indexed type that embeds it (IndexedEmbedded for example).

purge

void purge(Class<?> entityClass,
           Object providedId)

Delete the entity from the index.

On contrary to delete(Object), if documents embed this entity (through IndexedEmbedded for example), these documents will not be re-indexed, leaving the indexes in an inconsistent state until they are re-indexed manually.

Parameters:

entityClass - The class of the entity to delete from the index.

providedId - A value to extract the document ID from. Generally the expected value is the entity ID, but a different value may be expected depending on the mapping.

Throws:

SearchException - If the entity type is not indexed directly (Indexed).

purge

void purge(String entityName,
           Object providedId)

Delete the entity from the index.

On contrary to delete(Object), if documents embed this entity (through IndexedEmbedded for example), these documents will not be re-indexed, leaving the indexes in an inconsistent state until they are re-indexed manually.

Parameters:

entityName - An entity name. See Entity.name().

providedId - A value to extract the document ID from. Generally the expected value is the entity ID, but a different value may be expected depending on the mapping.

Throws:

SearchException - If the entity type is not indexed directly (Indexed).

process

void process()

Extract all data from objects passed to the indexing plan so far, creates documents to be indexed and put them into an internal buffer, without writing them to the indexes.

Calling this method is optional: the execute() method or the automatic write on transaction commit will perform the extraction as necessary.

However, calling this method can be useful before a session is cleared if automatic indexing is disabled: it will make sure the data lost when clearing the session will no longer be necessary for indexing.

Caution: calling this method repeatedly without a call to execute() will add more and more data to an internal document buffer, which may lead to an OutOfMemoryError. Use with caution in batch processes.

execute

void execute()

Write all pending changes to the index now, without waiting for a Hibernate ORM flush event or transaction commit.

If a transaction is active and is ultimately rolled back, the written changes will not be rolled back, causing indexes to become out of sync with the database. Thus, calling this method should generally be avoided, and relying on automatic write on transaction commit should be preferred.