001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.juneau.annotation;
018
019import static java.lang.annotation.ElementType.*;
020import static java.lang.annotation.RetentionPolicy.*;
021
022import java.lang.annotation.*;
023
024/**
025 * Identifies a setter as a method for adding a parent reference to a child object.
026 *
027 * <p>
028 * Can be used in the following locations:
029 * <ul>
030 *    <li>Bean getter/setter/field.
031 *    <li><ja>@Rest</ja>-annotated classes and <ja>@RestOp</ja>-annotated methods when an {@link #on()} value is specified.
032 * </ul>
033 *
034 * <p>
035 * Used by the parsers to add references to parent objects in child objects.
036 *
037 * <h5 class='section'>Notes:</h5><ul>
038 *    <li class='note'>
039 *       The annotated field or method does not need to be public.
040 * </ul>
041 *
042 * <h5 class='section'>See Also:</h5><ul>
043 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/ParentPropertyAnnotation">@ParentProperty Annotation</a>
044
045 * </ul>
046 */
047@Target({METHOD,FIELD,TYPE})
048@Retention(RUNTIME)
049@Inherited
050@Repeatable(ParentPropertyAnnotation.Array.class)
051@ContextApply(ParentPropertyAnnotation.Applier.class)
052public @interface ParentProperty {
053
054    /**
055     * Optional description for the exposed API.
056     *
057     * @return The annotation value.
058     * @since 9.2.0
059     */
060    String[] description() default {};
061
062   /**
063    * Dynamically apply this annotation to the specified methods/fields.
064    *
065    * <p>
066    * Used in conjunction with {@link org.apache.juneau.BeanContext.Builder#applyAnnotations(Class...)} to dynamically apply an annotation to an existing method/field.
067    * It is ignored when the annotation is applied directly to methods/fields.
068    *
069    * <h5 class='section'>Valid patterns:</h5>
070    * <ul class='spaced-list'>
071    *    <li>Methods:
072    *       <ul>
073    *          <li>Fully qualified with args:
074    *             <ul>
075    *                <li><js>"com.foo.MyClass.myMethod(String,int)"</js>
076    *                <li><js>"com.foo.MyClass.myMethod(java.lang.String,int)"</js>
077    *                <li><js>"com.foo.MyClass.myMethod()"</js>
078    *             </ul>
079    *          <li>Fully qualified:
080    *             <ul>
081    *                <li><js>"com.foo.MyClass.myMethod"</js>
082    *             </ul>
083    *          <li>Simple with args:
084    *             <ul>
085    *                <li><js>"MyClass.myMethod(String,int)"</js>
086    *                <li><js>"MyClass.myMethod(java.lang.String,int)"</js>
087    *                <li><js>"MyClass.myMethod()"</js>
088    *             </ul>
089    *          <li>Simple:
090    *             <ul>
091    *                <li><js>"MyClass.myMethod"</js>
092    *             </ul>
093    *          <li>Simple inner class:
094    *             <ul>
095    *                <li><js>"MyClass$Inner1$Inner2.myMethod"</js>
096    *                <li><js>"Inner1$Inner2.myMethod"</js>
097    *                <li><js>"Inner2.myMethod"</js>
098    *             </ul>
099    *       </ul>
100    *    <li>Fields:
101    *       <ul>
102    *          <li>Fully qualified:
103    *             <ul>
104    *                <li><js>"com.foo.MyClass.myField"</js>
105    *             </ul>
106    *          <li>Simple:
107    *             <ul>
108    *                <li><js>"MyClass.myField"</js>
109    *             </ul>
110    *          <li>Simple inner class:
111    *             <ul>
112    *                <li><js>"MyClass$Inner1$Inner2.myField"</js>
113    *                <li><js>"Inner1$Inner2.myField"</js>
114    *                <li><js>"Inner2.myField"</js>
115    *             </ul>
116    *       </ul>
117    *    <li>A comma-delimited list of anything on this list.
118    * </ul>
119    *
120    * <h5 class='section'>See Also:</h5><ul>
121    *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/DynamicallyAppliedAnnotations">Dynamically Applied Annotations</a>
122    * </ul>
123    *
124    * @return The annotation value.
125    */
126   String[] on() default {};
127}