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 w800'>
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#swaps(Object...)}
050 * method.
051 * <p class='bcode w800'>
052 *    JsonSerializer s = JsonSerializer
053 *       .<jsm>create</jsm>()
054 *       .swaps(MySurrogate.<jk>class</jk>)
055 *       .build();
056 *
057 *    JsonParser p = JsonParser
058 *       .<jsm>create</jsm>()
059 *       .swaps(MySurrogate.<jk>class</jk>)
060 *       .build();
061 * </p>
062 *
063 * <p>
064 * Surrogates can also be associated using the {@link Swap @Swap} annotation.
065 * <p class='bcode w800'>
066 *    <ja>@Swap</ja>(MySurrogate.<jk>class</jk>)
067 *    <jk>public class</jk> NormalClass {...}
068 * </p>
069 *
070 * <p>
071 * On a side note, a surrogate class is functionally equivalent to the following {@link PojoSwap}
072 * implementation:
073 * <p class='bcode w800'>
074 *    <jk>public class</jk> MySurrogate <jk>extends</jk> PojoSwap&lt;NormalClass,MySurrogate&gt; {
075 *       <jk>public</jk> MySurrogate swap(NormalClass o) <jk>throws</jk> SerializeException {
076 *          <jk>return new</jk> MySurrogate(o);
077 *       }
078 *       <jk>public</jk> NormalClass unswap(MySurrogate o, ClassMeta&lt;?&gt; hint) <jk>throws</jk> ParseException {
079 *          <jk>return</jk> o.unswap();
080 *       }
081 *    }
082 * </p>
083 *
084 * <ul class='seealso'>
085 *    <li class='link'>{@doc SurrogateClasses}
086 * </ul>
087 */
088public interface Surrogate {}