com.kenshoo.pl.entity.annotation.audit.Audited Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of persistence-layer Show documentation
A Java persistence layer based on JOOQ for high performance and business flow support.
There is a newer version: 0.1.121-jooq-3.16.3
package com.kenshoo.pl.entity.annotation.audit;

import com.kenshoo.pl.entity.audit.AuditTrigger;
import com.kenshoo.pl.entity.spi.audit.AuditExtensions;
import com.kenshoo.pl.entity.spi.audit.AuditExtensions.EmptyAuditExtensions;
import com.kenshoo.pl.entity.spi.audit.AuditFieldValueFormatter;
import com.kenshoo.pl.entity.spi.audit.AuditFieldValueFormatter.MissingAuditFieldValueFormatter;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

import static com.kenshoo.pl.entity.audit.AuditTrigger.ON_CREATE_OR_UPDATE;

/**
 * Whenever an entity or field has this annotation, it indicates that any changes to the entity / field
 * will be published (by the publisher belonging to the PersistenceLayer instance).

 *     When the entity-level is annotated, it implies that all fields should also be annotated unless overriden by {@link NotAudited} on the field.
 */
@Target({ElementType.TYPE, ElementType.FIELD})
@Retention(RetentionPolicy.RUNTIME)
public @interface Audited {

    /**
     * @return the name to use for the annotated type (entity or field) when audited.

     * If empty or missing, will default to the name already defined for this type, as follows:
     * 
     *     Entity: {@code EntityType.getName()}
     *     Field: The result of {@code toString()} on the field, which retrieves the name by reflection
     * 
     */
    String name() default "";

    /**
     * @return the formatter to use for field values when they are audited.
     * 
     * If defined at the entity level, will apply to all fields in the entity (unless overriden).
     * 
If defined at the field level, will apply to that field while overriding any definition (if exists) at the entity level
     * 
If missing at both levels, will default to {@link com.kenshoo.pl.entity.spi.audit.DefaultAuditFieldValueFormatter}
     * 
     */
    Class valueFormatter() default MissingAuditFieldValueFormatter.class;

    /**
     * @return the rule by which to trigger auditing for the annotated entity type or field.

     * This attribute is valid for field-level annotations only, and will be ignored if appearing on entities.

     * For the entity-level,{@link AuditTrigger#ON_CREATE_OR_UPDATE} is implied always.
     */
    AuditTrigger trigger() default ON_CREATE_OR_UPDATE;

    /**
     * By default, virtual fields will not be audited (even if the entity or field are annotated with a plain '@Audited').

     * This to avoid redundant auditing of the same data, in case the underlying field(s) are also audited.

     * This behavior can be overriden, forcing the auditing of a virtual field - by setting this attribute to {@code true}.

     * This attribute is valid for field-level annotations only, and will be ignored if appearing on entities
     * (so that it's not applied by accident too broadly).

     *
     * @return {@code true} if the annotated field should be audited even if it's virtual

     *         {@code false} otherwise
     */
    boolean allowVirtual() default false;

    /**
     * NOTE: This attribute is valid for entity-level annotations only, and will be ignored if appearing on fields.
     * @return extensions to the basic audit data that will be generated for the annotated entity type.

     * This attribute is valid for entity-level annotations only, and will be ignored if appearing on fields.
     * @see AuditExtensions
     */
    Class extensions() default EmptyAuditExtensions.class;
}