Interface Database

All Superinterfaces:
AutoCloseable, Named
public interface Database extends Named, AutoCloseable
Represents a database in the CloudNet. A database might be better known as a table (SQL) or collection (MongoDB). CloudNet uses a database to store values mapped to a key. A key must be unique within the database but can be overridden when a new value should get associated with a previously existing key. Every key is case-sensitive.

A database object can be obtained using DatabaseProvider.database(String) and should never be instantiated directly (may lead to unexpected behaviour when using the database).

Furthermore, there is no guarantee that writes to a database are synced directly into the cluster. You can verify if an operation will be directly visible to all nodes by calling synced(). If the method returns false either the server owner should consider changing to a solution which syncs instantly in the cluster, or you might run into synchronization problems when operating on the same data from different nodes.

Warning: In normal cases it is not recommended using the CloudNet database system for all of your data. The system will just write the value document as a plain string into the database which might lead to problems with some databases which are unable to handle such a mass of data. On the other hand it is much easier to use another structure if you want to randomly access single data fields instead of always accessing the hole chunk of data stored in the database.

Note: Great care must be taken when trying to read all values or key-value pairs from a database. The operation might take a while and for components which are not a node they need to get transferred over the network. Same thing applied for searches based on an entry in the database. These searches are not deep, meaning that you can only search reliably for top level entries in the value json rather than nested searches.

Since:
4.0
See Also:

  • Method Details

    • insert

      boolean insert(@NonNull @NonNull String key, @NonNull @NonNull Document document)
      Associates the given key with the given document in the database. A key should be unique for later identification when trying other operations on the key like read or remove. If the key already exists it will get overridden.
      Parameters:
      key - the unique key for the document.
      document - the document to associate with the key.
      Returns:
      true if the document was associated with the key successfully, false otherwise.
      Throws:
      NullPointerException - if either key or document is null.

    • contains

      boolean contains(@NonNull @NonNull String key)
      Tests whether a document is associated with the given key.
      Parameters:
      key - the key to check.
      Returns:
      true if the database contains the given key, false otherwise.
      Throws:
      NullPointerException - if key is null.

    • delete

      boolean delete(@NonNull @NonNull String key)
      Removes the key and the associated document from the database.
      Parameters:
      key - the key to remove.
      Returns:
      true if the key and document were removed from the database, false otherwise.
      Throws:
      NullPointerException - if key is null.

    • get

      @Nullable @Nullable Document get(@NonNull @NonNull String key)
      Gets the associated document with the given key from the database. If the returned document is null than there is no document associated with the given key.
      Parameters:
      key - the key of the document to get.
      Returns:
      the document associated with the key or null if there is no document associated with the key.
      Throws:
      NullPointerException - if key is null.

    • find

      @NonNull @NonNull Collection<Document> find(@NonNull @NonNull String fieldName, @Nullable @Nullable String fieldValue)
      Searches for all entries in the database which value contains the given field and the field value matches the given value. Null as the field value is permitted and will be used as literally null. The search is not deep meaning that you can only reliably search for top-level value mappings, nested types might work but will most likely not.
      Parameters:
      fieldName - the name of the field which the document value must contain.
      fieldValue - the value of the field which the document must have. Null is valid.
      Returns:
      all documents in the database which contain the given field mapped to the given field value.
      Throws:
      NullPointerException - if fieldName is null.

    • find

      @NonNull @NonNull Collection<Document> find(@NonNull @NonNull Map<String,String> filters)
      Searches for all entries in the database which contain each entry of the provided map. Null as a field value is permitted and will be used as literally null. The search is not deep meaning that you can only reliably search for top-level value mappings, nested types might work but will most likely not.
      Parameters:
      filters - the map containing the key-value pairs which the searched database document must contain.
      Returns:
      all documents in the database which contain all key-value mappings of the filter document.
      Throws:
      NullPointerException - if filters is null.

    • keys

      @NonNull @NonNull Collection<String> keys()
      Get all keys which are currently stored and mapped to a document in the database. This operation might be heavy when querying a huge database.
      Returns:
      all keys stored in the database.

    • documents

      @NonNull @NonNull Collection<Document> documents()
      Get all values which are currently stored and mapped to a key in the database. This operation might be heavy when querying a huge database.
      Returns:
      all documents stored in the database.

    • entries

      @NonNull @NonNull Map<String,Document> entries()
      Get all key-value pairs which are currently stored in the database. This operation might be heavy when querying a huge database.
      Returns:
      all key-value pairs stored in the database.

    • clear

      void clear()
      Removes all key-value pairs which are currently stored in the database. This operation will not remove the database.

    • documentCount

      long documentCount()
      Get the amount of key-value pairs currently stored in the database.
      Returns:
      the amount of key-value pairs in the database.

    • synced

      boolean synced()
      Gets if this database is synced to the cluster. This means that every change made to the database will be directly visible to all components in the cluster rather than requiring a special sync. Normally synced databases are databases which are running as an external process, like MySQL or MongoDB.
      Returns:
      true if all modify operations are directly visible to all components in a cluster, false otherwise.

    • insertAsync

      @NonNull @NonNull CompletableFuture<Boolean> insertAsync(@NonNull @NonNull String key, @NonNull @NonNull Document document)
      Associates the given key with the given document in the database. A key should be unique for later identification when trying other operations on the key like read or remove. If the key already exists it will get overridden.

      The returned future, if completed successfully, completes with true to indicate that the value was written into the database successfully. Will be completed with false if the data wasn't written without specifying a reason.

      Parameters:
      key - the unique key for the document.
      document - the document to associate with the key.
      Returns:
      a future completed with the write operation status.
      Throws:
      NullPointerException - if either key or document is null.

    • containsAsync

      @NonNull @NonNull CompletableFuture<Boolean> containsAsync(@NonNull @NonNull String key)
      Tests whether a document is associated with the given key.

      The returned future, if completed successfully, completes with true to indicate that the database contains the given key and with false to indicate that either the database does not contain the given key or the lookup failed without giving a reason for that.

      Parameters:
      key - the key to check.
      Returns:
      a future completed with the lookup status when completed.
      Throws:
      NullPointerException - if key is null.

    • deleteAsync

      @NonNull @NonNull CompletableFuture<Boolean> deleteAsync(@NonNull @NonNull String key)
      Removes the key and the associated document from the database.

      The returned future, if completed successfully, completes with true to indicate that the database no longer contains a mapping for the given key and with false to indicate that there was an issue removing the key from the database without specifying a reason.

      Parameters:
      key - the key to remove.
      Returns:
      a future completed with the removal status of the given key.
      Throws:
      NullPointerException - if key is null.

    • getAsync

      @NonNull @NonNull CompletableFuture<Document> getAsync(@NonNull @NonNull String key)
      Gets the associated document with the given key from the database. If the returned document is null than there is no document associated with the given key.

      The returned future, if completed successfully, completes with the document mapped to the given key in the database and with null if either the lookup in the database failed or no document in the database is associated with the given key.

      Parameters:
      key - the key of the document to get.
      Returns:
      a future completed with the document associated with the given key.
      Throws:
      NullPointerException - if key is null.

    • findAsync

      @NonNull @NonNull CompletableFuture<Collection<Document>> findAsync(@NonNull @NonNull String fieldName, @Nullable @Nullable String fieldValue)
      Searches for all entries in the database which value contains the given field and the field value matches the given value. Null as the field value is permitted and will be used as literally null. The search is not deep meaning that you can only reliably search for top-level value mappings, nested types might work but will most likely not.

      The returned future, if completed successfully, completes with a collection of documents which are all matching the given field key/value matcher or with an empty collection if either the lookup failed or the database does not contain any document matching the field key/value.

      Parameters:
      fieldName - the name of the field which the document value must contain.
      fieldValue - the value of the field which the document must have. Null is valid.
      Returns:
      a future completed with all documents matching the given field key/value.
      Throws:
      NullPointerException - if fieldName is null.

    • findAsync

      @NonNull @NonNull CompletableFuture<Collection<Document>> findAsync(@NonNull @NonNull Map<String,String> filters)
      Searches for all entries in the database which contain each entry of the provided map. Null as a field value is permitted and will be used as literally null. The search is not deep meaning that you can only reliably search for top-level value mappings, nested types might work but will most likely not.

      The returned future, if completed successfully, completes with a collection of documents which are all matching the given filters or with an empty collection if either the lookup failed or the database does not contain any document matching the given filters.

      Parameters:
      filters - the map containing the key-value pairs which the searched database document must contain.
      Returns:
      a future completed with all documents matching the given filters.
      Throws:
      NullPointerException - if filters is null.

    • keysAsync

      @NonNull @NonNull CompletableFuture<Collection<String>> keysAsync()
      Get all keys which are currently stored and mapped to a document in the database. This operation might be heavy when querying a huge database.

      The returned future, if completed successfully, completes with a collection of all keys which are currently stored in the database or an empty collection if the lookup failed or the database does not contain any keys.

      Returns:
      a future completed with all keys which are currently stored in the database.

    • documentsAsync

      @NonNull @NonNull CompletableFuture<Collection<Document>> documentsAsync()
      Get all values which are currently stored and mapped to a key in the database. This operation might be heavy when querying a huge database.

      The returned future, if completed successfully, completes with a collection of all documents which are currently stored in the database or an empty collection if the lookup failed or the database does not contain any documents.

      Returns:
      a future completed with all documents which are currently stored in the database.

    • entriesAsync

      @NonNull @NonNull CompletableFuture<Map<String,Document>> entriesAsync()
      Get all key-value pairs which are currently stored in the database. This operation might be heavy when querying a huge database.

      The returned future, if completed successfully, completes with all key-value pairs which are currently stored in the database or an empty collection if the lookup failed or the database does not contain anything.

      Returns:
      a future completed with all key-value pairs currently stored in the database.

    • clearAsync

      @NonNull @NonNull CompletableFuture<Void> clearAsync()
      Removes all key-value pairs which are currently stored in the database. This operation will not remove the database.

      The returned future is just for listening reasons and has no special return value. It will always get completed with null.

      Returns:
      a future completed when the operation took place.

    • documentCountAsync

      @NonNull @NonNull CompletableFuture<Long> documentCountAsync()
      Get the amount of key-value pairs currently stored in the database.

      The returned future, if completed successfully, completes with the amount of key-value pairs currently stored in the database or 0 if the lookup failed or the database does not contain anything.

      Returns:
      a future completed with the amount of documents currently stored in the database.