org.jsimpledb.annotation.OnCreate Maven / Gradle / Ivy

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

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

package org.jsimpledb.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 JSimpleDB 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 org.jsimpledb.JObject}s).
 * These two events do not necessarily always occur at the same time. Methods that are annotated with
 * {@link OnCreate @OnCreate} are invoked only for event (a). In particular, Java model objects are frequently
 * instantiated to represent database objects that already exist in the database. Also, it's possible for a Java model
 * object to be instantiated when no corresponding database object exists in the database (e.g., via
 * {@link org.jsimpledb.JTransaction#get(org.jsimpledb.core.ObjId)}).
 *
 * 

 * 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:
 * 
 *  @JSimpleClass
 *  public abstract class Event {
 *
 *      protected Event() {
 *          this.setCreateTime(new Date());
 *      }
 *
 *      public abstract Date getCreateTime();
 *      public abstract void setCreateTime(Date createTime);
 *
 *      ...
 * 
 * do this:
 *
 *  *  @JSimpleClass
 *  public abstract class Event {
 *
 *      protected Event() {
 *      }
 *
 *      @OnCreate
 *      private void init() {
 *          this.setCreateTime(new Date());
 *      }
 *
 *      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}.
* 
*/
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
@Documented
public @interface OnCreate {

    /**
     * Determines whether this annotation should also be enabled for
     * {@linkplain org.jsimpledb.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 org.jsimpledb.SnapshotJTransaction
     */
    boolean snapshotTransactions() default false;
}