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="https://opentrafficsim.org/docs/license.html">OpenTrafficSim License</a>.
8 * <p>
9 * version Jun 07, 2019 <br>
10 * @author <a href="https://www.tudelft.nl/averbraeck">Alexander Verbraeck</a>
11 * @author <a href="https://www.tudelft.nl/staff/p.knoppers/">Peter Knoppers</a>
12 * @param <T> Type of object that can be serialized and deserialized
13 */
14 public interface Serializer<T extends Object>
15 {
16 /**
17 * Compute the number of bytes needed to serialize an object of type T (excluding the byte(s) that indicate that an object
18 * of type T is next in the data stream).
19 * @param object T; Instance of the object
20 * @return int; the number of bytes needed to serialize an object of type T
21 * @throws SerializationException when the <code>object</code> cannot be serialized
22 */
23 int size(T object) throws SerializationException;
24
25 /**
26 * Compute the number of bytes needed to serialize an object of type T (including the byte(s) that indicate that an object
27 * of type T is next in the data stream).
28 * @param object T; Instance of the object
29 * @return int; the number of bytes needed to serialize an object of type T
30 * @throws SerializationException when the <code>object</code> cannot be serialized
31 */
32 int sizeWithPrefix(T object) throws SerializationException;
33
34 /**
35 * Return the byte representation of the field type.
36 * @return byte
37 */
38 byte fieldType();
39
40 /**
41 * Serialize an object of type T; not including the prefix byte(s).
42 * @param object T; the object to serialize
43 * @param buffer byte[]; buffer for the serialized T
44 * @param pointer Pointer; position in buffer where the first byte of the serialized T will be stored
45 * @param endianUtil EndianUtil; selects bigEndian or littleEndian encoding
46 * @throws SerializationException when a matrix has size zero or is jagged
47 */
48 void serialize(T object, byte[] buffer, Pointer pointer, EndianUtil endianUtil) throws SerializationException;
49
50 /**
51 * Serialize an object of type T including the prefix byte(s).
52 * @param object T; the object to serialize
53 * @param buffer byte[]; buffer for the serialized T
54 * @param pointer Pointer; position in buffer where the first byte of the serialized T will be stored
55 * @param endianUtil EndianUtil; selects bigEndian or littleEndian encoding
56 * @throws SerializationException when a matrix has size zero or is jagged
57 */
58 void serializeWithPrefix(T object, byte[] buffer, Pointer pointer, EndianUtil endianUtil) throws SerializationException;
59
60 /**
61 * Deserialize an object of type T. The <code>pointer</code> should be on the first byte of the object; i.e. just after the
62 * prefix byte.
63 * @param buffer byte[]; the bytes with serialized data that must be reconstructed into a T
64 * @param pointer Pointer; position in the buffer where the first byte of the serialized T is located
65 * @return T; a T object constructed from the data in the buffer
66 * @param endianUtil EndianUtil; selects bigEndian or littleEndian encoding
67 * @throws SerializationException when the input data cannot be deserialized
68 */
69 T deSerialize(byte[] buffer, Pointer pointer, EndianUtil endianUtil) throws SerializationException;
70
71 /**
72 * Return a description of the type of data that this serializer handles. The result of this method should <b>not</b> be
73 * subject to localization because it is used in the SerialDataDecoder to identify the type of a serializer.
74 * @return String; description of the type of data that this serializer handles
75 */
76 String dataClassName();
77
78 /**
79 * Return the number of dimensions of the stored data.
80 * @return int; 0 for plain data, 1 for array, 2 for matrix
81 */
82 int getNumberOfDimensions();
83
84 }