io.permazen.annotation.PermazenMapField 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 io.permazen.Permazen;

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 Permazen} {@link java.util.Map} fields.
 *
 * 
 * The annotated method's return type must be either {@link java.util.Map Map}{@code },
 * {@link java.util.SortedMap SortedMap}{@code }, or {@link java.util.NavigableMap NavigableMap}{@code },
 * where {@code K} and {@code V} are supported simple types.
 *
 * 

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

    /**
     * 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 map 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 keys.
     *
     * 

     * 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 map key sub-field
     */
    PermazenField key() default @PermazenField();

    /**
     * Configuration for the field's values.
     *
     * 
     * 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 map value sub-field
     */
    PermazenField value() default @PermazenField();
}