eu.toolchain.serializer.SerializerFramework Maven / Gradle / Ivy
package eu.toolchain.serializer;
import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.nio.ByteBuffer;
import java.nio.channels.ReadableByteChannel;
import java.nio.channels.WritableByteChannel;
import java.util.BitSet;
import java.util.List;
import java.util.Map;
import java.util.NavigableMap;
import java.util.NavigableSet;
import java.util.Optional;
import java.util.Set;
import java.util.SortedMap;
import java.util.SortedSet;
import java.util.UUID;
/**
* Serialization Framework.
*
* This type is the entry-point to everything regarding serialization.
*
*
Fixed vs. Variable Width Serializers
*
* A fixed-width {@link Serializer} always marshalls the value into the same number of bytes.
*
* A variable-width {@link Serializer} encodes the value using a varying number of bytes, typically
* to reduce the size for more frequent numerals.
*
* @author udoprog
*/
public interface SerializerFramework {
/**
* A fixed-length {@link Serializer} for {@link String}s.
*/
public Serializer string();
/**
* A fixed-length {@link Serializer} for {@link Byte}s.
*/
public Serializer fixedByte();
/**
* A fixed-length {@link Serializer} for {@link Boolean}s.
*/
public Serializer fixedBoolean();
/**
* A fixed-length {@link Serializer} for {@link Short}s.
*/
public Serializer fixedShort();
/**
* A fixed-length {@code Serializer} for {@link Integer}s.
*/
public Serializer fixedInteger();
/**
* A fixed-length {@link Serializer} for {@link Long}s.
*/
public Serializer fixedLong();
/**
* A fixed-length {@link Serializer} for {@link Float}s.
*/
public Serializer fixedFloat();
/**
* A fixed-length {@link Serializer} for {@link Double}s.
*/
public Serializer fixedDouble();
/**
* A fixed-length {@link Serializer} for {@link Character}s.
*/
public Serializer fixedCharacter();
/**
* A variable-length {@link Serializer} for {@link Integer}s.
*/
public Serializer variableInteger();
/**
* A variable-length {@link Serializer} for {@link Long}s.
*/
public Serializer variableLong();
/* deprecated */
/**
* @see #fixedBoolean()
*/
@Deprecated
public Serializer bool();
/**
* @see #fixedShort()
*/
@Deprecated
public Serializer shortNumber();
/**
* @see #fixedInteger()
*/
@Deprecated
public Serializer integer();
/**
* @see #fixedLong()
*/
@Deprecated
public Serializer longNumber();
/**
* @see #fixedFloat()
*/
@Deprecated
public Serializer floatNumber();
/**
* @see #fixedDouble()
*/
@Deprecated
public Serializer doubleNumber();
/**
* @see #variableInteger()
*/
@Deprecated
public Serializer varint();
/**
* @see #variableLong()
*/
@Deprecated
public Serializer varlong();
/* more fancy things */
/**
* Build a {@code Serializer} that can serialize null values.
*/
public Serializer nullable(Serializer serializer);
/**
* Same as {@link #prefix(byte[], Serializer)}, but using a 32 bit integer as a prefix.
*/
public Serializer prefix(int prefix, Serializer serializer);
/**
* Build a {@code Serializer} that adds the specified prefix when serializing.
*
* If this prefix is missing when reading, a runtime exception will be thrown.
*
* @param prefix The prefix to use.
* @param serializer The {@code Serializer} to prefix.
* @return A new {@code Serializer} with the prefix operation.
*/
public Serializer prefix(byte[] prefix, Serializer serializer);
/**
* Create a length-prefixed serialized that buffers up data, and guarantees that the underlying
* child-serializer gets the specified amount.
*
* @param serializer The {@code Serializer} to length prefix.
* @param policy A policy governing how long a child message is allowed to be.
* @return A new {@code Serializer} with the length prefix operation.
*/
public Serializer lengthPrefixed(Serializer serializer, LengthPolicy policy);
/**
* This will use a the default length policy that is configured in the framework.
*
* @see #lengthPrefixed(Serializer, LengthPolicy)
*/
public Serializer lengthPrefixed(Serializer serializer);
/**
* Build a {@code Serializer} that can serialize a list.
*
* How the list is encoded is implementation specific.
*
* @param Type of the list items.
* @param serializer The {@code Serializer} to use for each list item.
* @return A new list {@code Serializer}.
*/
public Serializer> list(Serializer serializer);
/**
* Build a {@code Serializer} that can serialize a map.
*
* How the map is encoded is implementation specific.
*
* @param Type of map keys.
* @param Type of map values.
* @param key The {@code Serializer} to use for map keys.
* @param value The {@code Serializer} to use for map values.
* @return A new map {@code Serializer}.
*/
public Serializer> map(Serializer key, Serializer value);
/**
* Build a {@code Serializer} that can serialize a sorted map.
*
* How the map is encoded is implementation specific.
*
* @param Type of map keys.
* @param Type of map values.
* @param key The {@code Serializer} to use for map keys.
* @param value The {@code Serializer} to use for map values.
* @return A new map {@code Serializer}.
*/
public , V> Serializer> sortedMap(
Serializer key, Serializer value
);
public , V> Serializer> navigableMap(
Serializer key, Serializer value
);
/**
* Build a {@code Serializer} that can serialize a set.
*
* How the ser is encoded is implementation specific.
*
* @param Type of the set items.
* @param serializer The {@code Serializer} to use for each set item.
* @return A new set {@code Serializer}.
*/
public Serializer> set(Serializer serializer);
/**
* Build a {@code Serializer} that can serialize a sorted set.
*
* How the ser is encoded is implementation specific.
*
* @param Type of the set items.
* @param serializer The {@code Serializer} to use for each set item.
* @return A new set {@code Serializer}.
*/
public > Serializer> sortedSet(Serializer serializer);
public > Serializer> navigableSet(
Serializer serializer
);
/**
* Create a new serializer for the given array.
*
* @param element The element serializer to use.
* @param constructor The array constructor to use.
* @return A new array serializer.
*/
public Serializer array(Serializer element, ArrayConstructor constructor);
public Serializer booleanArray();
public Serializer shortArray();
public Serializer intArray();
public Serializer longArray();
public Serializer floatArray();
public Serializer doubleArray();
/**
* A {@code Serializer} that can serialize a byte array.
*/
public Serializer byteArray();
/**
* A {@code Serializer} that can serialize a char array.
*/
public Serializer charArray();
/**
* A {@code Serializer} that can serializer {@link UUID}s.
*/
public Serializer uuid();
/**
* A {@code Serializer} that can serializer {@link BitSet}s.
*/
public Serializer bitSet();
/**
* Build a serializer for an optional type.
*
* @param element The element serializer to use.
* @return A serializer for the specified optional type.
*/
public Serializer> optional(Serializer element);
/**
* Same as {@link #forEnum(Object[], Object)}, but throws an exception when out-of-range.
*
* @see #forEnum(Object[], Object)
*/
public > Serializer forEnum(final T[] values);
/**
* A serializer that can serialize enums.
*
* Example usage:
*
*
* {@code
* // setup a serializer framework
* SerializerFramework s = null;
* Serializer myEnumSerializer = s.forEnum(MyEnum.values());
* }
*
*
* @param values Enum values.
* @param defaultValue Default value to use when enum deserialized value is out-of-range.
* @return A serializer for enum values.
*/
public > Serializer forEnum(T[] values, T defaultValue);
/**
* A {@code Serializer} that throws a runtime exception with the message "not implemented".
*/
public Serializer notImplemented();
/**
* A type mapping, that maps a specific type {@code Class}, to a {@code Serializer}, and an
* ordinal id.
*
* @param Super type to create mapping for.
* @param Subtype of the super type .
* @param id The id of the mapped type.
* @param key The type of the mapped type.
* @param serializer The serializer for the mapped type.
* @return A new typemapping.
*/
public TypeMapping type(int id, Class type, Serializer serializer);
/**
* Create a {@code Serializer} for the given type mappings.
*
* @param The super type that is to be serialized to and from.
* @param mappings Type mappings.
* @return A new serializer for the given type mappings.
*/
public Serializer subtypes(Iterable> mappings);
/**
* Create a singleton serializer that always deserializes to the same reference.
*
* @param value Reference to serialize.
* @return The singleton reference.
*/
public Serializer singleton(T value);
/**
* Serialize a value.
*
* It is not recommended that you use this method when integrating this framework. For that,
* implement a custom {@code SerialWriter} that fits your needs to the letter instead.
*
* @param serializer The {@code Serializer} to use.
* @param value The value to serialize.
* @return A ByteBuffer containing the serialized value.
* @throws IOException If serialization fails.
*/
public ByteBuffer serialize(Serializer serializer, T value) throws IOException;
/**
* Deserialize a buffer.
*
* It is not recommended that you use this method when integrating this framework. For that,
* implement a custom {@code SerialReader} that fits your needs to the letter instead.
*
* @param serializer The {@code Serializer} to use.
* @param buffer The buffer to deserialize.
* @return The given value.
* @throws IOException If serialization fails.
*/
public T deserialize(Serializer serializer, ByteBuffer buffer) throws IOException;
/**
* Write directly to the provided byte buffer.
*
* @param buffer Byte buffer to write to.
* @return A new {@link SerialWriter} writing to the provided {@link ByteBuffer}.
*/
public SerialWriter writeByteBuffer(ByteBuffer buffer);
/**
* Read directly from the given ByteBuffer.
*
* @param buffer Buffer to read from.
* @return A new {@link SerialReader} reading directly from the given ByteBuffer.
*/
public SerialReader readByteBuffer(ByteBuffer buffer);
public SerialWriter writeByteChannel(WritableByteChannel channel);
public SerialReader readByteChannel(ReadableByteChannel channel);
/**
* Write to a growing byte array buffer.
*
* @return A new {@link SerialWriter} capable of growing as its being written to.
*/
public BytesSerialWriter writeBytes();
/**
* Read directly from the given byte array.
*
* @param bytes Byte array to read from.
* @return A new {@link SerialReader} reading from the given byte array.
*/
public SerialReader readByteArray(byte[] bytes);
/**
* Write to the given {@link OutputStream}.
*
* This returns a special writer implementation {@link StreamSerialWriter} which provides
* flushing capabilities. It is important to flush the underlying stream when you wish for any
* previously serialized objects to be written. Flushing is implied when closing the stream.
*
* @param output The output stream to write to.
* @return A new {@link SerialWriter} connected to the given {@link OutputStream}.
*/
public StreamSerialWriter writeStream(OutputStream output);
/**
* Read from the given {@link InputStream}.
*
* Reading from input streams are very likely to block.
*
* @param input The input stream to read from.
* @return A new {@link SerialReader} connected to the given {@link InputStream}.
*/
public SerialReader readStream(InputStream input);
/**
* Maps a specific ordinal id to a type (key), and a serializer for that type.
*
* @param The mapped type.
*/
public static class TypeMapping {
final int id;
final Class key;
final Serializer serializer;
public TypeMapping(int id, Class key, Serializer serializer) {
this.id = id;
this.key = key;
this.serializer = serializer;
}
public int id() {
return id;
}
public Class key() {
return key;
}
public Serializer serializer() {
return serializer;
}
}
}