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 */
016 package org.joda.beans;
017
018 import java.lang.annotation.ElementType;
019 import java.lang.annotation.Retention;
020 import java.lang.annotation.RetentionPolicy;
021 import 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)
033 public @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 * @return the style of the property, not null
053 */
054 String get() default "smart";
055
056 /**
057 * The style of the method used to mutate the property.
058 * <p>
059 * The style is a string describing the mutator, typically used for code generation.
060 * By default this is 'smart' which will use the source code knowledge to determine
061 * what to generate. This will be a method of the form {@code setXxx()} for all types unless
062 * the field is {@code final}. If the field is a final {@code Collection} or {@code Map}
063 * of a known type then a set method is generated using {@code addAll} or {@code puAll}
064 * <p>
065 * Standard style stings are:
066 * <ul>
067 * <li>'' - do not generate any form of setter
068 * <li>'smart' - process intelligently - uses 'set' unless final, when it will use 'setClearAddAll'
069 * for common list types or 'setClearPutAll' for common map types and FlexiBean
070 * <li>'set' - generates setXxx()
071 * <li>'setClearAddAll' - generates setXxx() using field.clear() and field.addAll(newData)
072 * <li>'setClearPutAll' - generates setXxx() using field.clear() and field.putAll(newData)
073 * <li>'manual' - a method named setXxx() must be manually provided at package scope or greater
074 * </ul>
075 *
076 * @return the style of the property, not null
077 */
078 String set() default "smart";
079
080 /**
081 * The validator to use.
082 * <p>
083 * The property value may be validated by specifying this attribute.
084 * By default no validation is performed.
085 * The code generator places the validation into the set method and ensures that
086 * new objects are validated correctly.
087 * <p>
088 * Custom validations, are written by writing a static method and referring to it.
089 * For example, {@code public void checkMyValue(Integer val, String propertyName) ...}
090 * The method generally has a {@code void} return, throwing an exception if validation fails.
091 * There must be two arguments, the value and the property name. The value may be the
092 * property type or a superclass (like Object). The property name should be a String.
093 * <p>
094 * Standard validation stings are:
095 * <ul>
096 * <li>'' - do not generate any form of validation
097 * <li>'notNull' - suitable for checking that the value is non-null,
098 * calls JodaBeanUtils.notNull() which throws an IllegalArgumentException
099 * <li>'notEmpty' - suitable for checking that a string is non-null and non-empty,
100 * calls JodaBeanUtils.notEmpty() which throws an IllegalArgumentException
101 * <li>'{className}.{staticMethodName}' - a custom validation method, described above
102 * </ul>
103 *
104 * @return the validation type, not null
105 */
106 String validate() default "";
107
108 }