This post will tell you how we use a simple YAML file to insert the initial data (like roles, privileges, admin user, and all the other necessary data) into our database. We use Play! Framework (Java) with Hibernate. The important part is how we make Objects from the YAML description using SnakeYAML (Play framework’s integrated YAML parser) though.

I’ll give you some tricks on how to use YAML easily in order to create the initial data for your application.

‘Rules’ of YAML

NEVER use tabs in your YAML file. The YAML parser will throw a RuntimeException if there is even a single tab in your file.

Care for the file’s indent; the parser is indent sensitive.

I recommend you use 2-4 spaces.

YAML’s Similarity with JSON

YAML has the same expressivity as JSON. There are lots of online JSON to YAML and vice versa converters, so if you are not familiar with the YAML file format you can write your data in JSON and then convert it to YAML. Why is YAML better than JSON? I’ll explain it later in the ‘Comment’ & ‘Aliases’ sections, but first let’s take a look at what a YAML file looks like.

Usage

Comment

You can add comments to your file by adding a # at the beginning of the line

# This is a comment
This is not #but this is a comment again

As opposed to JSON, you can leave comments in YAML. Pretty handy 🙂

YAML elements

In a valid YAML file we can have lists (like a JSON Array), associative arrays (like a JSON Object), and scalars. I’ll call these just as they are in the JSON syntax to avoid further misunderstanding.

numbers:
  - 1
  - 2
  - 3

key1: "value1"
key2: "value2"
key3: "value3"

Connection with Java classes

If you want to tell the parser that your YAML object is an instance of your JAVA class, simply define its key as !!package.MyClass. The following example is a list of two users.

users:
  - !!models.User
    name: User1
    password: hashedPassword1
  - !!models.User
    name: User2
    password: hashedPassword2

Aliases

Aliases are good if you don’t want to copy-paste a lot of boilerplate code (for example, Roles, Privileges, Organization etc.). You can define an alias with the ‘&’ special character, and reference the alias later with the ‘*’ character.

privileges:
  - !!models.Privilege &adminPrivilege #Defining the adminPrivilege alias
    id: 1
    key: privilege.admin
  - !!models.Privilege &privilege1
    id: 2
    key: privilege.privilege1
  - !!models.Privilege &privilege2
    id: 3
    key: privilege.privilege2
roles:
  - !!models.Role &adminRole #Defining the adminRole alias
    id: 1
    key: role.admin
    privileges:
      - *adminPrivilege #Referring the adminPrivilege alias
  - !!models.Role &userRole
    id: 2
    key: role.user
    privileges:
      - *privilege1
      - *privilege2
users:
  - !!models.User
    id: 1
    loginName: SuperAdmin
    password: hashedPassword1
    roles:
      - *adminRole #Referring the adminRole alias
      - *userRole
  - !!models.User
    id: 2
    loginName: Admin
    password: hashedPassword2
    roles:
      - *adminRole #Referring the adminRole alias
  - !!models.User
    id: 3
    loginName: User
    password: hashedPassword3
    roles:
      - *userRole

IMPORTANT: This is why YAML is better than JSON – define once & use it all the time.

ALSO IMPORTANT: You can only back-refer with aliases, so you must define the alias before you use it.

Recursion with aliases

You can easily define recursion with aliases. Still note that you can only back-refer.

users:
  - !!models.User &adminUser
    id: 1
    loginName: Admin
    password: hashedPassword1
    organization:
      !!models.Organization
        users:
          - *adminUser

Enums

If you have the following enum for examle, you just refer to it in the YAML file by its name.

public enum UserStatusEnum {
   ACTIVE, INACTIVE
}

users:
  - !!models.User &adminUser
    id: 1
    loginName: Admin
    password: hashedPassword1
    status: ACTIVE

Store initial data into the DB

The following code snippet will do all the work for you. The only thing you have to care about is the order of the entity lists. If you want to store an entity that refers another, then you must store the referreditem first, and the referring after (but because of the aliases, this shouldn’t be a problem).

if(Privilege.size() == 0) { //to check if the DB is empty
    Map entityMap = (Map) Yaml.load("initial-data.yml");
    for(String key : entityMap.keySet()) {
        for(Object entity : entityMap.get(key)) {
            JPA.em().persist(entity);
        }
    }
}

Summing-it-up

As you see, YAML is an easy way to define your initial data for an application. You don’t need a lot of boiler plate code in your application to parse the YAML and insert the data into the DB, you only have to write the YAML file, and that’s why we love it!

Another way of using YAML

We have another post on using YAML as Swagger documentation, a Swagger doc is an easy way to define the interface between backend and frontend (web or mobile clients, too). I recommend you to take a look at that post too!