001package io.jstach.jstache;
002
003import java.lang.annotation.Documented;
004import java.lang.annotation.ElementType;
005import java.lang.annotation.Retention;
006import java.lang.annotation.RetentionPolicy;
007import java.lang.annotation.Target;
008import java.net.URI;
009import java.net.URL;
010
011/**
012 * Statically sets allowed formatting types.
013 * <p>
014 * If a type is not allowed or known and used as a variable a compile error will happen.
015 * This annotation allows you to change that behavior by adding types.
016 * <p>
017 * By default the only allowed (and always allowed) types to be formatted are:
018 * <ul>
019 * <li>{@link String}
020 * <li>native types both unboxed or boxed
021 * <li>{@link URI}
022 * <li>{@link URL}
023 * </ul>
024 * <p>
025 * {@linkplain JStacheConfig Config lookup and precedence} is as follows:
026 * <ol>
027 * <li>type annotated with JStache and this annotation.
028 * <li>enclosing class (of type annotated with JStache) with this annotation with inner to
029 * outer order.
030 * <li>package annotated with this annotation.
031 * <li>module annotated with this annotation.
032 * <li><em>the chosen {@linkplain JStacheFormatter formatter} with this annotation.</em>
033 * </ol>
034 *
035 * However unlike other annotations in this library the found annotation settings are
036 * combined (union) and consequently the precedence order does not matter.
037 *
038 * @apiNote n.b. the retention policy is SOURCE as this settings are only needed for the
039 * compiler and why it is not in {@link JStacheConfig}.
040 * @author agentgt
041 * @see JStacheFormatter
042 * @see JStacheConfig
043 */
044@Retention(RetentionPolicy.SOURCE)
045@Target({ ElementType.TYPE, ElementType.PACKAGE, ElementType.MODULE })
046@Documented
047public @interface JStacheFormatterTypes {
048
049        /**
050         * Whitelist classes that will be allowed to be passed to the formatter.
051         * @return Allowed classes that will be passed to the formatter.
052         */
053        public Class<?>[] types() default {};
054
055        /**
056         * List of regex used to match whitelist class names that are allowed to be formatted.
057         * @return regex used to match class names that are allowed to be formatted.
058         */
059        public String[] patterns() default {};
060
061}