SpongePowered/SpongeAPI — pull request #272 by gabizou (2014-12-10 02:43:50+00:00)
Title: [WIP] Persistence API

Persistence API introduces the common data structure to represent any possible data produced by the SpongeAPI.

This adds interfaces for `DataContainer`, `DataView`, and `DataOptions`.

Being that these data structures are map based, serialization to various data handlers, such as NBT, flat file, SQL, etc. is possible.

As well, adding annotations for `SerializableAs` and `DataPath` to mark methods and fields with keys that can easily be referenced for automated serialization (example: Gson).
Example usage:
```java
@SerializableAs("Banner")
public interface BannerData extends DataSerializable {

@DataPath("id") String getId();

@DataPath(collapse = true) Vec3i getPosition();

@DataPath("base") DyeColor getBaseColor();

@DataPath(key = "patterns") List getPatterns();

@SerializableAs(key = "pattern", compoundable = true)
interface BannerPattern extends DataSerializable {

// Since banners use dye to create their colors
@DataPath("color") DyeColor getColor();

@DataPath("pattern") List getPatterns();

}

void setPosition(Vec3i pos);
void setColor(DyeColor color);
void setPatterns(List patterns);
void setPattern(BannerPattern pattern);

}

@SerializableAs(key = "position", compoundable = true)
public class Vec3i implements DataSerializable {

@DataPath("x") int x;
@DataPath("y") int y;
@DataPath("z") int z;

}
```

Finally, displaying the importance of the viability for `BannerData` as a `DataContainer`, the following would exist:

```
"Banner" // Name of the DataContainer
|- "id" -> String
|- "x" -> Integer
|- "y" -> Integer
|- "z" -> Integer
|- "base" -> DyeColor
|- "patterns" -> List
|- "BannerPattern" -> BannerPattern
|- "pattern" -> String
|- "color" -> DyeColor
|- "BannerPattern" -> BannerPattern
|- "pattern" -> String
|- "color" -> DyeColor
|- "BannerPattern" -> BannerPattern
|- "pattern" -> String
|- "color" -> DyeColor
```
As visible in the example, the map based data structure, `DataContainer#getString("id")` would return the actual string id provided from the `BannerData` and likewise,
`DyeColor color = BannerData.serialize().getList("patterns").get(0).getSerializable("color", DyeColor.class);`

In essence, we can now safely use these maps to not only serialize and deserialize SpongeAPI objects, but internally, we can use various implementations to not just translate, but manipulate similar data structures in NBT (like in this case, banner data).

Likewise, all of the `DataContainer` system is designed to allow serializing `EntitySnapshots` for various reasons.