Using the ORM

In the Using Controllers section you've learned how to setup and use the HTTP-Server and create routes. Now you'll learn how to retrieve data from a database using the ORM. To make things simple we'll assume that you use MySQL/MariaDB, so we need to include the database driver in our pom.xml.

<dependency>
    <groupId>mysql</groupId>
    <artifactId>mysql-connector-java</artifactId>
    <version>8.0.22</version>
</dependency>

After that we can start to instantiate the MySQL implementation and an ORMConfig.

SQL sql = new MySQL(
    "localhost", // The database host name
    3306,        // The database port
    "guide",     // The database name
    "root",      // The database user
    ""           // The database password
);

ORMConfig ormConfig = new ORMConfig()
    .setDefaultSize(255); // override the default VARCHAR size

As a next step we will create an abstract parent class just as we done for the Controller before, you can also skip this step, but its our recommended approach, so you can have all sorts of utilities available in all your models.

public abstract class Model extends org.javawebstack.orm.Model {
    // Add common methods to all your models
}

We can then put everything together and let the auto-discovery do the job for us.

ORM.register(Model.class.getPackage(), sql, ormConfig):

Creating a Model

Now we can start creating model classes for the data we want to work with.

public class User extends Model {
    @Column
    private int id;
    @Column(size = 50)
    private String name;
}

You might notice the Column annotation above each field of our new User model class. Those tell the ORM that those are columns in the database, giving you the ability to have unpersisted data in your models. You can also see the size parameter above the name, which will override the VARCHAR size or even switch to types like TEXT, there are also a few more options you can explore here.

Auto Migration

ORM.autoMigrate();

And thats it! The ORM will create the tables with all declared columns for you.

Creating data

User user = new User();
user.setName("example");
user.save();

You should now have a new table row in your database. Note that we didn't specify an id as the ORM will auto increment when using ints/longs and UUIDs if you rather want to have String keys.

Retrieving data

Now that we created a user in the database we also want to e.g. get all users or search by name. For this we will access the Repo of our User.

List<User> users = Repo.get(User.class).all();

The List will now be populated with all users in the database. Of course we can also create more complex queries and search our User by name.

User user = Repo.get(User.class).where("name", "example").first();

This query will do two things, first it will make a where statement to select users with the name being example. Second it will also limit the query to 1 result and give only one back, as you can see by the return type. You can find more about our powerful query builder here.