Overview
Odn
Odin

Getting started

Introduction

To start using the library, there is one class to know: Odin. This class manages every input, output and types.


You can simply declare a new instance without any constructor parameters

Odin odin = new Odin();

After that, you can choose between indented or compressed output. By default, the output is compressed.

Odin odin = new Odin().indentOutput();
Odin odin = new Odin().compressOutput();

You can also change the reader buffer size, the default buffer size being 4096.


The minimum buffer size that can be set is 64 but the recommended values are 1024, 2048 or 4096.

Odin odin = new Odin().setReaderBufferSize(2048);

One line serialization

If you simply need to transform an object into a String or vice versa, you can use the direct serialization and deserialization methods.

You have two ways of serializing objects. The first one only takes your object and uses a UnknownType, so if your object is not a primitive the type definitions are added before the object.

String s = odin.toOdn(objectToSerialize);

The second method requires an additional generic type to avoid type definition. If your object has the same class as your given type, no type definition is added.


You need to pass the same generic type when you call the deserialization process to make Odin use the right type.

String s = odin.toOdn(objectToSerialize, Foo.class);

One line deserialization

Follow the same logic to deserialize a String representing an Odn object. Simply give the String to Odin

Foo result = odin.fromOdn(source);

You can also add a generic type. If type definition is still there, odin uses it instead of your type, considering type definition is a subclass of your given type.

Foo result = odin.fromOdn(source, Foo.class);

Open Writer

Odin class allows to write to several types of destinations. Each type uses a method that returns a new OdinWriter instance:

  • Writer


    Writer is the default Odin output type that allows to write to any kind of output.

    try (OdinWriter writer = odin.writer(new FileWriter(new File("destination")))) {
        // write objects
    } catch (IOException e) {
        // manage exception
    }

  • OutputStream


    Odin can open a OdinWriter using a OutputStream. It will convert it to Writer and use UTF-8 to encode characters.

    try (OdinWriter writer = odin.writer(aSocket.getOutputStream())) {
        // write objects
    } catch (IOException e) {
        // manage exception
    }

  • File


    You can also use a File, this method creates a new FileOutputStream and can throw a FileNotFoundException if the file does not exist and cannot be created. 

    try (OdinWriter writer = odin.writer(new File("destination"))) {
        // write objects
    } catch (IOException e) {
        // manage exception
    }

  • Path


    The NIO2 alternative for File: this method creates a new OutputStream with the path and uses WRITE and CREATE options to open the stream. 

    try (OdinWriter writer = odin.writer(Paths.get("destination"))) {
        // write objects
    } catch (IOException e) {
        // manage exception
    }

Reader

The Odin reader can be obtained the same way as the writer, so there are 4 input types:

  • Reader


    Reader is the default Odin input type that allows to read from any kind of input.

    try (OdinReader reader = odin.reader(new FileReader(new File("source")))) {
        // read objects
    } catch (IOException e) {
        // manage exception
    }

  • InputStream


    Odin can open an OdinReader using a InputStream, it will convert it to Reader with the UTF-8 charset
    If the default charset of your JDK is defined to UTF-8, you can directly use a Reader to avoid useless InputStream instanciations, else you can use this InputStream to let odin force the UTF-8 to Reader. 

    try (OdinReader reader = odin.reader(aSocket.getInputStream())) {
        // read objects
    } catch (IOException e) {
        // manage exception
    }

  • File


    you can use File to let Odin create InputStream and Reader for you, this method creates a new FileInputStream and can throw a FileNotFoundException if the file does not exist and cannot be created.

    try (OdinReader reader = odin.reader(new File("source"))) {
        // read objects
    } catch (IOException e) {
        // manage exception
    }

  • Path


    About the NIO2 alternative for File: it's the same as File. This method creates a new InputStream with the path and uses READ options for stream opening.

    try (OdinReader reader = odin.reader(Paths.get("source"))) {
        // read objects
    } catch (IOException e) {
        // manage exception
    }
Previous: Odn Format Next: Handle Objects