Core Mapping Annotations

These annotations establish the structural bridge between the Java Virtual Machine and the relational schema.

• @Entity Target: ElementType.TYPE This annotation is mandatory for any class intended for full CRUD operations or relationship support. It marks the class as a managed domain object.
• @Table Target: ElementType.TYPE Optional if the class name matches the database table name. Use the name attribute to specify the exact table name when they differ.
• @PrimaryKey Target: ElementType.FIELD Designates the unique identifier for the entity. EzQu enforces a single-field primary key constraint.

• @Column Target: ElementType.FIELD Configures specific database column properties. This is required for schema generation or when mapping to non-standard column names.

Basic Annotated Entity Example:

@Entity
@Table(name = "SYSTEM_USERS")
public class User {
    @PrimaryKey(GeneratorType.IDENTITY)
    private Long id;

    @Column(name = "USER_NAME", length = 50, notNull = true, unique = true)
    private String username;

    @Column(enumType = Types.ENUM_INT) // Persists ordinal for performance private
    UserStatus status;

    @Column(sqlType = "java.sql.Clob")
    private String bio;
}

Relationship Mapping & Depth Control

EzQu supports four primary relationship mappings.

• @One2One: Defines a direct link. Defaults to Eager loading. Supports @Lazy and @Cascade(CascadeType.DELETE).
• @One2Many: Maps a collection. Defaults to Lazy loading.

• @Many2One: Used on the "many" side to fetch a parent entity. Often the inverse of an @One2Many. When One2Many is managed via FK it is not necessary to use this annotation (On many occasions this field won't even exist). This annotation should only be used with relation tables.
• @Many2Many: Defines a many-to-many link via a join table. These relationships are always two-sided and always use lazy loading.

Complex Relationship Example

@Entity
public class Project {
    @PrimaryKey(GeneratorType.SEQUENCE, seqName = "PROJ_SEQ")
    private Long id; // Ordered O2M relationship using a relation table

    @One2Many(joinTableName = "PROJ_TASK_LINK", relationFieldName = "PROJ_ID", childType = Task.class, orderBy = "priority", direction = "DESC")
    private List<Task> tasks;
}

Inheritance Mapping

EzQu supports two inheritance strategies. Developers MUST use @Inherited on the child entity to define the strategy.

• @Inheritence: Used to mark the inheritance strategy to be used for an object graph when persisting it to the underlying RDBMS. Set the annotation on the root class of the object graph

• @MappedSuperclass : Applied to abstract classes to prevent EzQu from creating a dedicated table for the superclass.
• @Inherited: Use on an inherited class when the inheritence strategy is Table per class.
• @Discriminator : Use this annotation when your entity is a child type in an inheritance graph and the inheritence strategy is discriminator, to define the discriminator for this class. No need to use the {@link Inherited} annotation.

Advanced Field Control

• @Cascade: Used on One2One relations when you want cascade delete behavior when deleting the Entity
• @Lazy: Used on One2One relationships you want to lazy load.
• @RelationTypes: Used on One2One relations when the related entity type is 'abstract' and you need to tell EzQU which child classes to except.
• @Converter: Bridges custom Java types and DB types. Requires a class implementing EzquConverter. There are some default converters a developer can use in com.centimia.orm.ezqu.converter package.
• @Version: Enables optimistic concurrency. Applied to Long or Integer fields. EzQu will throw an EzquConcurrencyException if a version mismatch occurs during update.
• @Transient: Fields ignored by EzQu but visible to standard serialization. (Note: Java transient keyword is ignored by both).
• @Extension: Fields only populated via "extended select" queries.

private class Person {
    @PrimaryKey(GenerationType = GenerationType.IDENTITY)
    private Long id;

    private String firstName;

    private String lastName;

    @Extension
    private String fullName;

    public Person() {}
        ... Getters and Setters
    }
}

normal work with Person object will not populate fullName, it will simply be ignored. But you can do this:

List<Person> res = factory.getFromSession(select -> {
    Person p = new Person();
    select.from(p).where(p.getId()).is(3).select(new Person() {
        {
            id = p.getId();
            firstName = p.getFirstName();
            lastName = p.getLastName();
            fullName = Function.concat(select, null, p.getFirstName(), " ", p.getLastName());
        }
    });
});

Here is another example:

@Entity
public class Account {

    @PrimaryKey
    private Long id;

    private Double credit;

    private Double rate;

    @Extension
    private Double interest;

    // Getters and setters omitted for brevity
}

Account a = sessionFactory.getFromSession(select -> {
    Account desc = new Account();
    select.from(desc).primaryKey().is(4L).selectFirst(new Account() {
        {
            id = desc.getId();
            credit = desc.getCredit();
            rate = id * credit;
        }
    });
});

• @Generated: Marks fields that get their value via calling a sequence or identity type.

Caching, Mutability, and Indexing

Immutability effects two things.

• @Immutable: The multiCallCache holds objects in cache between db calls within the same session. The multi cache makes fetching of data more efficient, because what was fetched before is held in cache and is not fetched again, also it makes sure that the same object instance is always fetched within the same session and thus, if a change is applied to that object during the session it will reflect in all other objects that hold a relation to it. i.e. if we fetch an entity 'A' that holds a relationship with entity 'C' and ina nother call in the same session we fetch entity 'B' wich also holds a relationship to the same 'C' we will get tge same 'C' instance.
  
  Sometimes this creates issues and ezQu will throw an exception stating it found two instances of the same entity in the session. While this is something that usually the developer should take care of, there are cases when this behavior should not be applied because the related entity is actually immutable and can not change, thus having different instances does not matter.
  @Immutable annotation should be put on such Entites to tell ezQu just that, and allow multi instances.
• @NoUpdateOnSave: Instructs EzQu to skip updates for related objects in O2O relations, assuming they already exist.
• @Index: This is a creational annotation, valid only if EzQu generates the table. It allows the creation of an index in the database

• @Indices: This is a creational annotation, valid only if EzQu generates the table. When creating more then one @Index.

Lifecycle Interceptors

• @Interceptor: apply the annotation to an entity. The referenced class MUST implement CRUDInterceptor.
  
  • onInsert(K entity): Before DB insertion.
  • onMerge(K entity): Before a merge (insert-or-update) operation.
  • onUpdate(K entity): Before DB update.
  • onDelete(K entity): Before DB deletion.