<?xml version="1.0" encoding="UTF-8"?>
<chapter id="sid-5931328">
   <title>Marshalling</title>
   <para>Errai includes a comprehensive marshalling framework which permits the serialization of domain objects between the browser and the server. From the perspective of GWT, this is a complete replacement for the provided GWT serialization facilities and offers a great deal more flexibility. You are be able to map both application-specific domain model, as well as preexisting model, including model from third-party libraries using the custom definitions API.</para>
   <section id="sid-5931328_Marshalling-MappingYourDomain">
      <title>Mapping Your Domain</title>
      <para>All classes that you intend to be marshalled between the client and the server must be exposed to the marshalling framework. There are several ways you can do it and this section will take you through the different approaches you can take to fit your needs.</para>
      <section id="sid-5931328_Marshalling-@Portableand@NonPortable">
         <title>@Portable and @NonPortable</title>
         <para>
          To make a Java class eligible for serialization with Errai Marshalling, mark it with the
          <code>org.jboss.errai.common.client.api.annotations.Portable</code>
          annotation. This tells the marshalling system to generate marshalling and demarshalling code for the annotated class and all of its nested classes.
        </para>
         <para>
          The mapping strategy that will be used depends on how much information you provide about your model up-front. If you simply annotate a domain type with
          <code>@Portable</code>
          and do nothing else, the marshalling system will use and exhaustive strategy to determine how to construct and deconstruct instances of that type and its nested types.
        </para>
         <para>
          The Errai marshalling system works by enumerating all of the Portable types it can find (by any of the three methods discussed in this section of the reference guide), eliminating all the non-portable types it can find (via
          <code>@NonPortable</code>
          annotations and entries in
          <code>ErraiApp.properties</code>
          ), then enumerating the marshallable properties that make up each remaining portable entity type. The rules that Errai uses for enumerating the properties of a portable entity type are as follows:
        </para>
         <itemizedlist>
            <listitem>
               <para>
              If an entity type has a field called
              <code>foo</code>
              , then that entity has a property called
              <code>foo</code>
              unless the field is marked
              <code>static</code>
              or
              <code>transient</code>
              .
            </para>
            </listitem>
         </itemizedlist>
         <para>
          Note that the existence of methods called
          <code>getFoo()</code>
          ,
          <code>setFoo()</code>
          , or both,
          <emphasis role="italics">does not</emphasis>
          mean that the entity has a property called
          <code>foo</code>
          . Errai Marshalling always works from fields when discovering properties.
        </para>
         <para>
          When reading a field
          <code>foo</code>
          , Errai Marshalling will call the method
          <code>getFoo()</code>
          in preference to direct field access if the
          <code>getFoo()</code>
          method exists.
        </para>
         <para>
          Similarly, when writing a field
          <code>foo</code>
          , Errai Marshalling will call the method
          <code>setFoo()</code>
          in preference to direct field access if the
          <code>setFoo()</code>
          method exists.
        </para>
         <para>
          The above rules are sufficient for marshalling an existing entity to a JSON representation, but for de-marshalling, Errai must also know how to obtain an instance of a type. The rules that Errai uses for deciding how to create an instance of a
          <code>@Portable</code>
          type are as follows:
        </para>
         <itemizedlist>
            <listitem>
               <para>
              If the entity has a public constructor where every argument is annotated with
              <code>@MapsTo</code>
              , and those parameters cover all properties of the entity type, then Errai uses this constructor to create the object, passing in all of the property values.
            </para>
            </listitem>
            <listitem>
               <para>
              Otherwise, if the entity has a public static method where every argument is annotated with
              <code>@MapsTo</code>
              , and those parameters cover all properties of the entity type, then Errai uses this method to create the object. Note that when using this mechanism you are free to create and return a subtype of the marshalled type, or resolve one from a cache.
            </para>
            </listitem>
            <listitem>
               <para>If the entity has a public no-arguments constructor (or no explicit constructors at all), it will be created via that constructor, and the properties will be written to the new object one at a time. Each property will be written by its setter method, or by direct field access if a setter method is not available.</para>
            </listitem>
         </itemizedlist>
         <para>Now let's take a look at some common examples of how this works.</para>
         <section id="sid-5931328_Marshalling-Example%3AASimpleEntity">
            <title>Example: A Simple Entity</title>
            <informalexample>
               <programlisting language="java">
@Portable
public class Person {
  private String name;
  private int age;
  
  public Person() {
  }

  public Person(String name, int age) {
    this.name = name;
    this.age = age;
  }

  public String getName() { 
    return name;
  }

  public int getAge() {
    return age; 
  }
}
</programlisting>
            </informalexample>
            <para>This is a pretty vanilla domain object. Note the default, public, no-argument constructor. In this case, it will be necessary to have one explicitly declared. But notice we have no setters. In this case, the marshaler will rely on private field access to write the values on each side of the marshalling transaction. For simple domain objects, this is both nice and convenient. But you may want to make the class immutable and have a constructor enforce invariance. See the next section for that.</para>
         </section>
         <section id="sid-5931328_Marshalling-Example%3AAnImmutableEntitywithaPublicConstructor">
            <title>Example: An Immutable Entity with a Public Constructor</title>
            <para>Immutability is almost always a good practice, and the marshalling system provides you a straight forward way to tell it how to marshal and de-marshal objects which enforce an immutable contract. Let's modify our example from the previous section.</para>
            <informalexample>
               <programlisting language="java">
@Portable
public class Person {
  private final String name;
  private final int age;
  
  public Person(@MapsTo("name") String name, @MapsTo("age") int age) {
    this.name = name;
    this.age = age;
  }

  public String getName() { 
    return name;
  }

  public int getAge() {
    return age; 
  }
}
</programlisting>
            </informalexample>
            <para>
            Here we have set both of the class fields final. By doing so, we had to remove our default constructor. But that's okay, because we have annotated the remaining constructor's parameters using the
            <code>org.jboss.errai.marshalling.client.api.annotations.MapsTo</code>
            annotation.
          </para>
            <para>
            By doing this, we have told the marshaling system, for instance, that the first parameter of the constructor maps to the property
            <code>name</code>
            . Which in this case, defaults to the name of the corresponding field. This may not always be the case – as will be explored in the section on custom definitions. But for now that's a safe assumption.
          </para>
         </section>
         <section id="sid-5931328_Marshalling-Example%3AAnImmutableEntitywithaFactoryMethod">
            <title>Example: An Immutable Entity with a Factory Method</title>
            <para>Another good practice is to use a factory pattern to enforce invariance. Once again, let's modify our example.</para>
            <informalexample>
               <programlisting language="java">
@Portable
public class Person {
  private final String name;
  private final int age;
  
  private Person(String name, int age) {
    this.name = name;
    this.age = age;
  }
  
  public static Person createPerson(@MapsTo("name") String name, @MapsTo("age") int age) {
    return new Person(name, age);
  }

  public String getName() { 
    return name;
  }

  public int getAge() {
    return age; 
  }
}
</programlisting>
            </informalexample>
            <para>
            Here we have made our only declared constructor private, and created a static factory method. Notice that we've simply used the same
            <code>@MapsTo</code>
            annotation in the same way we did on the constructor from our previous example. The marshaller will see this method and know that it should use it to construct the object.
          </para>
         </section>
         <section id="sid-5931328_Marshalling-Example%3AAnImmutableEntitywithaBuilder">
            <title>Example: An Immutable Entity with a Builder</title>
            <para>For types with a large number of optional attributes, a builder is often the best approach.</para>
            <informalexample>
               <programlisting language="java">
@Portable
public class Person {
  private final String name;
  private final int age;
  
  private Person(@MapsTo("name") String name, @MapsTo("age") int age) {
    this.name = name;
    this.age = age;
  }
  
  public String getName() { 
    return name;
  }

  public int getAge() {
    return age; 
  }

  @NonPortable
  public static class Builder {
    private String name;
    private int age;

    public Builder name(String name) {
      this.name = name;
      return this;
    }

    public Builder age(int age) {
      this.age = age;
      return this;
    }

    public BuilderEntity build() {
      return new Person(name, age);
    }
  }
}
</programlisting>
            </informalexample>
            <para>
            In this example, we have a nested
            <code>Builder</code>
            class that implements the Builder Pattern and calls the private
            <code>Person</code>
            constructor. Hand-written code will always use the builder to create
            <code>Person</code>
            instances, but the
            <code>@MapsTo</code>
            annotations on the private
            <code>Person</code>
            constructor tell Errai Marshalling to bypass the builder and construct instances of Person directly.
          </para>
            <para>
            One final note: as a nested type of
            <code>Person</code>
            (which is marked
            <code>@Portable</code>
            ), the builder itself would normally be portable. However, we do not intend to move instances of
            <code>Person.Builder</code>
            across the network, so we mark
            <code>Person.Builder</code>
            as
            <code>@NonPortable</code>
            .
          </para>
         </section>
      </section>
      <section id="sid-5931328_Marshalling-ManualMapping">
         <title>Manual Mapping</title>
         <para>Some classes may be out of your control, making it impossible to annotate them for auto-discovery by the marshalling framework. For cases such as this, there are two approaches which can be undertaken to include these classes in your application.</para>
         <para>
          The first approach is the easiest, but is contingent on whether or not the class is directly exposed to the GWT compiler. That means, the classes must be part of a GWT module and within the GWT client packages. See the GWT documentation on
          <ulink url="http://code.google.com/webtoolkit/doc/latest/DevGuideCodingBasicsClient.html">Client-Side Code</ulink>
          for information on this.
        </para>
         <section id="sid-5931328_Marshalling-MappingExistingClientClasses">
            <title>Mapping Existing Client Classes</title>
            <para>
            If you have client-exposed classes that cannot be annotated with the
            <code>@Portable</code>
            annotation, you may manually map these classes so that the marshaller framework will comprehend and produce marshallers for them and their nested types.
          </para>
            <para>
            To do this, specify them in
            <emphasis role="strong">ErraiApp.properties</emphasis>
            , using the
            <code>errai.marshalling.serializableTypes</code>
            attribute with a whitespace separated list of classes to make portable.
          </para>
            <example>
               <title>Example ErraiApp.properties defining portable classes.</title>
               <programlisting language="ini">
errai.marshalling.serializableTypes=org.foo.client.UserEntity \
                                    org.foo.client.GroupEntity \
                                    org.abcinc.model.client.Profile
</programlisting>
            </example>
            <para>If any of the serializable types have nested classes that you wish to make non-portable, you can specify them like this:</para>
            <example>
               <title>Example ErraiApp.properties defining nonportable classes.</title>
               <programlisting language="ini">
errai.marshalling.nonserializableTypes=org.foo.client.UserEntity$Builder \
                                       org.foo.client.GroupEntity$Builder
</programlisting>
            </example>
         </section>
         <section id="sid-5931328_Marshalling-AliasedMappingsofExistingInterfaceContracts">
            <title>Aliased Mappings of Existing Interface Contracts</title>
            <para>
            The marshalling framework supports and promotes the concept of marshalling by interface contract, where possible. For instance, the framework ships with a marshaller which can marshall data to and from the
            <code>java.util.List</code>
            interface. Instead of having custom marshallers for classes such as
            <code>ArrayList</code>
            and
            <code>LinkedList</code>
            , by default, these implementations are merely aliased to the
            <code>java.util.List</code>
            marshaller.
          </para>
            <para>
            There are two distinct ways to go about doing this. The most straightforward is to specify which marshaller to alias when declaring your class is
            <code>@Portable</code>
            .
          </para>
            <informalexample>
               <programlisting language="java">
package org.foo.client;

@Portable(aliasOf = java.util.List.class)
public MyListImpl extends ArrayList {
  // .. //
}
</programlisting>
            </informalexample>
            <para>
            In the case of this example, the marshaller will not attempt to comprehend your class. Instead, it will merely rely on the
            <code>java.util.List</code>
            marshaller to dematerialize and serialize instances of this type onto the wire.
          </para>
            <para>
            If for some reason it is not feasible to annotate the class, directly, you may specify the mapping in the
            <emphasis role="strong">ErraiApp.properties</emphasis>
            file using the
            <code>errai.marshalling.mappingAliases</code>
            attribute.
          </para>
            <informalexample>
               <programlisting language="ini">
errai.marshalling.mappingAliases=org.foo.client.MyListImpl-&gt;java.util.List \
                                 org.foo.client.MyMapImpl-&gt;java.util.Map

</programlisting>
            </informalexample>
            <para>The list of classes is whitespace-separated so that it may be split across lines.</para>
            <para>
            The example above shows the equivalent mapping for the
            <code>MyListImpl</code>
            class from the previous example, as well as a mapping of a class to the
            <code>java.util.Map</code>
            marshaller.
          </para>
            <para>
            The syntax of the mapping is as follows:
            <code>&lt;class_to_map&gt;</code>
               <emphasis role="strong">-&gt;</emphasis>
               <code>&lt;contract_to_map_to&gt;</code>
            .
          </para>
            <important>
               <title>Aliases do not inherit functionality!</title>
               <para>When you alias a class to another marshalling contract, extended functionality of the aliased class will not be available upon deserialization. For this you must provide custom marshallers for those classes.</para>
            </important>
         </section>
      </section>
      <section id="sid-5931328_Marshalling-ManualClassMapping">
         <title>Manual Class Mapping</title>
         <para>Although the default marshalling strategies in Errai Marshalling will suit the vast majority of use cases, there may be situations where it is necessary to manually map your classes into the marshalling framework to teach it how to construct and deconstruct your objects.</para>
         <para>
          This is accomplished by specifying
          <code>MappingDefinition</code>
          classes which inform the framework exactly how to read and write state in the process of constructing and deconstructing objects.
        </para>
         <section id="sid-5931328_Marshalling-MappingDefinition">
            <title>MappingDefinition</title>
            <para>
            All manual mappings should extend the
            <code>org.jboss.errai.marshalling.rebind.api.model.MappingDefinition</code>
            class. This is base metadata class which contains data on exactly how the marshaller can deconstruct and construct objects.
          </para>
            <para>Consider the following class:</para>
            <informalexample>
               <programlisting language="java">
public class MySuperCustomEntity {
   private final String mySuperName;
   private String mySuperNickname;

   public MySuperCustomEntity(String mySuperName) {
     this.mySuperName = mySuperName;;
   }

   public String getMySuperName() {
     return this.mySuperName;
   } 

   public void setMySuperNickname(String mySuperNickname) {
     this.mySuperNickname = mySuperNickname;
   }

   public String getMySuperNickname() {
     return this.mySuperNickname;
   }
}
</programlisting>
            </informalexample>
            <para>Let us construct this object like so:</para>
            <informalexample>
               <programlisting language="java">
  MySuperCustomEntity entity = new MySuperCustomEntity("Coolio");
  entity.setSuperNickname("coo");
</programlisting>
            </informalexample>
            <para>
            It is clear that we may rely on this object's two getter methods to extract the totality of its state. But due to the fact that the
            <code>mySuperName</code>
            field is final, the only way to properly construct this object is to call its only public constructor and pass in the desired value of
            <code>mySuperName</code>
            .
          </para>
            <para>Let us consider how we could go about telling the marshalling framework to pull this off:</para>
            <informalexample>
               <programlisting language="java">
@CustomMapping
public MySuperCustomEntityMapping extends MappingDefinition {
  public MySuperCustomEntityMapping() {
    super(MySuperCustomEntity.class);                                                          // (1)

    SimpleConstructorMapping cnsMapping = new SimpleConstructorMapping(); 
    cnsMapping.mapParmToIndex("mySuperName", 0, String.class);                                 // (2)

    setInstantiationMapping(cnsMapping);

    addMemberMapping(new WriteMapping("mySuperNickname", String.class, "setMySuperNickname")); // (3)
    
    addMemberMapping(new ReadMapping("mySuperName", String.class, "getMySuperName"));          // (4)
    addMemberMapping(new ReadMapping("mySuperNickname", String.class, "getMySuperNickname"));  // (5)
  }
}
</programlisting>
            </informalexample>
            <para>
            And that's it. This describes to the marshalling framework how it should go about constructing and deconstructing
            <code>MySuperCustomEntity</code>
            .
          </para>
            <para>Paying attention to our annotating comments, let's describe what we've done here.</para>
            <orderedlist inheritnum="ignore" continuation="restarts">
               <listitem>
                  <para>
                Call the constructor in
                <code>MappingDefinition</code>
                passing our reference to the class we are mapping.
              </para>
               </listitem>
               <listitem>
                  <para>
                Using the
                <code>SimpleConstructorMapping</code>
                class, we have indicated that a custom constructor will be needed to instantiate this class. We have called the
                <code>mapParmToIndex</code>
                method with three parameters. The first,
                <code>"mySupername"</code>
                describes the class field that we are targeting. The second parameter, the integer
                <code>0</code>
                indicates the parameter index of the constructor arguments that we'll be providing the value for the aforementioned field – in this case the first and only, and the final parameter
                <code>String.class</code>
                tells the marshalling framework which marshalling contract to use in order to de-marshall the value.
              </para>
               </listitem>
               <listitem>
                  <para>
                Using the
                <code>WriteMapping</code>
                class, we have indicated to the marshaller framework how to write the
                <code>"mySuperNickname"</code>
                field, using the
                <code>String.class</code>
                marshaller, and using the setter method
                <code>setMySuperNickname</code>
                .
              </para>
               </listitem>
               <listitem>
                  <para>
                Using the
                <code>ReadMapping</code>
                class, we have indicated to the marshaller framework how to read the
                <code>"mySuperName"</code>
                field, using the
                <code>String.class</code>
                marshaller, and using the getter method
                <code>getMySuperName</code>
                .
              </para>
               </listitem>
               <listitem>
                  <para>
                Using the
                <code>ReadMapping</code>
                class, we have indicated to the marshaller framework how to read the
                <code>"mySuperNickname"</code>
                field, using the
                <code>String.class</code>
                marshaller, and using the getter method
                <code>getMySuperNickname</code>
                .
              </para>
               </listitem>
            </orderedlist>
         </section>
      </section>
      <section id="sid-5931328_Marshalling-CustomMarshallers">
         <title>Custom Marshallers</title>
         <para>
          There is another approach to extending the marshalling functionality that doesn't involve mapping rules, and that is to implement your own
          <code>Marshaller</code>
          class.  This gives you complete control over the parsing and emission of the JSON structure.
        </para>
         <para>The implementation of marshallers is made relatively straight forward by the fact that both the server and the client share the same JSON parsing API.</para>
         <para>
          Consider the included
          <code>java.util.Date</code>
          marshaller that comes built-in to the marshalling framework:
        </para>
         <example>
            <title>DataMarshaller.java from the built-in marshallers</title>
            <programlisting language="java">
@ClientMarshaller @ServerMarshaller
public class DateMarshaller extends AbstractNullableMarshaller&lt;Date&gt; {
  @Override
  public Class&lt;Date&gt; getTypeHandled() {
    return Date.class;
  }

  @Override
  public Date demarshall(EJValue o, MarshallingSession ctx) {
    // check if the JSON element is null
    if (o.isNull() != null) {
      // if the JSON element is null, so is our object!
      return null;
    }

    // instantiate our Date!
    return new Date(Long.parseLong(o.isObject().get(SerializationParts.QUALIFIED_VALUE).isString().stringValue()));
  }

  @Override
  public String marshall(Date o, MarshallingSession ctx) {
    // if the object is null, we encode "null"
    if (o == null) { return "null"; }

    // return the JSON representation of the object
    return "{\"" + SerializationParts.ENCODED_TYPE + "\":\"" + Date.class.getName() + "\"," +
            "\"" + SerializationParts.OBJECT_ID + "\":\"" + o.hashCode() + "\"," +
            "\"" + SerializationParts.QUALIFIED_VALUE + "\":\"" + o.getTime() + "\"}";
  }
}
</programlisting>
         </example>
         <para>
          The class is annotated with both
          <code>@ClientMarshaller</code>
          and
          <code>@ServerMarshaller</code>
          indicating that this class should be used for both marshalling on the client and on the server.
        </para>
         <para>
          The
          <code>demarshall()</code>
          method does what its name implies: it is responsible for demarshalling the object from JSON and turning it back into a Java object.
        </para>
         <para>
          The
          <code>marshall()</code>
          method does the opposite, and encodes the object into JSON for transmission on the wire.
        </para>
      </section>
   </section>
</chapter>
