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