001/*
002 * Copyright 2012-2016 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 *      http://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.boot.autoconfigure.condition;
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.context.annotation.Conditional;
026import org.springframework.core.env.Environment;
027
028/**
029 * {@link Conditional} that checks if the specified properties have a specific value. By
030 * default the properties must be present in the {@link Environment} and
031 * <strong>not</strong> equal to {@code false}. The {@link #havingValue()} and
032 * {@link #matchIfMissing()} attributes allow further customizations.
033 *
034 * <p>
035 * The {@link #havingValue} attribute can be used to specify the value that the property
036 * should have. The table below shows when a condition matches according to the property
037 * value and the {@link #havingValue()} attribute:
038 *
039 * <table summary="having values" border="1">
040 * <tr>
041 * <th>Property Value</th>
042 * <th>{@code havingValue=""}</th>
043 * <th>{@code havingValue="true"}</th>
044 * <th>{@code havingValue="false"}</th>
045 * <th>{@code havingValue="foo"}</th>
046 * </tr>
047 * <tr>
048 * <td>{@code "true"}</td>
049 * <td>yes</td>
050 * <td>yes</td>
051 * <td>no</td>
052 * <td>no</td>
053 * </tr>
054 * <tr>
055 * <td>{@code "false"}</td>
056 * <td>no</td>
057 * <td>no</td>
058 * <td>yes</td>
059 * <td>no</td>
060 * </tr>
061 * <tr>
062 * <td>{@code "foo"}</td>
063 * <td>yes</td>
064 * <td>no</td>
065 * <td>no</td>
066 * <td>yes</td>
067 * </tr>
068 * </table>
069 *
070 * <p>
071 * If the property is not contained in the {@link Environment} at all, the
072 * {@link #matchIfMissing()} attribute is consulted. By default missing attributes do not
073 * match.
074 *
075 * @author Maciej Walkowiak
076 * @author Stephane Nicoll
077 * @author Phillip Webb
078 * @since 1.1.0
079 */
080@Retention(RetentionPolicy.RUNTIME)
081@Target({ ElementType.TYPE, ElementType.METHOD })
082@Documented
083@Conditional(OnPropertyCondition.class)
084public @interface ConditionalOnProperty {
085
086        /**
087         * Alias for {@link #name()}.
088         * @return the names
089         */
090        String[] value() default {};
091
092        /**
093         * A prefix that should be applied to each property. The prefix automatically ends
094         * with a dot if not specified.
095         * @return the prefix
096         */
097        String prefix() default "";
098
099        /**
100         * The name of the properties to test. If a prefix has been defined, it is applied to
101         * compute the full key of each property. For instance if the prefix is
102         * {@code app.config} and one value is {@code my-value}, the fully key would be
103         * {@code app.config.my-value}
104         * <p>
105         * Use the dashed notation to specify each property, that is all lower case with a "-"
106         * to separate words (e.g. {@code my-long-property}).
107         * @return the names
108         */
109        String[] name() default {};
110
111        /**
112         * The string representation of the expected value for the properties. If not
113         * specified, the property must <strong>not</strong> be equals to {@code false}.
114         * @return the expected value
115         */
116        String havingValue() default "";
117
118        /**
119         * Specify if the condition should match if the property is not set. Defaults to
120         * {@code false}.
121         * @return if should match if the property is missing
122         */
123        boolean matchIfMissing() default false;
124
125        /**
126         * If relaxed names should be checked. Defaults to {@code true}.
127         * @return if relaxed names are used
128         */
129        boolean relaxedNames() default true;
130
131}