S11n core API

LambdaLib provided some support for serialization(s11n) of some specific format. Currently, cross-network serialization, XML serialization, and in addition, object copying are supported. NBT serialization support is also intended to be added.

Serialization is supported to be VERY automated, or it will cause hundreds and thousands lines of redundant code, all just trying to write a class to some format and read the instance back from that format. The s11n API is designed to ease this trouble.

The core s11n API specifies how all objects are supposed to be serialized. The object can be classified into two types: direct types and recursive types, which we will discuss below.

Direct Types

Direct types are those whose writing and reading method is directly defined. This usually means that the object can't be subdivided. All primitive types (int, char, boolean, ...), String, and enums are direct types. A s11n API must support the below direct types, but can also add direct types by itself.

Built-in types:

• char
• byte
• short
• int
• float
• double
• boolean
• String

Recursive Types

Recursive types are those whose value can be subdivided into smaller objects, and they each can be serialized. Any object that is not of direct type is of recursive type.

For example:

public class SomeMessage {
String channel;
String player;
String message;
}

This class is a recursive type, because we can serialize this object by serializing all its fields (They are all String and we know how to handle them).

But what if we compose another message upon it?

public class MessagePair {
SomeMessage msg1;
SomeMessage msg2;
}

Actually this class's s11n can be automated too, because we do know how to serialize SomeMessage: by serializing all its fields. Thus, we can serialize type that is not direct using the following pseudocode:

function recursive-s11n(object):
  for field in object's exposed fields:
    if field's type is direct:
      serialize the field's value directly
    else:
      recursive-s11n(field's value)

Thus any object with any hierarchy depth can be serialized. The process is recursive so we call this recursive serialization.

Field expose

By statement above we know that recursive s11n is powerful, but its power will destroy us if we abuse it. A class usually contains lots of information - only part of which we might want to have them serialized. Thus, the core API exposes a public and uniform way to determine exposed fields, and the rule shall apply on all s11n APIs.

To be safe on handling recursive types, we define that a type is to be automatically serialized, only when its marked as an serialization type.

The rule:

1. Only fields of type that is direct or is a serialization type will be included.
2. Only public fields, or those marked with @SerializeIncluded will be included. But those marked with @SerializeExcluded will not be included.
3. @SerializeIncluded will include a field even if its type is NOT a serialize type.
4. You can use @SerializeStrategy annotation to tweak the default rule completely.

The API

The core API is solely a specification on HOW the serialization is to be performed. Any s11n API of LambdaLib will follow this rule, but it's the API's own rule to keep things consistent.

The only useful API is possibly the one controlling how the fields are exposed. cn.lambdalib.s11n.SerializationHelper provides this functionality. It allows you to define serialization types and query what types are serializable.

Below are APIs that are built upon s11n core API:

• CopyHelper
• Network s11n
• XML s11n