{8.1.0-new} Auto-detected POJO swaps

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

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:

- fromString(String) - {@link java.util.UUID}
- valueOf(String) - {@link java.lang.Boolean}, {@link java.lang.Byte}, {@link java.lang.Double}, {@link java.lang.Float}, {@link java.lang.Integer}, {@link java.lang.Long}, {@link java.lang.Short}, {@link java.sql.Date}, {@link java.sql.Time}, {@link java.sql.Timestamp}
- parse(String) - {@link java.text.DateFormat}, {@link java.text.MessageFormat}, {@link java.text.NumberFormat}, {@link java.util.Date}, {@link java.util.logging.Level}
- parseString(String) - {@link javax.xml.bind.DatatypeConverter}
- forName(String) - {@link java.lang.Class}

If you want to force a bean-like class to be serialized as a string, you can use the {@link oaj.annotation.BeanIgnore @BeanIgnore} annotation on the class to force it to be serialized to a string using the toString() method.

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(BeanSession) method, where X is any serializable object.
- public static MyPojo unswap(X) method, where X is any serializable object.
- public static MyPojo swap(X,BeanSession) method, where X is any serializable object.

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 OMap toMap() method.
- public Map toMap(BeanSession) method. Can be any type of map with string keys and object vals.
- public OMap toMap(BeanSession) method.
- public static MyPojo fromMap(Map) method. Can be any type of map with string keys and object vals.
- public static MyPojo fromMap(OMap) method.
- public static MyPojo fromMap(Map,BeanSession) method. Can be any type of map with string keys and object vals.
- public static MyPojo fromMap(OMap,BeanSession) method.

The BeanSession 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 ({@link oaj.BeanSession#getMediaType()}).

The following example shows how an HTML5 form template object can be created that gets serialized as a populated HTML5 {@link oaj.dto.html5.Form} bean.

import static org.apache.juneau.dto.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(BeanSession session) { return form(action, input("text").name("v1").value(value1), input("text").name("v2").value(value2) ); } }

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

- public static T unswap(BeanSession, 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.dto.html5.HtmlBuilder.*; /** * A simple HTML form template whose serialized form is an HTML5 Form object. * This time with parsing support. */ @Bean(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(BeanSession session) { return form(action, input("text").name("v1").value(value1), input("text").name("v2").value(value2) ); } }