Terasology/subsystems/TypeHandlerLibrary

TypeHandlerLibrary

It is really not subsystem. but used by them

A library of type handlers. This is used for the construction of class metadata. This library should be initialised by adding a number of base type handlers, describing how to serialize each supported type. It will then produce serializers for classes (through their ClassMetadata) on request.

Type handlers provide the algorithms for serializing and deserializing types - this uses an implementation agnostic set of interfaces so TypeHandlers can be used for different serialization techniques (Json, Protobuf, etc).

Structure

• Serializer - central class for (de)serialization.
• TypeHandlerLibrary - core class for registering TypeHandlerFactorys
• TypeHandlerFactory - factory for TypeHandlers
• TypeHandler - interface for handling convertiong from <your class> to PersistentData and otherwise.
• PersistedData - interface for target format/protocol(e.g. gson/protobuf)
• PersistedDataSerializer - interface for creating/filling PersistedData
• PersistedDataWriter - interface for writing PersistedData to bytes or outputStream
• PersistedDataReader - interface for reading PersistedData from bytes or inputStream

Usage

1. Create Serializer:

   Serializer serializer = new Serializer(
           typeHandlerLibrary, // Previosly filled with your TypeHandlers
           persistedDataSerializer, // format implementation
           persistedDataWriter, // format implementation
           persistedDataReader, // format implementation
   )
   

2. Serialize:

   serializer.serialize(
                      obj, // Your object to serialize
                      TypeInfo.of(YourClass.class), // Type of obj (also can handle generic types)
                      outputStream); // Output stream for writing. 
   

   or

   byte[] bytes = serializer.serialize(
                      obj, // Your object to serialize
                      TypeInfo.of(YourClass.class)); // Type of obj (also can handle generic types)     
   

3. Deserialize:

   Optional<YourClass> obj = serializer.deserialize(  
                       TypeInfo.of(YourClass.class), // Type of obj (also can handle generic types)
                       inputStream); // Input Stream for reading.
   

   or

   byte[] bytes; // your format data in bytes; 
   Optional<YourClass> obj =  serializer.deserialize(
                      TypeInfo.of(YourClass.class), // Type of obj (also can handle generic types)
                      bytes);     
   

(De)Serialization Process

Serialization: Deserialization:

Implement your own format

You should implements:

1. PersistedData - for storing your format data.
2. PersistedDataSerializer - for creating your PersistedData from TypeHandler
3. PersistedDataWriter - for writing your PersistedData to outputStream or bytes
4. PersistedDataReader - for reading your PersistedData from inputStream or bytes

Implement your own handler for java type

Just implement TypeHandler and register it in TypeHandlerLibrary

Example( BooleanTypeHandler from coreTypes ):

public class BooleanTypeHandler extends TypeHandler<Boolean> {

    @Override
    public PersistedData serializeNonNull(Boolean value, PersistedDataSerializer serializer) {
        return serializer.serialize(value);
    }

    @Override
    public Optional<Boolean> deserialize(PersistedData data) {
        if (data.isBoolean()) {
            return Optional.of(data.getAsBoolean());
        }
        return Optional.empty();
    }

}

Or implement TypeHandlerFactory and register it in TypeHandlerLibrary