001// *************************************************************************************************************************** 002// * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file * 003// * distributed with this work for additional information regarding copyright ownership. The ASF licenses this file * 004// * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance * 005// * with the License. You may obtain a copy of the License at * 006// * * 007// * http://www.apache.org/licenses/LICENSE-2.0 * 008// * * 009// * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an * 010// * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the * 011// * specific language governing permissions and limitations under the License. * 012// *************************************************************************************************************************** 013package org.apache.juneau.annotation; 014 015import static java.lang.annotation.ElementType.*; 016import static java.lang.annotation.RetentionPolicy.*; 017 018import java.lang.annotation.*; 019 020import org.apache.juneau.transform.*; 021 022/** 023 * Associates {@link PojoSwap} and {@link Surrogate} classes with POJOs and bean properties. 024 * 025 * <p> 026 * This annotation can be used in the following locations: 027 * <ul> 028 * <li>Classes. 029 * <li>Bean getters/setters/fields. 030 * <li>Inside the {@link Swaps @Swaps} annotation. 031 * </ul> 032 * 033 * <ul class='seealso'> 034 * <li class='link'>{@doc juneau-marshall.Transforms.SwapAnnotation} 035 * </ul> 036 */ 037@Documented 038@Target({TYPE,ANNOTATION_TYPE,FIELD,METHOD}) 039@Retention(RUNTIME) 040@Inherited 041public @interface Swap { 042 043 /** 044 * The {@link PojoSwap} and {@link Surrogate} class. 045 * 046 * <p> 047 * A synonym for {@link #value()}. 048 */ 049 Class<?> impl() default Null.class; 050 051 /** 052 * Identifies the media types that this swap is applicable for. 053 * 054 * <p> 055 * In the following example, the swap is only invoked by the JSON serializer: 056 * 057 * <p class='bcode w800'> 058 * <ja>@Swap</ja>(impl=ToStringSwap.<jk>class</jk>, mediaTypes=<js>"*/json"</js>) 059 * <jk>public class</jk> MyBean { ... } 060 * 061 * <jk>public class</jk> ToStringSwap <jk>extends</jk> PojoSwap<Object,String> { 062 * <jk>public</jk> String swap(BeanSession session, Object o) <jk>throws</jk> Exception { 063 * <jk>return</jk> o.toString(); 064 * } 065 * } 066 * </p> 067 * 068 * <ul class='seealso'> 069 * <li class='link'>{@doc juneau-marshall.Transforms.PerMediaTypePojoSwaps} 070 * </ul> 071 */ 072 String[] mediaTypes() default {}; 073 074 /** 075 * Identifies a template string along with this swap. 076 * 077 * <p> 078 * Template strings are arbitrary strings associated with swaps that help provide additional context information 079 * for the swap class. 080 * They're called 'templates' because their primary purpose is for providing template names, such as Apache FreeMarker 081 * template names. 082 * 083 * <p> 084 * The following is an example of a templated swap class used to serialize POJOs to HTML using FreeMarker: 085 * 086 * <p class='bcode w800'> 087 * <jc>// Our templated swap class.</jc> 088 * <jk>public class</jk> FreeMarkerSwap <jk>extends</jk> PojoSwap<Object,Reader> { 089 * 090 * <jk>public</jk> MediaType[] forMediaTypes() { 091 * <jk>return</jk> MediaType.<jsm>forStrings</jsm>(<js>"*/html"</js>); 092 * } 093 * 094 * <jk>public</jk> Reader swap(BeanSession session, Object o, String template) <jk>throws</jk> Exception { 095 * <jk>return</jk> getFreeMarkerReader(template, o); <jc>// Some method that creates raw HTML.</jc> 096 * } 097 * } 098 * </p> 099 * <p class='bcode w800'> 100 * <ja>@Swap</ja>(impl=FreeMarkerSwap.<jk>class</jk>, template=<js>"MyPojo.div.ftl"</js>) 101 * <jk>public class</jk> MyPojo {} 102 * </p> 103 * 104 * <ul class='seealso'> 105 * <li class='link'>{@doc juneau-marshall.Transforms.TemplatedSwaps} 106 * </ul> 107 */ 108 String template() default ""; 109 110 /** 111 * The {@link PojoSwap} and {@link Surrogate} class. 112 * 113 * <p> 114 * A synonym for {@link #impl()}. 115 */ 116 Class<?> value() default Null.class; 117}