org.apache.juneau.transform.Surrogate Maven / Gradle / Ivy
// ***************************************************************************************************************************
// * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file *
// * distributed with this work for additional information regarding copyright ownership. The ASF licenses this file *
// * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance *
// * with the License. You may obtain a copy of the License at *
// * *
// * http://www.apache.org/licenses/LICENSE-2.0 *
// * *
// * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an *
// * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the *
// * specific language governing permissions and limitations under the License. *
// ***************************************************************************************************************************
package org.apache.juneau.transform;
import org.apache.juneau.*;
/**
* Identifies a class as being a surrogate class.
*
*
* Surrogate classes are used in place of other classes during serialization.
* For example, you may want to use a surrogate class to change the names or order of bean properties on a bean.
*
*
* This interface has no methods to implement.
* It's simply used by the framework to identify the class as a surrogate class when specified as a swap.
*
*
* The following is an example of a surrogate class change changes a property name:
*
* public class MySurrogate implements Surrogate {
* public String surrogateField; // New bean property
*
* public MySurrogate(NormalClass normalClass) {
* this .surrogateField = normalClass.normalField;
* }
* }
*
*
*
* Optionally, a public static method can be used to un-transform a class during parsing:
*
* public class MySurrogate implements Surrogate {
* ...
* public static NormalClass toNormalClass (SurrogateClass surrogateClass) {
* return new NormalClass(surrogateClass.transformedField);
* }
* }
*
*
*
* Surrogate classes must conform to the following:
*
* -
* It must have a one or more public constructors that take in a single parameter whose type is the normal types.
* (It is possible to define a class as a surrogate for multiple class types by using multiple constructors with
* different parameter types).
*
-
* It optionally can have a public static method that takes in a single parameter whose type is the transformed
* type and returns an instance of the normal type.
* This is called the un-transform method.
* The method can be called anything.
*
-
* If an un-transform method is present, the class must also contain a no-arg constructor (so that the
* transformed class can be instantiated by the parser before being converted into the normal class by the
* un-transform method).
*
*
*
* Surrogate classes are associated with serializers and parsers using the {@link CoreObjectBuilder#pojoSwaps(Class...)}
* method.
*
* @Test
* public void test() throws Exception {
* JsonSerializer s = new JsonSerializerBuilder().simple().pojoSwaps(MySurrogate.class ).build();
* JsonParser p = new JsonParserBuilder().pojoSwaps(MySurrogate.class ).build();
* String r;
* Normal n = Normal.create ();
*
* r = s.serialize(n);
* assertEquals("{f2:'f1'}" , r);
*
* n = p.parse(r, Normal.class );
* assertEquals("f1" , n.f1);
* }
*
* // The normal class
* public class Normal {
* public String f1;
*
* public static Normal create () {
* Normal n = new Normal();
* n.f1 = "f1" ;
* return n;
* }
* }
*
* // The surrogate class
* public class MySurrogate implements Surrogate {
* public String f2;
*
* // Surrogate constructor
* public MySurrogate(Normal n) {
* f2 = n.f1;
* }
*
* // Constructor used during parsing (only needed if un-transform method specified)
* public MySurrogate() {}
*
* // Un-transform method (optional)
* public static Normal toNormal (Surrogate f) {
* Normal n = new Normal();
* n.f1 = f.f2;
* return n;
* }
* }
*
*
*
* It should be noted that a surrogate class is functionally equivalent to the following {@link PojoSwap}
* implementation:
*
* public static class MySurrogate extends PojoSwap<Normal,MySurrogate> {
* public MySurrogate swap(Normal n) throws SerializeException {
* return new MySurrogate(n);
* }
* public Normal unswap(MySurrogate s, ClassMeta<?> hint) throws ParseException {
* return MySurrogate.toNormal (s);
* }
* }
*
*
*/
public interface Surrogate {}