io.permazen.annotation.PermazenListField 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.
The newest version!

/*
 * 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;

/**
 * Java annotation for the getter methods of Java bean properties reflecting {@link java.util.List} fields.
 *
 * 
 * The annotated method's return type must be {@link java.util.List List}{@code }, where {@code E} is a supported simple type.
 *
 * 

 * List fields have a "random access" performance profile similar to an {@link java.util.ArrayList}. In particular,
 * {@link java.util.List#get List.get()} and {@link java.util.List#size List.size()} are constant time, but an insertion
 * in the middle of the list requires shifting all subsequent values by one.
 *
 * 

 * Note that both primitive types and their corresponding wrapper types are supported as elements. A list whose
 * elements have primitive type will throw an exception on an attempt to add a null value.
 * To specify a primitive element type, specify the primitive type name (e.g., {@code "int"}) as the {@link PermazenField#encoding}
 * in the {@link #element}.
 *
 * 
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 PermazenListField {

    /**
     * The name of this field.
     *
     * 

     * If empty string (default value), the name is inferred from the name of the annotated Java bean getter method.
     *
     * @return the list field name
     */
    String name() default "";

    /**
     * Storage ID for this field.
     *
     * 

     * 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 contained class.
     *
     * @return the field's storage ID, or zero for automatic assignment
     */
    int storageId() default 0;

    /**
     * Configuration for the field's elements.
     *
     * 
     * Normally this property only needs to be set to index the sub-field.
     * If set, the {@link PermazenField#name name} property must be left unset.
     *
     * @return configuration for the list element sub-field
     */
    PermazenField element() default @PermazenField();
}