001/*
002 *  Copyright 2001-2013 Stephen Colebourne
003 *
004 *  Licensed under the Apache License, Version 2.0 (the "License");
005 *  you may not use this file except in compliance with the License.
006 *  You may obtain a copy of the License at
007 *
008 *      http://www.apache.org/licenses/LICENSE-2.0
009 *
010 *  Unless required by applicable law or agreed to in writing, software
011 *  distributed under the License is distributed on an "AS IS" BASIS,
012 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 *  See the License for the specific language governing permissions and
014 *  limitations under the License.
015 */
016package org.joda.beans;
017
018import java.lang.annotation.ElementType;
019import java.lang.annotation.Retention;
020import java.lang.annotation.RetentionPolicy;
021import java.lang.annotation.Target;
022
023/**
024 * Annotation defining a property for code generation.
025 * <p>
026 * This annotation must be used on all private instance variables that
027 * should be treated as properties.
028 * 
029 * @author Stephen Colebourne
030 */
031@Retention(RetentionPolicy.RUNTIME)
032@Target(ElementType.FIELD)
033public @interface PropertyDefinition {
034
035    /**
036     * The style of the method used to query the property.
037     * <p>
038     * The style is a string describing the getter, typically used for code generation.
039     * By default this is 'smart' which will use the source code knowledge to determine
040     * what to generate. This will be a method of the form {@code isXxx()} for {@code boolean}
041     * and {@code getXxx()} for all other types.
042     * <p>
043     * Supported style stings are:
044     * <ul>
045     * <li>'' - do not generate any form of getter
046     * <li>'smart' - process intelligently - 'is' for boolean and 'get' for other types
047     * <li>'is' - generates isXxx()
048     * <li>'get' - generates getXxx()
049     * <li>'manual' - a method named getXxx() must be manually provided at package scope or greater
050     * </ul>
051     */
052    String get() default "smart";
053
054    /**
055     * The style of the method used to mutate the property.
056     * <p>
057     * The style is a string describing the mutator, typically used for code generation.
058     * By default this is 'smart' which will use the source code knowledge to determine
059     * what to generate. This will be a method of the form {@code setXxx()} for all types unless
060     * the field is {@code final}. If the field is a final {@code Collection} or {@code Map}
061     * of a known type then a set method is generated using {@code addAll} or {@code puAll}
062     * <p>
063     * Standard style stings are:
064     * <ul>
065     * <li>'' - do not generate any form of setter
066     * <li>'smart' - process intelligently - uses 'set' unless final, when it will use 'setClearAddAll'
067     *  for common list types or 'setClearPutAll' for common map types and FlexiBean
068     * <li>'set' - generates setXxx()
069     * <li>'setClearAddAll' - generates setXxx() using field.clear() and field.addAll(newData)
070     * <li>'setClearPutAll' - generates setXxx() using field.clear() and field.putAll(newData)
071     * <li>'manual' - a method named setXxx() must be manually provided at package scope or greater
072     * </ul>
073     */
074    String set() default "smart";
075
076    /**
077     * The validator to use.
078     * <p>
079     * The property value may be validated by specifying this attribute.
080     * By default no validation is performed.
081     * The code generator places the validation into the set method and ensures that
082     * new objects are validated correctly.
083     * <p>
084     * Custom validations, are written by writing a static method and referring to it.
085     * For example, {@code public void checkMyValue(Integer val, String propertyName) ...}
086     * The method generally has a {@code void} return, throwing an exception if validation fails.
087     * There must be two arguments, the value and the property name. The value may be the
088     * property type or a superclass (like Object). The property name should be a String.
089     * <p>
090     * Standard validation stings are:
091     * <ul>
092     * <li>'' - do not generate any form of validation
093     * <li>'notNull' - suitable for checking that the value is non-null,
094     *  calls JodaBeanUtils.notNull() which throws an IllegalArgumentException
095     * <li>'notEmpty' - suitable for checking that a string is non-null and non-empty,
096     *  calls JodaBeanUtils.notEmpty() which throws an IllegalArgumentException
097     * <li>'{className}.{staticMethodName}' - a custom validation method, described above
098     * </ul>
099     */
100    String validate() default "";
101
102}