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.marshall;
018
019import static java.lang.annotation.ElementType.*;
020import static java.lang.annotation.RetentionPolicy.*;
021
022import java.lang.annotation.*;
023
024import org.apache.juneau.marshall.swap.spi.*;
025
026/**
027 * Associates {@link ObjectSwap} and {@link Surrogate} classes with POJOs and bean properties.
028 *
029 * <p>
030 * Can be used in the following locations:
031 * <ul>
032 *    <li>Classes.
033 *    <li>Bean getters/setters/fields.
034 *    <li><ja>@Rest</ja>-annotated classes and <ja>@RestOp</ja>-annotated methods when used with {@link SwapApply @SwapApply}.
035 * </ul>
036
037 * <h5 class='section'>See Also:</h5><ul>
038 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/SwapAnnotation">@Swap Annotation</a>
039
040 * </ul>
041 */
042@Documented
043@Target({ TYPE, ANNOTATION_TYPE, FIELD, METHOD })
044@Retention(RUNTIME)
045@Inherited
046@Repeatable(SwapAnnotation.Array.class)
047public @interface Swap {
048
049   /**
050    * Optional description for the exposed API.
051    *
052    * @return The annotation value.
053    * @since 9.2.0
054    */
055   String[] description() default {};
056
057   /**
058    * The {@link ObjectSwap} and {@link Surrogate} class.
059    *
060    * <p>
061    * A synonym for {@link #value()}.
062    *
063    * @return The annotation value.
064    */
065   Class<?> impl() default void.class;
066
067   /**
068    * Identifies the media types that this swap is applicable for.
069    *
070    * <p>
071    * In the following example, the swap is only invoked by the JSON serializer:
072    *
073    * <p class='bjava'>
074    *    <ja>@Swap</ja>(impl=ToStringSwap.<jk>class</jk>, mediaTypes=<js>"&#42;/json"</js>)
075    *    <jk>public class</jk> MyBean { ... }
076    *
077    *    <jk>public class</jk> ToStringSwap <jk>extends</jk> ObjectSwap&lt;Object,String&gt; {
078    *          <jk>public</jk> String swap(MarshallingSession <jv>session</jv>, Object <jv>value</jv>) <jk>throws</jk> Exception {
079    *             <jk>return</jk> <jv>value</jv>.toString();
080    *          }
081    *       }
082    * </p>
083    *
084    * <h5 class='section'>See Also:</h5><ul>
085    *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/Swaps#per-media-type-swaps">Per-media-type swaps</a>
086    * </ul>
087    *
088    * @return The annotation value.
089    */
090   String[] mediaTypes() default {};
091
092   /**
093    * Identifies a template string along with this swap.
094    *
095    * <p>
096    * Template strings are arbitrary strings associated with swaps that help provide additional context information
097    * for the swap class.
098    * They're called 'templates' because their primary purpose is for providing template names, such as Apache FreeMarker
099    * template names.
100    *
101    * <p>
102    * The following is an example of a templated swap class used to serialize POJOs to HTML using FreeMarker:
103    *
104    * <p class='bjava'>
105    *    <jc>// Our templated swap class.</jc>
106    *    <jk>public class</jk> FreeMarkerSwap <jk>extends</jk> ObjectSwap&lt;Object,Reader&gt; {
107    *
108    *       <jk>public</jk> MediaType[] forMediaTypes() {
109    *          <jk>return</jk> MediaType.<jsm>forStrings</jsm>(<js>"&#42;/html"</js>);
110    *       }
111    *
112    *       <jk>public</jk> Reader swap(MarshallingSession <jv>session</jv>, Object <jv>value</jv>, String <jv>template</jv>) <jk>throws</jk> Exception {
113    *          <jk>return</jk> <jsm>getFreeMarkerReader</jsm>(<jv>template</jv>, <jv>value</jv>);  <jc>// Some method that creates raw HTML.</jc>
114    *       }
115    *    }
116    * </p>
117    * <p class='bjava'>
118    *    <ja>@Swap</ja>(impl=FreeMarkerSwap.<jk>class</jk>, template=<js>"MyPojo.div.ftl"</js>)
119    *    <jk>public class</jk> MyPojo {}
120    * </p>
121    *
122    * <h5 class='section'>See Also:</h5><ul>
123    *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/TemplatedSwaps">Templated Swaps</a>
124    * </ul>
125    *
126    * @return The annotation value.
127    */
128   String template() default "";
129
130   /**
131    * The {@link ObjectSwap} and {@link Surrogate} class.
132    *
133    * <p>
134    * A synonym for {@link #impl()}.
135    *
136    * @return The annotation value.
137    */
138   Class<?> value() default void.class;
139}