Entities

Entities are Java classes that map to database tables. Volt uses annotations to define how classes and fields correspond to tables and columns.

Annotations

@Entity

Marks a class as a database entity and specifies the table name using the value attribute.

@Entity("users")
public class User {
    // ...
}

@Identifier

Marks a field as the primary key. Configure whether it's auto-generated and its type.

@Identifier(type = PrimaryKeyType.NUMBER, generated = true)
private Long id;

Attributes:

Attribute	Type	Default	Description
type	PrimaryKeyType	required	The primary key type (NUMBER or UUID)
generated	boolean	true	Whether the key is auto-generated

Primary Key Types:

import me.oskarscot.volt.entity.PrimaryKeyType;

// Auto-incrementing numeric ID
@Identifier(type = PrimaryKeyType.NUMBER, generated = true)
private Long id;

// Application-generated UUID
@Identifier(type = PrimaryKeyType.UUID, generated = false)
private UUID id;

@NamedField

Maps a field to a column with a different name using the name attribute. Use this when your Java field name differs from the database column name.

@NamedField(name = "user_name")
private String username;

@NamedField(name = "created_at")
private LocalDateTime createdAt;

Complete Example

import me.oskarscot.volt.annotation.Entity;
import me.oskarscot.volt.annotation.Identifier;
import me.oskarscot.volt.annotation.NamedField;
import me.oskarscot.volt.entity.PrimaryKeyType;

@Entity("products")
public class Product {

    @Identifier(type = PrimaryKeyType.NUMBER, generated = true)
    private Long id;

    private String name;

    private String description;

    @NamedField(name = "unit_price")
    private BigDecimal unitPrice;

    @NamedField(name = "stock_quantity")
    private Integer stockQuantity;

    @NamedField(name = "created_at")
    private LocalDateTime createdAt;

    // Required: public no-arg constructor
    public Product() {}

    // Getters and setters
    public Long getId() { return id; }
    public void setId(Long id) { this.id = id; }

    public String getName() { return name; }
    public void setName(String name) { this.name = name; }

    // ... remaining getters/setters
}

UUID Primary Keys

For UUID-based primary keys:

@Entity("sessions")
public class Session {

    @Identifier(type = PrimaryKeyType.UUID, generated = false)
    private UUID id;

    @NamedField(name = "user_id")
    private Long userId;

    @NamedField(name = "created_at")
    private Instant createdAt;

    public Session() {}

    // Generate UUID before saving
    public static Session create(Long userId) {
        Session session = new Session();
        session.id = UUID.randomUUID();
        session.userId = userId;
        session.createdAt = Instant.now();
        return session;
    }
}

Supported Field Types

Volt supports common Java types out of the box:

• String
• Integer, int, Long, long, Double, double
• BigDecimal
• Boolean, boolean
• UUID
• Instant, LocalDate, LocalDateTime

For custom types, see Type Converters.

Requirements

Entity classes must:

1. Be annotated with @Entity
2. Have exactly one field annotated with @Identifier
3. Have a public no-arg constructor
4. Be registered with volt.registerEntity()

Planned Features

Coming Soon

• @OneToMany - One-to-many relationships
• @ManyToOne - Many-to-one relationships
• @Column - Additional column configuration (nullable, unique, etc.)