Core

FlatPack Core Apis

This document describes the various functional parts of the FlatPack stack.

Entities

An entity is a POJO-like object (having getters and setters) that implements the HasUuid interface. An entity's UUID is distinct from the its primary database key. By using UUIDs to identify entities instead of database keys, it avoids the problem of having to juggle ephemeral and persistent ids for entities created by a client before they are persisted by the server.

The utility type BaseHasUuid provides a default implementation of HasUuid. It's defaultUuid() method may be overridden for value-like entities (see EntityDescription).

Properties

Properties of the following types are supported:

• All primitives and their boxed counterparts
• Enums
• java.util.UUID
• Other entities
• Lists, Sets, and arrays of any supported type
• Maps with keys of strings or entities and values of any supported type
• Any value type with a String or Object one-arg contractor, serialized as its toString() representation, including alljoda-time types
• com.google.gson.JsonElement or its subtypes

Type-specific serialization code is contained in subclasses of Codex and support for additional types may be added to a FlatPack stack with a CodexMapper.

Creating a FlatPack stack

An instance of FlatPack is constructed by creating a Configuration object and calling FlatPack.create().

Configuration configuration = new Configuration()
    .addTypeSource(new SearchTypeSource("com.example.domain")
    .withIgnoreUnresolvableTypes(true);
FlatPack flatpack = FlatPack.create(configuration);

The FlatPack type provides access to three service objects: Packer, Unpacker, and TypeContext. The first two types are used to serialize and deserialize FlatPackEntity instances, which are an intermediate representation of the payload. The TypeContext provides access to the FlatPack type system.

Instances of all FlatPack public APIs are immutable and thread-safe.

FlatPackEntity

A FlatPackEntity is a description of a serialized payload. It has property accessors that correspond to the structures in the wire format and also allows control over how a specific payload should be serialized.

value

Each payload has a single root value property, which is accessed via get / withValue(). The FlatPackEntity type is parameterized based on the type of the value that the payload is expected to contain.

Due to the lack of generic type literals in the Java language, FlatPackEntity implements a type-reference pattern to tell Unpacker how to interpret the top-level value in a payload. If one of the predefined factory methods doesn't match the kind of data that you have, an anonymous subtype must be constructed with the desired parameterization.

// A sample of some of the convenience factory methods
FlatPackEntity.create(someMerchantLocation);
FlatPackEntity.collectionOf(MerchantLocation.class).withValue(someList);
FlatPackEntity.stringMapOf(MerchantLocation.class).withValue(someMapOfStringToLocation);

// Constructing a FlatPackEntity with arbitrary parameterization
new FlatPackEntity<List<UUID>>(){}.withValue(Arrays.asList(uuid1, uuid2));

data

During serialization, the root value object is recursively scanned for references to other entities. Every entity encountered is added once to the data section of the payload. The TraversalMode may be set to one of three values: SIMPLE, SPARSE, or DEEP. The default, SIMPLE, skips any property determined to be deep-traversal-only (see Annotations, to avoid excessively large payloads. The DEEP mode enables traversal of these kinds of properties. The SPARSE mode disables scanning entirely.

Entities that are not reachable from the root value (e.g. out-of-band data or when SPARSE mode is enabled) can be added to the data section with the the addExtraEntity() methods.

Entities that implements HasTimestamps can be elided from a serialized payload by calling withLastModifiedTime().

Users using role-based property access will provide a java.security.Principal to the Packer via withPrincipal().

errors, warnings

The errors and warnings segments are set with addError() and addWarning. A convenience method addConstraintViolations() will map a set of ConstraintViolation objects in the errors segment.