io.permazen.annotation.OnCreate Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of permazen-main Show documentation
Permazen classes that map Java model classes onto the core API.
There is a newer version: 5.1.0

/*
 * Copyright (C) 2015 Archie L. Cobbs. All rights reserved.
 */

package io.permazen.annotation;

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

/**
 * Annotates Permazen model class methods that are to be invoked whenever a database object is newly created.
 *
 * 
 * Note that there is a subtle distinction between (a) the creation of database objects in the database, and
 * (b) the instantiation of Java model objects that represent database objects (i.e., {@link io.permazen.JObject}s).
 * These two events do not occur at the same time; in particular, distinct Java model objects are instantiated to
 * represent the same database object in different transactions. In addition, it's even possible for a Java model
 * object to be instantiated when no corresponding database object exists in the database, e.g., via
 * {@link io.permazen.JTransaction#get(io.permazen.core.ObjId)}.
 *
 * 

 * Methods that are annotated with {@link OnCreate @OnCreate} are invoked only for events of type (a).
 * As a consequence, for any database fields that require default initialization, this initialization should be
 * performed not in a Java constructor but rather in an {@link OnCreate @OnCreate}-annotated method.
 *
 * 

 * For example, instead of this:
 * 
 *  @PermazenType
 *  public abstract class Event {
 *
 *      protected Event() {
 *          this.setCreateTime(new Date());
 *      }
 *
 *      @NotNull
 *      public abstract Date getCreateTime();
 *      public abstract void setCreateTime(Date createTime);
 *
 *      ...
 * 
 *
 * 
 * do this:
 * 
 *  @PermazenType
 *  public abstract class Event {
 *
 *      @OnCreate
 *      private void initializeCreateTime() {
 *          this.setCreateTime(new Date());
 *      }
 *
 *      @NotNull
 *      public abstract Date getCreateTime();
 *      public abstract void setCreateTime(Date createTime);
 *
 *      ...
 * 
 *
 * 
 * Notifications are delivered in the same thread that created the object, immediately after the object is created.
 *
 * 

 * The annotated method must be an instance method (i.e., not static), return void, and take zero parameters.
 * It may have any level of access, including {@code private}.
 *
 * 
Meta-Annotations
 *
 * 
 * This annotation may be configured indirectly as a Spring
 * meta-annotation
 * when {@code spring-core} is on the classpath.
 */
@Retention(RetentionPolicy.RUNTIME)
@Target({ ElementType.ANNOTATION_TYPE, ElementType.METHOD })
@Documented
public @interface OnCreate {

    /**
     * Determines whether this annotation should also be enabled for
     * {@linkplain io.permazen.SnapshotJTransaction snapshot transaction} objects.
     * If unset, notifications will only be delivered to non-snapshot (i.e., normal) database instances.
     *
     * @return whether enabled for snapshot transactions
     * @see io.permazen.SnapshotJTransaction
     */
    boolean snapshotTransactions() default false;
}