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