== Why use Marshallable objects.

Marshallable object have been designed to allow you to

- write a simple POJO
- have the `toString()`, `hashCode()` and `equals(Object)` methods created for you.
- serialization to a human readable format (based on YAML), as well as efficient binary formats.
- the string format for text and binary can be logged and reconstructed from the text or hexi-decimal dump
- copying and conversion of data from one type to another

== Pojo Example
The following is a simple example of a POJO with a nested data type in a List.

.A Simple Pojo without needing to define toString/hashCode/equals
[source, java]
----
class MyPojo extends AbstractMarshallable {
    String text;
    int num;
    double factor;

    public MyPojo(String text, int num, double factor) {
        this.text = text;
        this.num = num;
        this.factor = factor;
    }
}

class MyPojos extends AbstractMarshallable {
    String name;
    List<MyPojo> myPojos = new ArrayList<>();

    public MyPojos(String name) {
        this.name = name;
    }
}
----

By extending `AbstractMarshallable` the class has an implementation
 for `readMarshallable(WireIn)`, `writeMarshallable(WireOut)` and from these
 `toString()`, `hashCode()` and `equals(Object)`.  You only need to define the method
  yourself for improved efficiency.  These default implementations can give you
  2/3rds of the performance of hand coding but save time and potential errors
  writing them yourself.

=== The toString()
A important feature of the toString() method is no information is lost.  The object can be reconstructed from
the text of the toString() method.  This is useful for building sample data in unit tests for from a file.
It also means that you can take the dump of an object in a log file and reconstruct the original object.

[source, java]
----
MyPojos mps = new MyPojos("test-list");
mps.myPojos.add(new MyPojo("text1", 1, 1.1));
mps.myPojos.add(new MyPojo("text2", 2, 2.2));

System.out.println(mps); // <1>
----
<1> Uses the default `toString()` provided

prints

[source, yaml]
----
!MyPojos {
  name: test-list,
  myPojos: [
    { text: text1, num: 1, factor: 1.1 },
    { text: text2, num: 2, factor: 2.2 }
  ]
}
----

You can take this same output and reconstruct the original object

[source, java]
----
MyPojos mps2 = Marshallable.fromString(mps.toString());
assertEquals(mps, mps2); // <1>

String text = "!MyPojos {\n" +
        "  name: test-list,\n" +
        "  myPojos: [\n" +
        "    { text: text1, num: 1, factor: 1.1 },\n" +
        "    { text: text2, num: 2, factor: 2.2 }\n" +
        "  ]\n" +
        "}\n";
MyPojos mps3 = Marshallable.fromString(text);
assertEquals(mps, mps3); // <1>
----
<1> `AbstractMarshallable` also provides a default `equals(Object)` and `hashCode()`

Finally you can take data from a file and build the object

[source, java]
----
MyPojos mps4 = Marshallable.fromFile("my-pojos.yaml");
assertEquals(mps, mps4);
----
