C. Installation & Quickstart in 5 minutes

Run the NDatabase plugin (Bukkit / Spigot)

1. Put the NDatabase plugin in your /plugins folder. You can build the jar yourself or download the latest release HERE
2. (Optional) start your server and edit your /plugins/NDatabase/config.yml as your needs and what database your are using. By default, the configuration is set to a SQLITE implementation, so this is very useful if you want to develop your plugin without deploying a database.

Show config file

# Your database type
# - SQLITE (default)
# - MYSQL
# - MONGODB (Recommended)
database-type: SQLITE

# Print all operations inside the database in the console with the value formatted as Json
debug-mode: false

# The number of thread that will be used for your async database call
# If you are using MySQL, I would advice to set the same number as "minimum idle connection"
# In the case were you have more than 3 running operation, extra thread will be created temporarily
idle-thread-pool-size: 3

database:
  mysql:

    # Full host path containing host:port/database_name
    # exemple: jdbc:mysql://localhost:3306/ndatabase
    host: 'jdbc:mysql://localhost:3306/your_database_name'
    user: ''
    pass: ''

    # Depending on your MySQL version or fork, you may want to change the driver
    # default com.mysql.jdbc.Driver
    driver-class-name: 'com.mysql.jdbc.Driver'

    # Set the minimum constantly opened connection with your database
    # note that the number of plugin won't multiply this number
    # so you can config this number according to your needs
    minimum-idle-connection: 3

    # Maximum number of connection in the pool
    maximum-pool-size: 10
  sqlite:

    # File generated in your plugins/NDatabase/sqlite folder that will contain your database
    file-name: 'ndatabase.sqlite'

  mongodb:

    host: 'localhost'

    # Database name
    database: ''
    port: 27017
    user: ''
    pass: ''

Once the NDatabase plugin is running on your server, you are good to go and you can use the API in any of your plugins without reconfiguring a database.

Add dependency to your project

Show Gradle

allprojects {
    repositories {
        ...
        maven { url 'https://jitpack.io' }
    }
}
dependencies {
    compileOnly 'com.github.NivixX.NDatabase:ndatabase-api:1.0.0'
}

Show Maven

<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>

<dependency>
    <groupId>com.github.NivixX.NDatabase</groupId>
    <artifactId>ndatabase-api</artifactId>
    <version>1.0.0</version>
    <scope>provided</scope>
</dependency>

Define your data model

First let's define our data model, you just have to create a class which extends NEntity<K> where K is the type of your key, currently UUID, String, Long, Integer types are supported.

@NTable(name = "player_statistics", schema = "", catalog = "")
public class PlayerStatsDTO extends NEntity<UUID> {

    @JsonProperty("killCount")
    private int kills;

    @JsonProperty("deathCount")
    private int deaths;

    @JsonProperty("lastLocation")
    private SerializedLocation lastLocation;

    // ... with getters / setters

    // Note that you need a default constructor as the Framework will use it
    public PlayerStatsDTO() { }
}

Define your table name with the @NTable annotation, only the name is mandatory, you can choose to not specify a schema or catalog.

Behind the scene, NDatabase will convert your object to a JSON, it's optional, but I recommend specifying the field name with the @JsonProperty annotation, because your schema will still work even if you change your variable name.

Last but not least, you can embed other objects inside your data model. Every object must be Serializable, so for instance, you cannot store a Bukkit.Location object as it is linked to your minecraft server domains context, which is volatile. I recommend you to check the Data model design best practices section to know best practices and domain<>dto separation.

It's done and ready to use !

Repository<UUID, PlayerStatsDTO> repository = NDatabase.api().getOrCreateRepository(PlayerStats.class);

You can now use your repository for all your CRUD operations and queries. You don't have to create any repository class yourself. See repository usage : Repository api usage