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.transform;
014
015import org.apache.juneau.*;
016import org.apache.juneau.annotation.*;
017
018/**
019 * Identifies a class as being a surrogate class.
020 * 
021 * <p>
022 * Surrogate classes are used in place of other classes during serialization.
023 * <br>For example, you may want to use a surrogate class to change the names or order of bean properties on a bean.
024 * 
025 * <p>
026 * This interface has no methods to implement.
027 * <br>It's simply used by the framework to identify the class as a surrogate class when specified as a swap.
028 * 
029 * <p>
030 * The following is an example of a surrogate class change changes a property name:
031 * <p class='bcode'>
032 *    <jk>public class</jk> MySurrogate <jk>implements</jk> Surrogate {
033 * 
034 *       <jc>// Public constructor that wraps the normal object during serialization.</jc>
035 *       <jk>public</jk> MySurrogate(NormalClass o) {...}
036 *    
037 *       <jc>// Public no-arg constructor using during parsing.</jc>
038 *       <jc>// Not required if only used during serializing.</jc>
039 *       <jk>public</jk> MySurrogate() {...}
040 * 
041 *       <jc>// Public method that converts surrogate back into normal object during parsing.</jc>
042 *       <jc>// The method name can be anything (e.g. "build", "create", etc...).</jc>
043 *       <jc>// Not required if only used during serializing.</jc>
044 *       <jk>public</jk> NormalClass unswap() {...}
045 *    }
046 * </p>
047 * 
048 * <p>
049 * Surrogate classes are associated with serializers and parsers using the {@link BeanContextBuilder#pojoSwaps(Class...)}
050 * method.
051 * <p class='bcode'>
052 *    JsonSerializer s = JsonSerializer
053 *       .<jsm>create</jsm>()
054 *       .pojoSwaps(MySurrogate.<jk>class</jk>)
055 *       .build();
056 *    
057 *    JsonParser p = JsonParser
058 *       .<jsm>create</jsm>()
059 *       .pojoSwaps(MySurrogate.<jk>class</jk>)
060 *       .build();
061 * </p>
062 * 
063 * Surrogates can also be associated using the {@link Swap @Swap} annotation.
064 * <p class='bcode'>
065 *    <ja>@Swap</ja>(MySurrogate.<jk>class</jk>)
066 *    <jk>public class</jk> NormalClass {...}
067 * </p>
068 * 
069 * <p>
070 * On a side note, a surrogate class is functionally equivalent to the following {@link PojoSwap}
071 * implementation:
072 * <p class='bcode'>
073 *    <jk>public class</jk> MySurrogate <jk>extends</jk> PojoSwap&lt;NormalClass,MySurrogate&gt; {
074 *       <jk>public</jk> MySurrogate swap(NormalClass o) <jk>throws</jk> SerializeException {
075 *          <jk>return new</jk> MySurrogate(o);
076 *       }
077 *       <jk>public</jk> NormalClass unswap(MySurrogate o, ClassMeta&lt;?&gt; hint) <jk>throws</jk> ParseException {
078 *          <jk>return</jk> o.unswap();
079 *       }
080 *    }
081 * </p>
082 * 
083 * <h5 class='section'>See Also:</h5>
084 * <ul>
085 *    <li class='link'><a class="doclink" href="../../../../overview-summary.html#juneau-marshall.SurrogateClasses">Overview &gt; juneau-marshall &gt; SurrogateClasses</a>
086 * </ul>
087 */
088public interface Surrogate {}