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