We're updating the issue view to help you get more done. 

Revisit the names of "SearchWriter" and "SearchSessionWritePlan"

Description

Problems:

  • "SearchWriter" is very generic. It gives the impression it's the single entry point to write to the indexes, and that's not try.

  • "SearchSessionWritePlan" can be used to achieve similar results to "MassIndexer", yet its name is very, very different.

Other names have been suggested, but they have their own problems:

  • "SearchAdminService" instead of "SearchWriter" would be a bit more precise, but "Service" is not great for an object that is definitely not a singleton. On top of that, it's not certain that this object will be only about "admin" operations forever. See below.

  • "SearchSessionIndexer" instead of "SearchSessionWritePlan" would be closer to "MassIndexer", but would also hide some important differences with the mass indexer. In particular, the write plan doesn't load entities on its own, it expects entities to be provided to it. Also, the write plan may be populated automatically by Hibernate ORM when entities are persisted/updated/deleted.

Some facts about "SearchWriter":

  • It is not bound to an ORM session, but keeps some information from the session it originated from. At the moment, this information is only the tenantId.

  • It only applies to a set of indexed types defined when the writer is created.

  • It exposes "large-scale" index operations: purge, optimize, flush.

  • In the future, it would be nice to allow users to write their own "mass indexer" using only the "SearchWriter" as an API: it already provides the purge/flush/optimize operations and the only thing missing are the "add-and-do-not-care-about-anything-else" operation, which doesn't reindex associated entities and does not check if the document already exists before putting it in the index. See org.hibernate.search.mapper.pojo.work.spi.PojoSessionWorkExecutor#add(java.lang.Object). That operation would require a session, however.

Some facts about "SearchSessionWritePlan":

  • It is bound to an ORM session.

  • It can apply to any indexed type.

  • It exposes "document-scale" operations: addOrUpdate, delete, purge (a single document).

  • It handles automatic reindexing of associated entities: if you call "addOrUpdate" on an entity A, and that entity is index-embedded into entity B, then entity B will be reindexed.

  • It does not load entities on its own, but expects entities to index to be submitted to it.

  • It receives commands from the Hibernate ORM session when automatic indexing is enabled: any time an entity is changed, it will be added to the write plan.

  • It receives commands from the user directly.

  • It is executed on transaction commit by default, but the user can choose to call process() or execute() before commit to execute reads or writes early.

Environment

None

Status

Assignee

Yoann Rodière

Reporter

Yoann Rodière

Components

Fix versions

Priority

Major