1 package org.djutils.serialization;
2
3 /**
4 * Interface to serialize and deserialize data.
5 * <p>
6 * Copyright (c) 2019-2019 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved. <br>
7 * BSD-style license. See <a href="http://opentrafficsim.org/docs/license.html">OpenTrafficSim License</a>.
8 * <p>
9 * $LastChangedDate: 2019-06-07 01:33:02 +0200 (Mon, 7 Jun 2019) $, @version $Revision: 1401 $, by $Author: pknoppers $, initial
10 * version Jun 07, 2019 <br>
11 * @author <a href="http://www.tbm.tudelft.nl/averbraeck">Alexander Verbraeck</a>
12 * @author <a href="http://www.tudelft.nl/pknoppers">Peter Knoppers</a>
13 * @param <T> Type of object that can be serialized and deserialized
14 */
15 public interface Serializer<T extends Object>
16 {
17 /**
18 * Compute the number of bytes needed to serialize an object of type T (excluding the byte(s) that indicate that an object
19 * of type T is next in the data stream).
20 * @param object Object; Instance of the object (should be of type T)
21 * @return int; the number of bytes needed to serialize an object of type T
22 * @throws SerializationException when the <code>object</code> cannot be serialized
23 */
24 int size(T object) throws SerializationException;
25
26 /**
27 * Compute the number of bytes needed to serialize an object of type T (including the byte(s) that indicate that an object
28 * of type T is next in the data stream).
29 * @param object Instance of the object (should be instance of T)
30 * @return int; the number of bytes needed to serialize an object of type T
31 * @throws SerializationException when the <code>object</code> cannot be serialized
32 */
33 int sizeWithPrefix(T object) throws SerializationException;
34
35 /**
36 * Return the byte representation of the field type.
37 * @return byte
38 */
39 byte fieldType();
40
41 /**
42 * Serialize an object of type T; not including the prefix byte(s).
43 * @param object Object; the object to serialize (should be of type T)
44 * @param buffer byte[]; buffer for the serialized T
45 * @param pointer Pointer; position in buffer where the first byte of the serialized T will be stored
46 * @param endianUtil EndianUtil; selects bigEndian or littleEndian encoding
47 * @throws SerializationException when a matrix has size zero or is jagged
48 */
49 void serialize(T object, byte[] buffer, Pointer pointer, EndianUtil endianUtil) throws SerializationException;
50
51 /**
52 * Serialize an object of type T including the prefix byte(s).
53 * @param object Object; the object to serialize (should be of type T)
54 * @param buffer byte[]; buffer for the serialized T
55 * @param pointer Pointer; position in buffer where the first byte of the serialized T will be stored
56 * @param endianUtil EndianUtil; selects bigEndian or littleEndian encoding
57 * @throws SerializationException when a matrix has size zero or is jagged
58 */
59 void serializeWithPrefix(T object, byte[] buffer, Pointer pointer, EndianUtil endianUtil)
60 throws SerializationException;
61
62 /**
63 * Deserialize an object of type T. The <code>pointer</code> should be on the first byte of the object; i.e. just after the
64 * prefix byte.
65 * @param buffer byte[]; the bytes with serialized data that must be reconstructed into a T
66 * @param pointer Pointer; position in the buffer where the first byte of the serialized T is located
67 * @return T; a T object constructed from the data in the buffer
68 * @param endianUtil EndianUtil; selects bigEndian or littleEndian encoding
69 * @throws SerializationException when the input data cannot be deserialized
70 */
71 T deSerialize(byte[] buffer, Pointer pointer, EndianUtil endianUtil) throws SerializationException;
72
73 /**
74 * Return a description of the type of data that this serializer handles.
75 * @return String; description of the type of data that this serializer handles
76 */
77 String dataClassName();
78
79 /**
80 * Return the number of dimensions of the stored data.
81 * @return int; 0 for plain data, 1 for array, 2 for matrix
82 */
83 int getNumberOfDimensions();
84
85 }