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 * Specifies the parameter name for bean property mapping.
026 *
027 * <p>
028 * This annotation is used to explicitly specify a parameter name when bytecode parameter names
029 * are not available (i.e., when code is not compiled with the {@code -parameters} flag).
030 * It allows constructors to map parameters to bean properties by name.
031 *
032 * <p>
033 * Can be used in the following locations:
034 * <ul>
035 *    <li>On constructor and method arguments when the parameter names are not in the compiled bytecode.
036 * </ul>
037 *
038 * <h5 class='figure'>Examples:</h5>
039 * <p class='bjava'>
040 *    <jc>// Without -parameters flag, parameter names would be arg0, arg1, etc.</jc>
041 *    <jk>public class</jk> Person {
042 *       <jk>public</jk> Person(<ja>@Name</ja>(<js>"firstName"</js>) String <jv>arg0</jv>, <ja>@Name</ja>(<js>"lastName"</js>) String <jv>arg1</jv>) {
043 *          <jc>// Parameters can be mapped to bean properties "firstName" and "lastName"</jc>
044 *       }
045 *    }
046 * </p>
047 *
048 * <h5 class='section'>Comparison with @Named:</h5>
049 * <p>
050 * Do not confuse this annotation with {@link Named @Named}, which serves a different purpose:
051 * <ul>
052 *    <li><b>{@link Name @Name}</b> - Specifies the parameter name for bean property mapping
053 *    <li><b>{@link Named @Named}</b> - Specifies which named bean to inject (bean qualifier)
054 * </ul>
055 *
056 * <h5 class='section'>Example showing the difference:</h5>
057 * <p class='bjava'>
058 *    <jc>// @Name - for parameter naming</jc>
059 *    <jk>public</jk> Person(<ja>@Name</ja>(<js>"firstName"</js>) String <jv>arg0</jv>) {
060 *       <jc>// Maps parameter to bean property "firstName"</jc>
061 *    }
062 *
063 *    <jc>// @Named - for bean injection</jc>
064 *    <jk>public</jk> MyService(<ja>@Named</ja>(<js>"primaryDb"</js>) Database <jv>db</jv>) {
065 *       <jc>// Injects the bean named "primaryDb" from BeanStore</jc>
066 *    }
067 * </p>
068 *
069 * <h5 class='section'>See Also:</h5><ul>
070 *    <li class='ja'>{@link Named}
071 *    <li class='jc'>{@link org.apache.juneau.cp.BeanStore}
072 * </ul>
073 */
074@Documented
075@Target({ PARAMETER })
076@Retention(RUNTIME)
077@Inherited
078public @interface Name {
079
080   /**
081    * The bean property or parameter name.
082    *
083    * @return The annotation value.
084    */
085   String value();
086}