Package io.fluxcapacitor.javaclient.tracking.handling

Annotation Interface HandleDocument

@Documented @Retention(RUNTIME) @Target({METHOD,CONSTRUCTOR}) @HandleMessage(DOCUMENT) public @interface HandleDocument
Marks a method or constructor as a handler for document messages within a search collection.

This is a specialization of HandleMessage for MessageType.DOCUMENT messages. It allows consuming updates from the document store in near real-time—similar to event tracking. Handlers can either specify a collection name or a document class.

Document Tracking Semantics

Each time a document is (re)indexed in Flux Capacitor, it receives a new tracking index. When a handler is subscribed via @HandleDocument, it will receive the most recent version of the document for each index. If the tracker is behind (e.g., during a replay), earlier versions of the same document may be skipped—only the latest version is retained.

Transforming and Updating Documents

A powerful feature of document handlers is that they can return a modified version of the document to update it in-place. This allows document transformations and upcasting to be applied automatically and reliably.

For this behavior to take effect:

  • The returned document must have a higher Revision than the one stored
  • The updated version will be stored in the document collection under the same ID

This mechanism supports fully-automated data migrations: handlers can evolve or patch documents over time, and changes are persisted across application restarts.

See Also:

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    boolean
    disabled
    If true, disables this handler during discovery.
    Class<?>
    documentClass
    Optional class of the documents to handle.
    String
    value
    Optional name of the document collection.

  • Element Details

    • value

      String value
      Optional name of the document collection. If provided, documentClass() is ignored.

      If neither documentClass nor value are specified, the first parameter of the method is used to determine the collection: 

      
 class OrganisationHandler {
     @HandleDocument
     void on(Organisation organisation, Metadata metadata) { ... }
 }
      See Also:
      Default:
      ""

    • documentClass

      Class<?> documentClass
      Optional class of the documents to handle. If annotated with Searchable, the annotation defines the collection; otherwise the class name is used.

      If neither documentClass nor value are specified, the first parameter of the method is used to determine the collection: 

      
 class OrganisationHandler {
     @HandleDocument
     void on(Organisation organisation, Metadata metadata) { ... }
 }
      See Also:
      Default:
      java.lang.Void.class

    • disabled

      boolean disabled
      If true, disables this handler during discovery.
      Default:
      false