001/*
002 * Copyright (c) 2014, Victor Nazarov <asviraspossible@gmail.com>
003 * All rights reserved.
004 *
005 * Redistribution and use in source and binary forms, with or without modification,
006 * are permitted provided that the following conditions are met:
007 *
008 *  1. Redistributions of source code must retain the above copyright notice,
009 *     this list of conditions and the following disclaimer.
010 *
011 *  2. Redistributions in binary form must reproduce the above copyright notice,
012 *     this list of conditions and the following disclaimer in the documentation and/or
013 *     other materials provided with the distribution.
014 *
015 *  3. Neither the name of the copyright holder nor the names of its contributors
016 *     may be used to endorse or promote products derived from this software
017 *     without specific prior written permission.
018 *
019 *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
020 *  ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
021 *  THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
022 *  IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
023 *  ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
024 *  (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
025 *   LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
026 *  ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
027 *  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
028 *  EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
029 */
030package io.jstach.jstache;
031
032import java.lang.annotation.Documented;
033import java.lang.annotation.ElementType;
034import java.lang.annotation.Retention;
035import java.lang.annotation.RetentionPolicy;
036import java.lang.annotation.Target;
037import java.util.ServiceLoader;
038
039/**
040 * Register escapers or filters.
041 *
042 * A class that is annotated represents a content type such as Html and will be used as a
043 * factory for creating escapers as well as a marker for the content type.
044 * <p>
045 * There are two supported escaper types:
046 * <ul>
047 * <li>{@code io.jstach.api.runtime.Escaper}
048 * <li>{@code java.util.function.Function<String,String>}
049 * </ul>
050 *
051 * The Function one is desirable if you would like no reference of jstachio runtime api in
052 * your code base and or just an easier interface to implement.
053 * <p>
054 * On the otherhand the Escaper interfaces allows potentially greater performance if you
055 * need to escape native types.
056 *
057 * <em>n.b. the class annotated does not need to implement the interfaces</em>
058 *
059 * @author agentgt
060 * @author Victor Nazarov
061 * @see JStacheConfig#contentType()
062 *
063 */
064@Retention(RetentionPolicy.RUNTIME)
065@Target(ElementType.TYPE)
066@Documented
067public @interface JStacheContentType {
068
069        /**
070         * A static method that will return an implementation of
071         * {@code io.jstach.api.runtime.Escaper} or {@code Function<String,String> }
072         * @return default method name is <code>provider</code> just like the
073         * {@link ServiceLoader}
074         */
075        String providesMethod() default "provider";
076
077        /**
078         * Media Type of the template to help in renderer lookup. The media type information
079         * should not include the charset parameter if {@link #charsets()} is set also for
080         * some media types the charset is inherent (e.g. application/json is inherently
081         * UTF-8) and should not be included.
082         * @return media type of the template or empty string no media type
083         */
084        String mediaType() default "";
085
086        /**
087         * The charsets supported by the escaper. If the template is encoded with a different
088         * charset a <strong>warning</strong> will be ommited by the compiler.
089         * @return supported charsets.
090         */
091        String[] charsets() default {};
092
093        /**
094         * A sentinel null object content type marker to auto resolve the content type based
095         * on config found elsewhere.
096         *
097         * @apiNote The provides method is purposely missing to avoid coupling with the
098         * runtime.
099         * @author agentgt
100         */
101        @JStacheContentType
102        public final class UnspecifiedContentType {
103
104                private UnspecifiedContentType() {
105                }
106
107        }
108
109}