Package io.permazen.annotation

Annotation Interface PermazenType

@Retention(RUNTIME) @Target({ANNOTATION_TYPE,TYPE}) @Documented public @interface PermazenType
Java annotation for Java classes that represent Permazen database object types.

Model classes may be POJO's, abstract classes, or interfaces, and the Java bean getter methods therein define database fields; Permazen generates concrete subclasses of each model class at runtime. Non-interface model classes must have a zero-arg constructor with at least protected access.

The following annotations on the getter methods of a @PermazenType-annotated class configure database fields:

By default, database fields are created automatically for all abstract getter methods, so no annotations are required. To override the defaults, or define database fields for non-abstract getter methods, add the appropriate @PermazenField, @PermazenSetField, @PermazenListField, or @PermazenMapField annotation.

These annotations are also supported on the methods in a @PermazenType-annotated class:

  • @OnChange - annotates a method to be invoked when some field (possibly seen through a path of references) changes
  • @OnCreate - annotates a method to be invoked just after object creation
  • @OnDelete - annotates a method to be invoked just prior to object deletion
  • @OnValidate - annotates a method to be invoked whenever the object is (re)validated
  • @OnSchemaChange - annotates a method to be invoked when the object's schema changes
  • @ReferencePath - annotates a method returning objects found by traversing a path of reference fields

Annotations are "inherited", meaning they may be present on any overridden supertype method, including methods in superclasses and superinterfaces (whether or not annotated with @PermazenType).

PermazenObject interface

The subclass of any @PermazenType-annotated model class that is generated by Permazen will implement PermazenObject, so the (abstract) model classes may be declared that way.

Indexing

Indexes on simple fields and collection fields are declared via PermazenField.indexed().

Composite indexes are declared by annotating any supertype of a @PermazenType-annotated class with one or more @PermazenCompositeIndex annotations.

Singletons

A database type intended to be a singleton can be marked with singleton() = true, which means that at most one instance of the type may exist. Similar to PermazenField.unique(), singleton() functions as an implicit validation constraint: the requirement is verified when the validation queue is processed, and it is affected by the transaction's configured ValidationMode.

Meta-Annotations

This annotation may be configured indirectly as a Spring meta-annotation when spring-core is on the classpath.

  • Element Details

    • name

      String name
      The name of this object type.

      If equal to the empty string (default value), the simple name of the annotated Java class is used.

      Returns:
      object type name
      Default:
      ""

    • storageId

      int storageId
      Storage ID for this object type.

      Normally this value is left as zero, in which case a value will be automatically assigned.

      Otherwise, the value should be positive and unique within the schema.

      Returns:
      this object type's storage ID, or zero for automatic assignment
      Default:
      0

    • autogenFields

      boolean autogenFields
      Whether to automatically generate database fields from un-annotated abstract Java bean methods.

      If true, database fields will be auto-generated corresponding to all abstract bean property getter methods, even if there is no @PermazenField, @PermazenSetField, @PermazenListField, or @PermazenMapField annotation. Note this includes superclass and interface methods. Methods must be either public or protected. In the case of simple fields, there must also be a corresponding setter method.

      Getter methods with return type assignable to Set, List, and Map will cause the corresponding collection fields to be created; other getter/setter method pairs will cause the corresponding simple fields to be generated.

      A @PermazenTransient annotation on the getter method, or any overridden superclass method, disables this auto-generation for that particular method (this is only useful when applied to non-abstract methods, and therefore when autogenNonAbstract() is true: if applied to any abstract methods, the auto-generated database subclass wouldn't be instantiable at runtime).

      Returns:
      whether to auto-generate fields from abstract methods
      See Also:
      Default:
      true

    • autogenNonAbstract

      boolean autogenNonAbstract
      Whether to automatically generate database fields even from non-abstract Java bean methods.

      If autogenFields() is false, this property is ignored. Otherwise, database fields will be auto-generated corresponding to all bean property getter methods, whether or not marked abstract, unless there is a @PermazenTransient annotation.

      Returns:
      whether to auto-generate fields from non-abstract methods when autogenFields() is true
      See Also:
      Default:
      false

    • autogenAllowDeleted

      boolean autogenAllowDeleted
      Configure the default for the @PermazenField.allowDeleted() property for auto-generated reference fields.

      If autogenFields() is false, this property is ignored. Otherwise, if this property is true, any auto-generated reference fields will allow assignment to deleted objects in normal transactions. In other words, they will behave as if they had a @PermazenField annotation with PermazenField.allowDeleted() set to true.

      Returns:
      whether auto-generated reference fields should allow assignment to a deleted object in normal transactions
      See Also:
      Default:
      false

    • autogenUpgradeConversion

      UpgradeConversionPolicy autogenUpgradeConversion
      Configure the default for the @PermazenField.upgradeConversion() property for auto-generated reference fields.

      If autogenFields() is false, this property is ignored. Otherwise, any auto-generated fields will have the specified UpgradeConversionPolicy applied when upgrading an object from some other schema to the current schema.

      Returns:
      type conversion policy for auto-generated fields
      See Also:
      Default:
      ATTEMPT

    • singleton

      boolean singleton
      Determine if there should only be one instance of this type.

      If this is true, then an implicit validation constraint is added requiring that at most one instance exist.

      Returns:
      true if this is a singleton type
      Default:
      false

    • schemaEpoch

      int schemaEpoch
      SchemaModel schema ID hash epoch.

      This value is included as input to the hash function used by SchemaSupport.getSchemaId(). Therefore, modifying this value will force a schema change, and therefore a subsequent "dummy" migration of all database objects the next time they are accessed, even if there are no other changes to the schema.

      This can be useful (for example) when you want to force revalidation of all instances of the annotated type on the next access, because revalidation is a side effect of a schema migration.

      Returns:
      schema epoch
      See Also:
      Default:
      0