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.inject;
018
019import static java.lang.annotation.ElementType.*;
020import static java.lang.annotation.RetentionPolicy.*;
021
022import java.lang.annotation.*;
023
024/**
025 * Resolves a configuration value into a constructor parameter, setter, or field.
026 *
027 * <p>
028 * The {@code value()} string is passed through Juneau's {@code VarResolver} (so
029 * {@code ${...}} / {@code $P{...}} placeholders are expanded against
030 * {@link org.apache.juneau.commons.settings.Settings#get() Settings.get()}), then coerced to the
031 * target Java type via {@link org.apache.juneau.commons.settings.Settings#toType(String, Class)}.
032 *
033 * <h5 class='section'>Examples:</h5>
034 * <p class='bjava'>
035 *    <jc>// Field injection with default.</jc>
036 *    <ja>@Value</ja>(<js>"${db.timeout.ms:5000}"</js>)
037 *    <jk>private int</jk> <jv>timeoutMs</jv>;
038 *
039 *    <jc>// Constructor-parameter injection.</jc>
040 *    <ja>@Inject</ja>
041 *    <jk>public</jk> OrdersResource(
042 *       <ja>@Value</ja>(<js>"${app.name:orders}"</js>) String <jv>appName</jv>,
043 *       <ja>@Value</ja>(<js>"${app.start}"</js>) Instant <jv>start</jv>
044 *    ) { ... }
045 * </p>
046 *
047 * <h5 class='section'>Resolution order:</h5>
048 * <ol>
049 *    <li>Thread-local override ({@link org.apache.juneau.commons.settings.Settings#setLocal Settings.setLocal})
050 *    <li>Global override ({@link org.apache.juneau.commons.settings.Settings#setGlobal Settings.setGlobal})
051 *    <li>Property sources in reverse insertion order — this is where Juneau {@code Config},
052 *       Spring {@code Environment}, and any other registered {@code PropertySource} participate.
053 *    <li>System properties
054 *    <li>System environment variables
055 * </ol>
056 *
057 * <p>
058 * Spring's {@code org.springframework.beans.factory.annotation.Value} annotation is honored identically
059 * via FQN-based detection in {@link JsrSupport}; no compile-time Spring dependency is introduced in
060 * {@code juneau-commons}.
061 *
062 * <h5 class='section'>Notes:</h5><ul>
063 *    <li class='note'>{@code @Value} and {@code @Inject} on the same site is invalid and throws
064 *       a {@code BeanCreationException}. {@code @Value} resolves strings/primitives; {@code @Inject}
065 *       resolves beans.
066 *    <li class='note'>If the expression resolves to {@code null} and the target type is a primitive,
067 *       a {@code BeanCreationException} is thrown.  For reference types, {@code null} is injected.
068 * </ul>
069 *
070 * <h5 class='section'>See Also:</h5><ul>
071 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/ValueAnnotation">@Value Annotation Basics</a>
072 * </ul>
073 */
074@Documented
075@Target({CONSTRUCTOR, METHOD, FIELD, PARAMETER})
076@Retention(RUNTIME)
077public @interface Value {
078
079   /**
080    * The configuration expression.
081    *
082    * <p>
083    * Typically uses the {@code ${key}} or {@code ${key:default}} placeholder syntax that is routed
084    * through {@code VarResolver} and {@link org.apache.juneau.commons.settings.Settings Settings}.
085    * Plain literals (no {@code $}) are passed through unchanged and still type-coerced.
086    *
087    * @return The configuration expression.
088    */
089   String value();
090}