Define Entities

This page explains how to create a proper entity using worm's annotations. An entity is a Java class, most likely a data/model/POJO class. It contains attributes that are stored in the database.

The following annotations are (mostly) independent of the underlying database. Thus, exchanging the database technology without affecting the code is possible.

General Requirements

The entity must fulfill the following requirements:

• The class must have an empty constructor.
• The attribute fields must not be final.
• There must be exactly one attribute annotated with @Identifier.

Entity

First of all, every entity starts with a table. The annotation @Table defines the name of the storage location. For MySQL, the name refers to the actual SQL table name inside the database.

@Entity("persons")
public class Person {
  ...
}

Attributes

An attribute is defined by the annotation @Attribute("name"). If an attribute should be stored by worm, it must have this annotation.

Supported Types

Currently, the following data types are supported out-of-the-box (i.e., can be annotated with @Attribute):

• Boolean
• Byte, Short, Integer, Long
• Float, Double
• Enum
• String, UUID
• LocalDateTime
• Set, List, Map, Array

It is also possible to reference another entity (see References).

---

The behavior of attributes can be extended with the following annotations and functions. Be aware that the following annotations must be added to the annotation @Attribute.

Identifier

The annotation @Identifier declares an attribute as a unique identifier for an entity. Every entity must have exactly one identifier.

@Entity("persons")
public class Person {
  
  @Identifier
  @MaxLength(128)
  @Attribute("email")
  private String emailAddress;
}

ℹ️ If the identifier has the type String, it must have the annotation @MaxLength as well.

If your entity does not have a natural identifier, it can be automatically generated for you. Currently, the following generators are supported out of the box:

• IntegerGenerator
• UUIDGenerator

To use a generator, the field generator in the annotation @Identifier can be set to a generator class. For instance:

@Entity("cars")
public class Car {
  
  @Identifier(generator = UUIDGenerator.class)
  @Attribute("id")
  private UUID id;
}

Implementing a custom generator by implementing the interface ValueGenerator<T> is also possible.

References

Next to the basic types, it is possible to reference other entities. For instance, the object Car has a field owner of type Person that is also an entity.

@Entity("persons")
public class Person {
  ...
}

@Entity("cars")
public class Car {

  @Identifier(generator = UUIDGenerator.class)
  @Attribute("id")
  private UUID id;

  @Reference
  @Attribute("owner_email")
  private Person owner;

Now, if a Car is stored, worm automatically stores the before.

Time Zones

By default, timestamps of type LocalDateTime are stored as GMT timestamps. However, it is sometimes necessary to deal with timestamps in a given timezone. To avoid manual conversations, worm has the built-in annotation @TimeZone("Europe/Berlin") that converts the stored timestamp to the given timezone. The value refers to the converted time zone. If no timezone is given, the system's default timezone is chosen.

@Entity("rounds")
public class Round {
  
 ...

  @TimeZone("Europe/Berlin")
  @Attribute("start_time")
  private LocalDateTime startTime;

Creation and Update Timestamps

To automatically keep track of the creation timestamp and the last update, an attribute of type LocalDateTime can be annotated with @CreatedAt and @UpdatedAt. The value of these attributes is automatically set by worm.

@Entity("rounds")
public class Round {
  
  @TimeZone("Europe/Berlin")
  @Attribute("created_at")
  private LocalDateTime createdAt;

  @UpdatedAt
  @TimeZone("Europe/Berlin")
  @Attribute("updated_at")
  private LocalDateTime updatedAt;

Maximal Length

To ensure a maximal length of String, Arrays, and Collections, an attribute can be annotated with @MaxLength(4). If the value exceeds the given maximal length, an error is thrown, and the entity is not stored in the database.

@Entity("persons")
public class Person {
  
  @MaxLength(4)
  @Attribute("pin")
  private String pin;
}