001/*
002 * Copyright 2002-2018 the original author or authors.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *      https://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package org.springframework.context.annotation;
018
019import java.lang.annotation.Documented;
020import java.lang.annotation.ElementType;
021import java.lang.annotation.Retention;
022import java.lang.annotation.RetentionPolicy;
023import java.lang.annotation.Target;
024
025import org.springframework.core.env.AbstractEnvironment;
026import org.springframework.core.env.ConfigurableEnvironment;
027import org.springframework.core.env.Profiles;
028
029/**
030 * Indicates that a component is eligible for registration when one or more
031 * {@linkplain #value specified profiles} are active.
032 *
033 * <p>A <em>profile</em> is a named logical grouping that may be activated
034 * programmatically via {@link ConfigurableEnvironment#setActiveProfiles} or declaratively
035 * by setting the {@link AbstractEnvironment#ACTIVE_PROFILES_PROPERTY_NAME
036 * spring.profiles.active} property as a JVM system property, as an
037 * environment variable, or as a Servlet context parameter in {@code web.xml}
038 * for web applications. Profiles may also be activated declaratively in
039 * integration tests via the {@code @ActiveProfiles} annotation.
040 *
041 * <p>The {@code @Profile} annotation may be used in any of the following ways:
042 * <ul>
043 * <li>as a type-level annotation on any class directly or indirectly annotated with
044 * {@code @Component}, including {@link Configuration @Configuration} classes</li>
045 * <li>as a meta-annotation, for the purpose of composing custom stereotype annotations</li>
046 * <li>as a method-level annotation on any {@link Bean @Bean} method</li>
047 * </ul>
048 *
049 * <p>If a {@code @Configuration} class is marked with {@code @Profile}, all of the
050 * {@code @Bean} methods and {@link Import @Import} annotations associated with that class
051 * will be bypassed unless one or more of the specified profiles are active. A profile
052 * string may contain a simple profile name (for example {@code "p1"}) or a profile
053 * expression. A profile expression allows for more complicated profile logic to be
054 * expressed, for example {@code "p1 & p2"}. See {@link Profiles#of(String...)} for more
055 * details about supported formats.
056 *
057 * <p>This is analogous to the behavior in Spring XML: if the {@code profile} attribute of
058 * the {@code beans} element is supplied e.g., {@code <beans profile="p1,p2">}, the
059 * {@code beans} element will not be parsed unless at least profile 'p1' or 'p2' has been
060 * activated. Likewise, if a {@code @Component} or {@code @Configuration} class is marked
061 * with {@code @Profile({"p1", "p2"})}, that class will not be registered or processed unless
062 * at least profile 'p1' or 'p2' has been activated.
063 *
064 * <p>If a given profile is prefixed with the NOT operator ({@code !}), the annotated
065 * component will be registered if the profile is <em>not</em> active &mdash; for example,
066 * given {@code @Profile({"p1", "!p2"})}, registration will occur if profile 'p1' is active
067 * or if profile 'p2' is <em>not</em> active.
068 *
069 * <p>If the {@code @Profile} annotation is omitted, registration will occur regardless
070 * of which (if any) profiles are active.
071 *
072 * <p><b>NOTE:</b> With {@code @Profile} on {@code @Bean} methods, a special scenario may
073 * apply: In the case of overloaded {@code @Bean} methods of the same Java method name
074 * (analogous to constructor overloading), an {@code @Profile} condition needs to be
075 * consistently declared on all overloaded methods. If the conditions are inconsistent,
076 * only the condition on the first declaration among the overloaded methods will matter.
077 * {@code @Profile} can therefore not be used to select an overloaded method with a
078 * particular argument signature over another; resolution between all factory methods
079 * for the same bean follows Spring's constructor resolution algorithm at creation time.
080 * <b>Use distinct Java method names pointing to the same {@link Bean#name bean name}
081 * if you'd like to define alternative beans with different profile conditions</b>;
082 * see {@code ProfileDatabaseConfig} in {@link Configuration @Configuration}'s javadoc.
083 *
084 * <p>When defining Spring beans via XML, the {@code "profile"} attribute of the
085 * {@code <beans>} element may be used. See the documentation in the
086 * {@code spring-beans} XSD (version 3.1 or greater) for details.
087 *
088 * @author Chris Beams
089 * @author Phillip Webb
090 * @author Sam Brannen
091 * @since 3.1
092 * @see ConfigurableEnvironment#setActiveProfiles
093 * @see ConfigurableEnvironment#setDefaultProfiles
094 * @see AbstractEnvironment#ACTIVE_PROFILES_PROPERTY_NAME
095 * @see AbstractEnvironment#DEFAULT_PROFILES_PROPERTY_NAME
096 * @see Conditional
097 * @see org.springframework.test.context.ActiveProfiles
098 */
099@Target({ElementType.TYPE, ElementType.METHOD})
100@Retention(RetentionPolicy.RUNTIME)
101@Documented
102@Conditional(ProfileCondition.class)
103public @interface Profile {
104
105        /**
106         * The set of profiles for which the annotated component should be registered.
107         */
108        String[] value();
109
110}