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