The Polygene™ Core Runtime use Serialization to provide string representation of ValueComposites via their toString() method, and, their instantiation from the very same representation via the newValueFromSerializedState(..) method of the ValueBuilderFactory API.

public interface SomeValue // (1)
{
    Property<String> foo();
}

@Override
public void assemble( ModuleAssembly module )
{
    module.values( SomeValue.class ); // (2)
      [...snip...]

    module.defaultServices(); // (3)
      [...snip...]

}
  [...snip...]

public void defaultSerialization()
{
    SomeValue someValue = someNewValueInstance(); // (4)
    String json = someValue.toString(); // (5)
    SomeValue someNewValue = valueBuilderFactory.newValueFromSerializedState( SomeValue.class, json ); // (6)
      [...snip...]

}

In each Module, if no Serialization service is assembled, a default one supporting the JSON format is used.

public interface SomeValue // (1)
{
    Property<String> foo();
}

@Override
public void assemble( ModuleAssembly module )
{
    module.values( SomeValue.class ); // (2)
      [...snip...]

    new JavaxJsonSerializationAssembler().assemble( module ); // (3)
      [...snip...]

}
  [...snip...]

@Service
private Serializer serializer; // (4)
@Service
private Deserializer deserializer; // (4)

  [...snip...]

public void assembledDefaultServiceSerialization()
{
    SomeValue someValue = someNewValueInstance(); // (5)
    String json = serializer.serialize( someValue ); // (6)
    SomeValue someNewValue = deserializer.deserialize( module, SomeValue.class, json ); // (7)
      [...snip...]

}

The Core SPI provides adapters for text or bytes based serialization, extends the following types to implement a custom serialization.

For text based serialization:

/**
 * Base Text Serializer.
 *
 * Implementations work on Strings, this base serializer encode these strings in UTF-8 to produce bytes.
 *
 * See {@link AbstractTextDeserializer}.
 */
public abstract class AbstractTextSerializer extends AbstractSerializer

/**
 * Base Text Deserializer.
 *
 * Implementations work on Strings, this base deserializer decode bytes in UTF-8 to produce strings.
 *
 * See {@link AbstractTextSerializer}.
 */
public abstract class AbstractTextDeserializer extends AbstractDeserializer

For bytes based serialization:

/**
 * Base Binary Serializer.
 *
 * Implementations work on bytes, this base serializer encode these bytes in Base64 to produce Strings.
 *
 * See {@link AbstractBinaryDeserializer}.
 */
public abstract class AbstractBinarySerializer extends AbstractSerializer

/**
 * Base Binary Deserializer.
 *
 * Implementations work on bytes, this base deserializer decode Strings from Base64 to produce bytes.
 *
 * See {@link AbstractBinarySerializer}.
 */
public abstract class AbstractBinaryDeserializer extends AbstractDeserializer

The Core SPI provides JSON and XML serialization respectively based on javax.json and javax.xml types and APIs to work directly with these types so you can work with the actual object representations without serializing to text or bytes. They both rely on the text serialization adapters shown above.

Here is an example using the JsonSerialization service:

@Service
JsonSerialization jsonSerialization;
  [...snip...]

    try( UnitOfWork uow = unitOfWorkFactory.newUnitOfWork() )
    {
        Some valueInstance = buildSomeValue( moduleInstance, uow, "42" );

        // Serialize using injected service
        JsonValue serializedJson = jsonSerialization.toJson( valueInstance );
        System.out.println( serializedJson.toString() );

        // Deserialize using Module API
        Some valueFromSerializedState = moduleInstance.newValueFromSerializedState( Some.class, serializedJson.toString() );
        assertThat( "Deserialized Value equality", valueInstance, equalTo( valueFromSerializedState ) );
          [...snip...]

    }

And another using the XmlSerialization service:

@Service
XmlSerialization xmlSerialization;
  [...snip...]

    try( UnitOfWork uow = unitOfWorkFactory.newUnitOfWork() )
    {
        Some valueInstance = buildSomeValue( moduleInstance, uow, "42" );

        // Serialize using injected service
        String serializedXml = xmlSerialization.serialize( valueInstance );
        System.out.println( serializedXml );

        // Deserialize using Module API
        Some valueFromSerializedState = moduleInstance.newValueFromSerializedState( Some.class, serializedXml );
        assertThat( "Deserialized Value equality", valueInstance, equalTo( valueFromSerializedState ) );
          [...snip...]

    }

Simply implement Serialization to create an extension for the Serialization SPI. The Core SPI module provides adapters to create Serializers and Deserializers.

The behaviour described here apply to all Serialization services implemented using the Core SPI adapters. Note that nothing stops you from implementing an extension for the Serialization SPI without relying on theses adapters.

Theses adapters are tailored for serialization mechanisms that support the following two structures that can be nested:

in other words, a JSON-like structure.