Interface DatabaseProvider

public interface DatabaseProvider
Represents a provider for databases. A database in CloudNet might better be known as a table (SQL) or collection (MongoDB). Therefore, a database provider represents a collection of databases, also known as a Database (SQL/MongoDB).

Every database must have a unique name which is case-sensitive. When retrieving a database there is no difference between a database which runs externally or a database which is embedded. The creation of a new database (if required) should be executed when retrieving the database object. For remote databases (retrieval while not being on a node component) the create operation can be executed when the database is used for the first time. Therefore, the method database(String) should never suspend the calling thread.

Deleting a database must remove all key-value pairs which are stored in the database. There is no guarantee that a database request/delete is directly visible to all components in the cluster as stated in Database.

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.

Since:
4.0
See Also:

  • Method Details

    • database

      @NonNull @NonNull Database database(@NonNull @NonNull String name)
      Retrieves or creates non-blocking a facade for a database to write and read data to. The name of the database should be unique for later identification.
      Parameters:
      name - the unique name of the database.
      Returns:
      a facade for a database to write and read data to.
      Throws:
      NullPointerException - if name is null.

    • containsDatabase

      boolean containsDatabase(@NonNull @NonNull String name)
      Checks whether the database with the given name already exists. When a call to database(String) is made there is no requirement for the database to get created.
      Parameters:
      name - the name of the database to check.
      Returns:
      true if a database with the given name exists, false otherwise.
      Throws:
      NullPointerException - if name is null.

    • deleteDatabase

      boolean deleteDatabase(@NonNull @NonNull String name)
      Deletes the database with the given name, removing all data which was previously stored in it.
      Parameters:
      name - the name of the database to remove.
      Returns:
      true if the database was deleted and all data in it got dropped, false otherwise
      Throws:
      NullPointerException - if name is null.

    • databaseNames

      @NonNull @NonNull Collection<String> databaseNames()
      Retrieves all names of all top-level existing databases. When a call to database(String) is made there is no requirement for the database to get created.
      Returns:
      all names of all top-level existing databases.

    • containsDatabaseAsync

      @NonNull @NonNull CompletableFuture<Boolean> containsDatabaseAsync(@NonNull @NonNull String name)
      Checks whether the database with the given name already exists. When a call to database(String) is made there is no requirement for the database to get created.

      The returned future, if completed successfully, completes with true to indicate that the database with the given name already exists and with false if either the lookup failed or the database does not exist.

      Parameters:
      name - the name of the database to check.
      Returns:
      a future completed with the existence status of the database.
      Throws:
      NullPointerException - if name is null.

    • deleteDatabaseAsync

      @NonNull @NonNull CompletableFuture<Boolean> deleteDatabaseAsync(@NonNull @NonNull String name)
      Deletes the database with the given name, removing all data which was previously stored in it.

      The returned future, if completed successfully, completes with true to indicate that the database with the given name was removed successfully and all stored data in it was removed and with false if either the deletion failed or the database does not exist.

      Parameters:
      name - the name of the database to remove.
      Returns:
      a future completed with the deletion result of the database.
      Throws:
      NullPointerException - if name is null.

    • databaseNamesAsync

      @NonNull @NonNull CompletableFuture<Collection<String>> databaseNamesAsync()
      Retrieves all names of all top-level existing databases. When a call to database(String) is made there is no requirement for the database to get created.

      The returned future, if completed successfully, completes with a collection of all existing top-level database names or with an empty collection if either the query failed or no databases are existing.

      Returns:
      a future completed with a collection of all database names.