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
020/**
021 * Identifies a bean injection qualifier for constructor/method parameters.
022 *
023 * <p>
024 * This annotation is used to specify which named bean should be injected into a constructor
025 * or method parameter. It serves the same purpose as the standard {@code javax.inject.Named} annotation but without
026 * requiring a dependency on the javax.inject module.
027 *
028 * <h5 class='section'>Example:</h5>
029 * <p class='bjava'>
030 *    <jk>public</jk> MyClass(<ja>@Named</ja>(<js>"myBean"</js>) MyBean <jv>bean</jv>) {
031 *       <jc>// Constructor will receive the bean named "myBean" from the BeanStore</jc>
032 *    }
033 * </p>
034 *
035 * <h5 class='section'>Comparison with @Name:</h5>
036 * <p>
037 * Do not confuse this annotation with {@link Name @Name}, which serves a different purpose:
038 * <ul>
039 *    <li><b>{@link Named @Named}</b> - Specifies which named bean to inject (bean qualifier)
040 *    <li><b>{@link Name @Name}</b> - Specifies the parameter name for bean property mapping when
041 *       bytecode parameter names are not available
042 * </ul>
043 *
044 * <h5 class='section'>Example showing the difference:</h5>
045 * <p class='bjava'>
046 *    <jc>// @Named - for bean injection</jc>
047 *    <jk>public</jk> MyService(<ja>@Named</ja>(<js>"primaryDb"</js>) Database <jv>db</jv>) {
048 *       <jc>// Injects the bean named "primaryDb" from BeanStore</jc>
049 *    }
050 *
051 *    <jc>// @Name - for parameter naming (when bytecode names unavailable)</jc>
052 *    <jk>public</jk> Person(<ja>@Name</ja>(<js>"firstName"</js>) String <jv>arg0</jv>, <ja>@Name</ja>(<js>"lastName"</js>) String <jv>arg1</jv>) {
053 *       <jc>// Maps constructor parameters to bean properties "firstName" and "lastName"</jc>
054 *       <jc>// Useful when class is not compiled with -parameters flag</jc>
055 *    }
056 * </p>
057 *
058 * <h5 class='section'>See Also:</h5><ul>
059 *    <li class='ja'>{@link Name}
060 *    <li class='jc'>{@link org.apache.juneau.cp.BeanStore}
061 * </ul>
062 */
063@Documented
064@Target({ PARAMETER })
065@Retention(RUNTIME)
066@Inherited
067public @interface Named {
068
069   /**
070    * The bean name to use for injection.
071    *
072    * @return The bean name.
073    */
074   String value();
075}