X-Git-Url: http://git.nikiroo.be/?a=blobdiff_plain;ds=sidebyside;f=src%2Fbe%2Fnikiroo%2Futils%2Fserial%2FCustomSerializer.java;h=e58ccf2af5945eab2ba4b508bd9d04c9213c56f1;hb=505be508ae7d3fb48122be548b310a238cfb91eb;hp=e5539c0fdce8669592a932c819d458b0717c1613;hpb=08f80ac5fa60738d3ad74c4b5390a0b79ae313d4;p=nikiroo-utils.git diff --git a/src/be/nikiroo/utils/serial/CustomSerializer.java b/src/be/nikiroo/utils/serial/CustomSerializer.java index e5539c0..e58ccf2 100644 --- a/src/be/nikiroo/utils/serial/CustomSerializer.java +++ b/src/be/nikiroo/utils/serial/CustomSerializer.java @@ -4,23 +4,83 @@ import java.io.IOException; import java.io.InputStream; import java.io.OutputStream; -import be.nikiroo.utils.IOUtils; -import be.nikiroo.utils.streams.NextableInputStream; -import be.nikiroo.utils.streams.NextableInputStreamStep; +import be.nikiroo.utils.streams.BufferedInputStream; import be.nikiroo.utils.streams.ReplaceInputStream; import be.nikiroo.utils.streams.ReplaceOutputStream; +/** + * A {@link CustomSerializer} supports and generates values in the form: + *
+ * In this scheme, the values are: + *
+ * To create a new {@link CustomSerializer}, you are expected to implement the + * abstract methods of this class. The rest should be taken care of bythe + * system. + * + * @author niki + */ public abstract class CustomSerializer { - + /** + * Generate the custom ENCODED_VALUE from this + * value. + *
+ * The value will always be of the supported type. + * + * @param out + * the {@link OutputStream} to write the value to + * @param value + * the value to serialize + * + * @throws IOException + * in case of I/O error + */ protected abstract void toStream(OutputStream out, Object value) throws IOException; + /** + * Regenerate the value from the custom ENCODED_VALUE. + *
+ * The value in the {@link InputStream} in will always be of the + * supported type. + * + * @param in + * the {@link InputStream} containing the + * ENCODED_VALUE + * + * @return the regenerated object + * + * @throws IOException + * in case of I/O error + */ protected abstract Object fromStream(InputStream in) throws IOException; + /** + * Return the supported type name. + *
+ * It must be the name returned by {@link Object#getClass() + * #getCanonicalName()}. + * + * @return the supported class name + */ protected abstract String getType(); /** - * Encode the object into the given {@link OutputStream} if supported. + * Encode the object into the given {@link OutputStream}, i.e., generate the + * ENCODED_VALUE part. + *
+ * Use whatever scheme you wish, the system shall ensure that the content is + * correctly encoded and that you will receive the same content at decode + * time. * * @param out * the builder to append to @@ -45,58 +105,39 @@ public abstract class CustomSerializer { } } + /** + * Decode the value back into the supported object type. + *
+ * We do not expect the full content here but only: + *