001// ***************************************************************************************************************************
002// * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements.  See the NOTICE file *
003// * distributed with this work for additional information regarding copyright ownership.  The ASF licenses this file        *
004// * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance            *
005// * with the License.  You may obtain a copy of the License at                                                              *
006// *                                                                                                                         *
007// *  http://www.apache.org/licenses/LICENSE-2.0                                                                             *
008// *                                                                                                                         *
009// * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an  *
010// * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the License for the        *
011// * specific language governing permissions and limitations under the License.                                              *
012// ***************************************************************************************************************************
013package org.apache.juneau.annotation;
014
015import static java.lang.annotation.ElementType.*;
016import static java.lang.annotation.RetentionPolicy.*;
017
018import java.lang.annotation.*;
019
020import org.apache.juneau.*;
021
022/**
023 * Maps constructor arguments to property names on beans with read-only properties.
024 *
025 * <p>
026 * This annotation can be used in the case of beans with properties whose values can only be set by passing them in
027 * through a constructor on the class.
028 * <br>Since method parameter names are lost during compilation, this annotation essentially redefines them so that they
029 * are available at runtime.
030 *
031 * <p>
032 * This annotation can only be applied to constructors and can only be applied to one constructor per class.
033 *
034 * <p>
035 * When present, bean instantiation is delayed until the call to {@link BeanMap#getBean()}.
036 * Until then, bean property values are stored in a local cache until <c>getBean()</c> is called.
037 * Because of this additional caching step, parsing into read-only beans tends to be slower and use more memory than
038 * parsing into beans with writable properties.
039 *
040 * <p>
041 * Attempting to call {@link BeanMap#put(String,Object)} on a read-only property after calling {@link BeanMap#getBean()}
042 * will result in a {@link BeanRuntimeException} being thrown.
043 * Multiple calls to {@link BeanMap#getBean()} will return the same bean instance.
044 *
045 * <ul class='seealso'>
046 *    <li class='link'>{@doc BeancAnnotation}
047 * </ul>
048 */
049@Documented
050@Target(CONSTRUCTOR)
051@Retention(RUNTIME)
052@Inherited
053public @interface Beanc {
054
055   /**
056    * Dynamically apply this annotation to the specified constructors.
057    *
058    * <p>
059    * Used in conjunction with the {@link BeanConfig#applyBeanc()}.
060    * It is ignored when the annotation is applied directly to constructors.
061    *
062    * <p>
063    * The following example shows this annotation in use:
064    * <p class='bpcode w800'>
065    *    <jc>// Our read-only bean.</jc>
066    *    <jk>public class</jk> Person {
067    *       <jk>private final</jk> String <jf>name</jf>;
068    *       <jk>private final int</jk> <jf>age</jf>;
069    *
070    *       <jk>public</jk> Person(String name, <jk>int</jk> age) {
071    *          <jk>this</jk>.<jf>name</jf> = name;
072    *          <jk>this</jk>.<jf>age</jf> = age;
073    *       }
074    *
075    *       <jc>// Read only properties.</jc>
076    *       <jc>// Getters, but no setters.</jc>
077    *
078    *       <jk>public</jk> String getName() {
079    *          <jk>return</jk> <jf>name</jf>;
080    *       }
081    *
082    *       <jk>public int</jk> getAge() {
083    *          <jk>return</jk> <jf>age</jf>;
084    *       }
085    *    }
086    *
087    *    <ja>@BeanConfig</ja>(applyBeanc=<ja>@Beanc</ja>(on="Person(String,int)", properties=<js>"name,age"</js>))
088    *    public static class X {}
089    * </p>
090    * <p class='bpcode w800'>
091    *    <jc>// Parsing into a read-only bean.</jc>
092    *    String json = <js>"{name:'John Smith',age:45}"</js>;
093    *    Person p = JsonParser.<jsf>DEFAULT</jsf>.builder().applyAnnotations(X.<jk>class</jk>).build().parse(json);
094    *    String name = p.getName();  <jc>// "John Smith"</jc>
095    *    <jk>int</jk> age = p.getAge();   <jc>// 45</jc>
096    * </p>
097    *
098    * <h5 class='section'>Valid patterns:</h5>
099    * <ul class='spaced-list'>
100    *    <li>Constructors:
101    *       <ul>
102    *          <li>Fully qualified with args:
103    *             <ul>
104    *                <li><js>"com.foo.MyClass(String,int)"</js>
105    *                <li><js>"com.foo.MyClass(java.lang.String,int)"</js>
106    *                <li><js>"com.foo.MyClass()"</js>
107    *             </ul>
108    *          <li>Simple with args:
109    *             <ul>
110    *                <li><js>"MyClass(String,int)"</js>
111    *                <li><js>"MyClass(java.lang.String,int)"</js>
112    *                <li><js>"MyClass()"</js>
113    *             </ul>
114    *          <li>Simple inner class:
115    *             <ul>
116    *                <li><js>"MyClass$Inner1$Inner2()"</js>
117    *                <li><js>"Inner1$Inner2()"</js>
118    *                <li><js>"Inner2()"</js>
119    *             </ul>
120    *       </ul>
121    *    <li>A comma-delimited list of anything on this list.
122    * </ul>
123    *
124    * <ul class='seealso'>
125    *    <li class='link'>{@doc DynamicallyAppliedAnnotations}
126    * </ul>
127    */
128   String on() default "";
129
130   /**
131    * The names of the properties of the constructor arguments.
132    *
133    * <p>
134    * The {@link org.apache.juneau.annotation.Beanc @Beanc} annotation is used to map constructor arguments to property
135    * names on bean with read-only properties.
136    * <br>Since method parameter names are lost during compilation, this annotation essentially redefines them so that
137    * they are available at runtime.
138    *
139    * <p>
140    * The definition of a read-only bean is a bean with properties with only getters, like shown below:
141    * <p class='bpcode w800'>
142    *    <jc>// Our read-only bean.</jc>
143    *    <jk>public class</jk> Person {
144    *       <jk>private final</jk> String <jf>name</jf>;
145    *       <jk>private final int</jk> <jf>age</jf>;
146    *
147    *       <ja>@Beanc</ja>(properties=<js>"name,age"</js>)
148    *       <jk>public</jk> Person(String name, <jk>int</jk> age) {
149    *          <jk>this</jk>.<jf>name</jf> = name;
150    *          <jk>this</jk>.<jf>age</jf> = age;
151    *       }
152    *
153    *       <jc>// Read only properties.</jc>
154    *       <jc>// Getters, but no setters.</jc>
155    *
156    *       <jk>public</jk> String getName() {
157    *          <jk>return</jk> <jf>name</jf>;
158    *       }
159    *
160    *       <jk>public int</jk> getAge() {
161    *          <jk>return</jk> <jf>age</jf>;
162    *       }
163    *    }
164    * </p>
165    * <p class='bpcode w800'>
166    *    <jc>// Parsing into a read-only bean.</jc>
167    *    String json = <js>"{name:'John Smith',age:45}"</js>;
168    *    Person p = JsonParser.<jsf>DEFAULT</jsf>.parse(json);
169    *    String name = p.getName();  <jc>// "John Smith"</jc>
170    *    <jk>int</jk> age = p.getAge();   <jc>// 45</jc>
171    * </p>
172    * <p>
173    *    Note that the {@link Name @Name} annotation can also be used to identify bean property names on constructor
174    *    arguments.  If neither this annotation or {@link Name @Name} is used, then we try to get the property names
175    *    from the parameter names if they are available in the bytecode.
176    * </p>
177    */
178   String properties() default "";
179}