Skip to main content

Auto-detected swaps

Various methods can be defined on a class directly to affect how it gets serialized. This can often be simpler than using ObjectSwaps.

Parsing from strings​

Objects serialized as Strings can be parsed back into their original objects by implementing one of the following methods on the class:

  • public static T fromString(String) method.

    Any of the following method names also work:

    • valueOf(String)
    • parse(String)
    • parseString(String)
    • forName(String)
    • forString(String)

  • public T(String) constructor.

Note that these methods cover conversion from several built-in Java types, meaning the parsers can automatically construct these objects from strings:

If your static factory method doesn't match any of those conventional names (e.g. of(String) or create(String)), you can use the @StringCtor annotation on the class to name the exact method to use, short-circuiting the name-based lookup above:

@StringCtor("of")
public class Money {

    public static Money of(String value) {
        return new Money(value);
    }

    ...
}

Classes without @StringCtor continue to fall back to the conventional-name lookup (and then the single-String-arg constructor) described above.

If you want to force a bean-like class to be serialized as a string, you can use the @Marshalled(as=STRING) annotation on the class to force it to be serialized to a string using the toString() method.

Swapping to other objects​

Serializing to other intermediate objects can be accomplished by defining a swap method directly on the class:

  • public X swap() method, where X is any serializable object.
  • public X swap(MarshallingSession) method, where X is any serializable object.
  • public static MyPojo unswap(X) method, where X is any serializable object.
  • public static MyPojo unswap(X,MarshallingSession) method, where X is any serializable object.

Swapping to and from maps​

Serializing to and from Maps can be accomplished by defining any of the following methods:

  • public Map toMap() method.

    Can be any type of map with string keys and object vals.

  • public JsonMap toMap() method.

  • public Map toMap(MarshallingSession) method.

    Can be any type of map with string keys and object vals.

  • public JsonMap toMap(MarshallingSession) method.

  • public static MyPojo fromMap(Map) method.

    Can be any type of map with string keys and object vals.

  • public static MyPojo fromMap(JsonMap) method.

  • public static MyPojo fromMap(Map,MarshallingSession) method.

    Can be any type of map with string keys and object vals.

  • public static MyPojo fromMap(JsonMap,MarshallingSession) method.

Template example​

The MarshallingSession parameter allows you access to various information about the current serialization session. For example, you could provide customized results based on the media type being produced (MarshallingSession.getMediaType()).

The following example shows how an HTML5 form template object can be created that gets serialized as a populated HTML5 Form bean.

import static org.apache.juneau.bean.html5.HtmlBuilder.*;

/**
 * A simple HTML form template whose serialized form is an HTML5 Form object.
 */
public class FormTemplate {

    private String action;
    private int value1;
    private boolean value2;

    // Some constructor that initializes our fields.
    public FormTemplate(String action, int value1, boolean value2) {
        this.action = action;
        this.value1 = value1;
        this.value2 = value2;
    }

    // Special swap method that converts this template to a serializable bean
    public Form swap(MarshallingSession session) {
        return form(action,
            input("text").name("v1").value(value1),
            input("text").name("v2").value(value2)
        );
    }
}

Parsing swapped objects​

Swapped objects can be converted back into their original form by the parsers by specifying one of the following methods:

  • public static T unswap(MarshallingSession, X) method where X is the swap class type.
  • public T(X) constructor where X is the swap class type.

The following shows how our form template class can be modified to allow the parsers to reconstruct our original object:

import static org.apache.juneau.bean.html5.HtmlBuilder.*;

/**
 * A simple HTML form template whose serialized form is an HTML5 Form object.
 * This time with parsing support.
 */
@Marshalled(dictionary=HtmlBeanDictionary.class)
public class FormTemplate {

    private String action;
    private int value1;
    private boolean value2;

    // Our 'unswap' constructor
    public FormTemplate(Form form) {
        this.action = form.getAttr("action");
        this.value1 = form.getChild(Input.class, 0)
            .getAttr(int.class, "value");
        this.value2 = form.getChild(Input.class, 1)
            .getAttr(boolean.class, "value");
    }

    public FormTemplate(String action, int value1, boolean value2) {
        this.action = action;
        this.value1 = value1;
        this.value2 = value2;
    }

    public Form swap(MarshallingSession session) {
        return form(action,
            input("text").name("v1").value(value1),
            input("text").name("v2").value(value2)
        );
    }
}