Class DittoStore

java.lang.Object
com.ditto.java.DittoStore
All Implemented Interfaces:
DittoQueryExecuting
public final class DittoStore extends Object implements DittoQueryExecuting
Provides access to execute Ditto queries.

  • Method Details

    • getObservers

      public @NonNull Set<? extends DittoStoreObserver> getObservers()
      Returns all currently active store observers.
      Returns:
      a Set of active DittoStoreObserver instances.

    • execute

      public @NonNull CompletionStage<DittoQueryResult> execute(@NonNull String query)
      Executes a DQL query and returns items as a query result. This method only returns results from the local store without waiting for any DittoSyncSubscriptions to have caught up with the latest changes. Only use this method if your program must proceed with immediate results. Use a DittoStoreObserver to receive updates to query results as soon as they have been synced to this peer.
      Specified by:
      execute in interface DittoQueryExecuting
      Parameters:
      query - a string containing a valid query expressed in DQL.
      Returns:
      a CompletionStage that completes with a DittoQueryResult containing a DittoQueryResultItem for each match.
      See Also:

    • execute

      public @NonNull CompletionStage<DittoQueryResult> execute(@NonNull String query, @NonNull DittoCborSerializable.Dictionary arguments)
      Executes a DQL query with arguments and returns items as a query result. This method only returns results from the local store without waiting for any DittoSyncSubscriptions to have caught up with the latest changes. Only use this method if your program must proceed with immediate results. Use a DittoStoreObserver to receive updates to query results as soon as they have been synced to this peer.
      Specified by:
      execute in interface DittoQueryExecuting
      Parameters:
      query - a string containing a valid query expressed in DQL.
      arguments - a dictionary of values keyed by the placeholder name without the leading :. Example: ["mileage": 123].
      Returns:
      a CompletionStage that completes with a DittoQueryResult containing a DittoQueryResultItem for each match.
      See Also:

    • observe

      public <@NonNull T> @NonNull Flow.Publisher<T> observe(@NonNull String query, @NonNull Function<@NonNull DittoQueryResult,@NonNull CompletionStage<@NonNull T>> transform)
      Returns a Flow Publisher that emits transformed query results whenever the local store changes.
      Type Parameters:
      T - the type of values emitted by the returned Publisher.
      Parameters:
      query - a string containing a valid query expressed in DQL.
      transform - a function that transforms DittoQueryResult into a value of type T.
      Returns:
      a Flow.Publisher that emits values of type T.
      See Also:

    • observe

      public <@NonNull T> @NonNull Flow.Publisher<T> observe(@NonNull String query, @Nullable DittoCborSerializable.Dictionary arguments, @NonNull Function<@NonNull DittoQueryResult,@NonNull CompletionStage<@NonNull T>> transform)
      Returns a Flow Publisher that emits transformed query results whenever the local store changes.
      Type Parameters:
      T - the type of values emitted by the returned Publisher.
      Parameters:
      query - a string containing a valid query expressed in DQL.
      arguments - a dictionary of values keyed by the placeholder name without the leading :. Example: ["mileage": 123].
      transform - a function that transforms DittoQueryResult into a value of type T.
      Returns:
      a Flow.Publisher that emits values of type T.
      See Also:

    • registerObserver

      public @NonNull DittoStoreObserver registerObserver(@NonNull String query, @NonNull DittoChangeListener listener) throws DittoException
      Convenience method that registers an observer where signalNext is called automatically after the changeHandler finishes.
      Parameters:
      query - a string containing a valid query expressed in DQL.
      listener - a DittoChangeListener instance which will be invoked with the results as changes occur.
      Returns:
      an active DittoStoreObserver for the given query.
      Throws:
      DittoException - if there is a problem creating or registering the observer.
      See Also:

    • registerObserver

      public @NonNull DittoStoreObserver registerObserver(@NonNull String query, @Nullable DittoCborSerializable.Dictionary arguments, @NonNull DittoChangeListener listener) throws DittoException
      Convenience method that registers an observer where signalNext is called automatically after the changeHandler finishes.
      Parameters:
      query - a string containing a valid query expressed in DQL.
      arguments - a dictionary of values keyed by the placeholder name without the leading :. Example: ["mileage": 123].
      listener - a DittoChangeListener instance which will be invoked with the results as changes occur.
      Returns:
      an active DittoStoreObserver for the given query and arguments.
      Throws:
      DittoException - if there is a problem creating or registering the observer.
      See Also:

    • registerObserver

      public @NonNull DittoStoreObserver registerObserver(@NonNull String query, @NonNull DittoChangeListenerWithNextSignal listener) throws DittoException
      Installs and returns a store observer for a query, configuring Ditto to trigger the passed in change handler whenever documents in the local store change such that the result of the matching query changes. The passed in query must be a SELECT query, otherwise a DittoException.StoreException with DittoException.StoreExceptionReason.QueryNotSupported reason is thrown.
      Parameters:
      query - A string containing a valid query expressed in DQL.
      listener - A DittoChangeListenerWithNextSignal instance which will be invoked with the results as changes occur.
      Returns:
      An active DittoStoreObserver for the given query and arguments. You'll have to keep it to be able to cancel the observation by close()-ing it. Otherwise, it will remain active until the owning Ditto instance goes out of scope.
      Throws:
      DittoException.StoreException - When the provided query is not a SELECT query.
      DittoException

    • registerObserver

      public @NonNull DittoStoreObserver registerObserver(@NonNull String query, @Nullable DittoCborSerializable.Dictionary arguments, @NonNull DittoChangeListenerWithNextSignal listener) throws DittoException
      Installs and returns a store observer for a query, configuring Ditto to trigger the passed in change handler whenever documents in the local store change such that the result of the matching query changes. The passed in query must be a SELECT query, otherwise a DittoException.StoreException with DittoException.StoreExceptionReason.QueryNotSupported reason is thrown.
      Parameters:
      query - A string containing a valid query expressed in DQL.
      arguments - A Map of values keyed by the placeholder name without the leading :. Example: ["mileage": 123].
      listener - A DittoChangeListenerWithNextSignal instance which will be invoked with the results as changes occur.
      Returns:
      An active DittoStoreObserver for the given query and arguments. You'll have to keep it to be able to cancel the observation by close()-ing it. Otherwise, it will remain active until the owning Ditto instance goes out of scope.
      Throws:
      DittoException.StoreException - When the provided query is not a SELECT query.
      DittoException

    • transaction

      public <T> @NonNull CompletionStage<DittoTransaction.Result<T>> transaction(@NonNull DittoTransactionFunction<T> transactionBlock)
      Executes multiple DQL queries within a single atomic transaction. This ensures that either all statements are executed successfully, or none are executed at all, providing strong consistency guarantees. Certain mesh configurations may impose limitations on these guarantees. For more details, refer to the Ditto documentation. Transactions are initiated as read-write transactions by default, and only a single read-write transaction is executed at any given time. Any other read-write transaction started concurrently will wait until the current transaction has been committed or rolled back. Therefore, it is crucial to ensure a transaction finishes as early as possible so that other read-write transactions aren’t blocked for a long time. A transaction can also be configured to be read-only using the isReadonly parameter. Multiple read-only transactions can be executed concurrently. However, executing a mutating DQL statement in a read-only transaction will throw an error. If errors occur in an execute() call within the transaction block and the error is caught and handled within the block, the transaction will continue to run and will not be rolled back. However, if an error is thrown at any point inside the transaction block or while committing the transaction, the transaction is implicitly rolled back, and the error is propagated up to the caller. When a Ditto instance is explicitly closed or garbage collected, it will drive all pending transactions to completion before shutting down. Warning:* Calling ditto.store.execute() or creating a nested transaction within a transaction may lead to a deadlock. For a complete guide on transactions, refer to the Ditto documentation.
      Parameters:
      transactionBlock - A lambda that provides access to a DittoTransaction object, allowing DQL queries to be executed.
      Returns:
      A CompletionStage<DittoTransaction.Result> containing either the transaction action that was taken (DittoTransaction.Result.Commit or DittoTransaction.Result.Rollback), or an instance of DittoException. A DittoException.StoreException with DittoException.StoreExceptionReason.TransactionReadOnly reason will be propagated if the transaction is read-only, but a mutating query was executed.
      See Also:

    • transaction

      public <T> @NonNull CompletionStage<DittoTransaction.Result<T>> transaction(boolean isReadOnly, @NonNull DittoTransactionFunction<T> transactionBlock)
      Executes multiple DQL queries within a single atomic transaction. This ensures that either all statements are executed successfully, or none are executed at all, providing strong consistency guarantees. Certain mesh configurations may impose limitations on these guarantees. For more details, refer to the Ditto documentation. Transactions are initiated as read-write transactions by default, and only a single read-write transaction is executed at any given time. Any other read-write transaction started concurrently will wait until the current transaction has been committed or rolled back. Therefore, it is crucial to ensure a transaction finishes as early as possible so that other read-write transactions aren’t blocked for a long time. A transaction can also be configured to be read-only using the isReadonly parameter. Multiple read-only transactions can be executed concurrently. However, executing a mutating DQL statement in a read-only transaction will throw an error. If errors occur in an execute() call within the transaction block and the error is caught and handled within the block, the transaction will continue to run and will not be rolled back. However, if an error is thrown at any point inside the transaction block or while committing the transaction, the transaction is implicitly rolled back, and the error is propagated up to the caller. When a Ditto instance is explicitly closed or garbage collected, it will drive all pending transactions to completion before shutting down. Warning:* Calling ditto.store.execute() or creating a nested transaction within a transaction may lead to a deadlock. For a complete guide on transactions, refer to the Ditto documentation.
      Parameters:
      isReadOnly - A flag indicating whether the transaction is read-only.
      transactionBlock - A lambda that provides access to a DittoTransaction object, allowing DQL queries to be executed.
      Returns:
      A CompletionStage<DittoTransaction.Result> containing either the transaction action that was taken (DittoTransaction.Result.Commit or DittoTransaction.Result.Rollback), or an instance of DittoException. A DittoException.StoreException with DittoException.StoreExceptionReason.TransactionReadOnly reason will be propagated if the transaction is read-only, but a mutating query was executed.
      See Also:

    • transaction

      public <T> @NonNull CompletionStage<DittoTransaction.Result<T>> transaction(String hint, @NonNull DittoTransactionFunction<T> transactionBlock)
      Executes multiple DQL queries within a single atomic transaction. This ensures that either all statements are executed successfully, or none are executed at all, providing strong consistency guarantees. Certain mesh configurations may impose limitations on these guarantees. For more details, refer to the Ditto documentation. Transactions are initiated as read-write transactions by default, and only a single read-write transaction is executed at any given time. Any other read-write transaction started concurrently will wait until the current transaction has been committed or rolled back. Therefore, it is crucial to ensure a transaction finishes as early as possible so that other read-write transactions aren’t blocked for a long time. A transaction can also be configured to be read-only using the isReadonly parameter. Multiple read-only transactions can be executed concurrently. However, executing a mutating DQL statement in a read-only transaction will throw an error. If errors occur in an execute() call within the transaction block and the error is caught and handled within the block, the transaction will continue to run and will not be rolled back. However, if an error is thrown at any point inside the transaction block or while committing the transaction, the transaction is implicitly rolled back, and the error is propagated up to the caller. When a Ditto instance is explicitly closed or garbage collected, it will drive all pending transactions to completion before shutting down. Warning:* Calling ditto.store.execute() or creating a nested transaction within a transaction may lead to a deadlock. For a complete guide on transactions, refer to the Ditto documentation.
      Parameters:
      hint - A hint for the transaction, which is logged. Mostly useful for debugging and testing.
      transactionBlock - A lambda that provides access to a DittoTransaction object, allowing DQL queries to be executed.
      Returns:
      A CompletionStage<DittoTransaction.Result> containing either the transaction action that was taken (DittoTransaction.Result.Commit or DittoTransaction.Result.Rollback), or an instance of DittoException. A DittoException.StoreException with DittoException.StoreExceptionReason.TransactionReadOnly reason will be propagated if the transaction is read-only, but a mutating query was executed.
      See Also:

    • transaction

      public <T> @NonNull CompletionStage<DittoTransaction.Result<T>> transaction(String hint, boolean isReadOnly, @NonNull DittoTransactionFunction<T> transactionBlock)
      Executes multiple DQL queries within a single atomic transaction. This ensures that either all statements are executed successfully, or none are executed at all, providing strong consistency guarantees. Certain mesh configurations may impose limitations on these guarantees. For more details, refer to the Ditto documentation. Transactions are initiated as read-write transactions by default, and only a single read-write transaction is executed at any given time. Any other read-write transaction started concurrently will wait until the current transaction has been committed or rolled back. Therefore, it is crucial to ensure a transaction finishes as early as possible so that other read-write transactions aren’t blocked for a long time. A transaction can also be configured to be read-only using the isReadonly parameter. Multiple read-only transactions can be executed concurrently. However, executing a mutating DQL statement in a read-only transaction will throw an error. If errors occur in an execute() call within the transaction block and the error is caught and handled within the block, the transaction will continue to run and will not be rolled back. However, if an error is thrown at any point inside the transaction block or while committing the transaction, the transaction is implicitly rolled back, and the error is propagated up to the caller. When a Ditto instance is explicitly closed or garbage collected, it will drive all pending transactions to completion before shutting down. Warning:* Calling ditto.store.execute() or creating a nested transaction within a transaction may lead to a deadlock. For a complete guide on transactions, refer to the Ditto documentation.
      Parameters:
      hint - A hint for the transaction, which is logged. Mostly useful for debugging and testing.
      isReadOnly - A flag indicating whether the transaction is read-only.
      transactionBlock - A lambda that provides access to a DittoTransaction object, allowing DQL queries to be executed.
      Returns:
      A CompletionStage<DittoTransaction.Result> containing either the transaction action that was taken (DittoTransaction.Result.Commit or DittoTransaction.Result.Rollback), or an instance of DittoException. A DittoException.StoreException with DittoException.StoreExceptionReason.TransactionReadOnly reason will be propagated if the transaction is read-only, but a mutating query was executed.
      See Also:

    • newAttachment

      public @NonNull CompletionStage<DittoAttachment> newAttachment(@NonNull String path)
      Creates a new attachment, which can then be inserted into a document. The file residing at the provided path will be copied into the Ditto's store. The DittoAttachment object that is returned is what you can then use to insert an attachment into a document. You can provide metadata about the attachment, which will be replicated to other peers alongside the file attachment. Below is a snippet to show how you can use the newAttachment functionality to insert an attachment into a document.
      Parameters:
      path - the path to the file that you want to create an attachment with.
      Returns:
      A CompletionStage instance, which can be used to insert the attachment into a document.

    • newAttachment

      public @NonNull CompletionStage<DittoAttachment> newAttachment(@NonNull String path, @NonNull DittoCborSerializable.Dictionary metadata)
      Creates a new attachment, which can then be inserted into a document. The file residing at the provided path will be copied into the Ditto's store. The DittoAttachment object that is returned is what you can then use to insert an attachment into a document. You can provide metadata about the attachment, which will be replicated to other peers alongside the file attachment.
      Parameters:
      path - The path to the file that you want to create an attachment with.
      metadata - Metadata relating to the attachment.
      Returns:
      A CompletionStage instance, which can be used to insert the attachment into a document.

    • newAttachment

      public @NonNull CompletionStage<DittoAttachment> newAttachment(@NonNull InputStream inputStream)
      Creates a new attachment, which can then be inserted into a document. The file that the input stream relates to will be copied into Ditto's store. The DittoAttachment object that is returned is what you can then use to insert an attachment into a document. You can provide metadata about the attachment, which will be replicated to other peers alongside the file attachment. Note that the input stream provided will be closed once it has been read from.
      Parameters:
      inputStream - an input stream for the file that you want to create an attachment with.
      Returns:
      a CompletionStage instance, which can be used to insert the attachment into a document.

    • newAttachment

      public @NonNull CompletionStage<DittoAttachment> newAttachment(@NonNull InputStream inputStream, @NonNull DittoCborSerializable.Dictionary metadata)
      Creates a new attachment, which can then be inserted into a document. The file that the input stream relates to will be copied into Ditto's store. The DittoAttachment object that is returned is what you can then use to insert an attachment into a document. You can provide metadata about the attachment, which will be replicated to other peers alongside the file attachment. Note that the input stream provided will be closed once it has been read from.
      Parameters:
      inputStream - an input stream for the file that you want to create an attachment with.
      metadata - metadata relating to the attachment.
      Returns:
      a CompletionStage instance, which can be used to insert the attachment into a document.

    • newAttachmentBlocking

      public @NonNull DittoAttachment newAttachmentBlocking(@NonNull String path) throws DittoException
      A blocking alternative to newAttachment(String).
      Throws:
      DittoException
      See Also:

    • newAttachmentBlocking

      public @NonNull DittoAttachment newAttachmentBlocking(@NonNull String path, @NonNull DittoCborSerializable.Dictionary metadata) throws DittoException
      A blocking alternative to newAttachment(String, DittoCborSerializable.Dictionary).
      Throws:
      DittoException
      See Also:

    • newAttachmentBlocking

      public @NonNull DittoAttachment newAttachmentBlocking(@NonNull InputStream inputStream) throws DittoException
      A blocking alternative to newAttachment(InputStream).
      Throws:
      DittoException
      See Also:

    • newAttachmentBlocking

      public @NonNull DittoAttachment newAttachmentBlocking(@NonNull InputStream inputStream, @NonNull DittoCborSerializable.Dictionary metadata) throws DittoException
      A blocking alternative to newAttachment(InputStream, DittoCborSerializable.Dictionary).
      Throws:
      DittoException
      See Also:

    • getAttachmentFetchers

      public @NonNull Set<? extends DittoAttachmentFetcher> getAttachmentFetchers()
      All currently active attachment fetchers.

    • fetchAttachment

      public @NonNull CompletionStage<DittoAttachmentFetchResult> fetchAttachment(@NonNull DittoAttachmentToken token) throws DittoException
      Trigger an attachment to be downloaded locally to the device and observe its progress as it does so. When you encounter a document that contains an attachment the attachment will not automatically be downloaded along with the document. You trigger an attachment to be downloaded locally to a device by calling this method. It will report changes to the status of the fetch attempt as it tries to download it. Assuming it succeeds in downloading the attachment it will call the onFetchEvent block with a completed event object, which will hold a reference to the attachment.
      Parameters:
      token - the DittoAttachmentToken relevant to the attachment that you wish to download and observe.
      Returns:
      a CompletionStage, which can be used to cancel the fetching, or await the result. Otherwise, the fetch will remain active until it either completes, the attachment is deleted, or the owning Ditto object is closed.
      Throws:
      DittoException

    • fetchAttachment

      public @NonNull CompletionStage<DittoAttachmentFetchResult> fetchAttachment(@NonNull DittoAttachmentToken token, @Nullable DittoAttachmentFetchProgressHandler fetchProgressHandler)
      Trigger an attachment to be downloaded locally to the device and observe its progress as it does so. When you encounter a document that contains an attachment the attachment will not automatically be downloaded along with the document. You trigger an attachment to be downloaded locally to a device by calling this method. It will report changes to the status of the fetch attempt as it tries to download it. Assuming it succeeds in downloading the attachment it will call the onFetchEvent block with a completed event object, which will hold a reference to the attachment.
      Parameters:
      token - the DittoAttachmentToken relevant to the attachment that you wish to download and observe.
      fetchProgressHandler - a DittoAttachmentFetchProgressHandler instance that will be called when there is an update relating to the attachment fetch progress.
      Returns:
      a CompletionStage, which can be used to cancel the fetching, or await the result. Otherwise, the fetch will remain active until it either completes, the attachment is deleted, or the owning Ditto object is closed.

    • fetchAttachment

      public @NonNull CompletionStage<DittoAttachmentFetchResult> fetchAttachment(@NonNull Map<String,Object> tokenMap)
      Trigger an attachment to be downloaded locally to the device and observe its progress as it does so. When you encounter a document that contains an attachment the attachment will not automatically be downloaded along with the document. You trigger an attachment to be downloaded locally to a device by calling this method. It will report changes to the status of the fetch attempt as it tries to download it. Assuming it succeeds in downloading the attachment it will call the onFetchEvent block with a completed event object, which will hold a reference to the attachment.
      Parameters:
      tokenMap - a Map representation of DittoAttachmentToken relevant to the attachment that you wish to download and observe.
      Returns:
      a CompletionStage, which can be used to cancel the fetching, or await the result. Otherwise, the fetch will remain active until it either completes, the attachment is deleted, or the owning Ditto object is closed.

    • fetchAttachment

      public @NonNull CompletionStage<DittoAttachmentFetchResult> fetchAttachment(@NonNull Map<String,Object> tokenMap, @Nullable DittoAttachmentFetchProgressHandler fetchProgressHandler)
      Trigger an attachment to be downloaded locally to the device and observe its progress as it does so. When you encounter a document that contains an attachment the attachment will not automatically be downloaded along with the document. You trigger an attachment to be downloaded locally to a device by calling this method. It will report changes to the status of the fetch attempt as it tries to download it. Assuming it succeeds in downloading the attachment it will call the onFetchEvent block with a completed event object, which will hold a reference to the attachment.
      Parameters:
      tokenMap - a Map representation of DittoAttachmentToken relevant to the attachment that you wish to download and observe.
      fetchProgressHandler - a DittoAttachmentFetchProgressHandler instance that will be called when there is an update relating to the attachment fetch progress.
      Returns:
      a CompletionStage, which can be used to cancel the fetching, or await the result. Otherwise, the fetch will remain active until it either completes, the attachment is deleted, or the owning Ditto object is closed.