Line data Source code
1 : /* Copyright (c) 2016-2017, Human Brain Project
2 : * Stefan.Eilemann@epfl.ch
3 : *
4 : * This file is part of Servus <https://github.com/HBPVIS/Servus>
5 : *
6 : * This library is free software; you can redistribute it and/or modify it under
7 : * the terms of the GNU Lesser General Public License version 3.0 as published
8 : * by the Free Software Foundation.
9 : *
10 : * This library is distributed in the hope that it will be useful, but WITHOUT
11 : * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
12 : * FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
13 : * details.
14 : *
15 : * You should have received a copy of the GNU Lesser General Public License
16 : * along with this library; if not, write to the Free Software Foundation, Inc.,
17 : * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
18 : */
19 :
20 : #ifndef SERVUS_SERIALIZABLE_H
21 : #define SERVUS_SERIALIZABLE_H
22 :
23 : #include <servus/api.h>
24 : #include <servus/types.h>
25 :
26 : #include <functional> // function
27 : #include <memory> // shared_ptr
28 :
29 : namespace servus
30 : {
31 : /** Interface for serializable objects */
32 : class Serializable
33 : {
34 : public:
35 : SERVUS_API Serializable();
36 : SERVUS_API virtual ~Serializable();
37 :
38 : /** @name Serialization methods */
39 : //@{
40 : /** Pointer + size wrapper for binary serialization. */
41 0 : struct Data
42 : {
43 0 : Data()
44 0 : : size(0)
45 : {
46 0 : }
47 :
48 : /** @return a deep copy of Data. */
49 : SERVUS_API Data clone();
50 :
51 : std::shared_ptr<const void> ptr; //!< ptr to the binary serialization
52 : size_t size; //!< The size of the binary serialization
53 : };
54 :
55 : /** @return the fully qualified, demangled class name. */
56 : virtual std::string getTypeName() const = 0;
57 :
58 : /** @return the universally unique identifier of this serializable. */
59 : SERVUS_API virtual uint128_t getTypeIdentifier() const;
60 :
61 : /** @return the description of the objects' data layout. */
62 1 : virtual std::string getSchema() const { return std::string(); }
63 : /**
64 : * Update this serializable from its binary representation.
65 : * @return true on success, false on error.
66 : */
67 : SERVUS_API bool fromBinary(const Data& data);
68 : SERVUS_API bool fromBinary(const void* data, const size_t size);
69 :
70 : /**
71 : * Get a binary representation of this object.
72 : *
73 : * The returned data is not thread safe, that is, it should not be modified
74 : * until the caller of this method has completed its execution.
75 : *
76 : * @return the binary representation of this object.
77 : */
78 : SERVUS_API Data toBinary() const;
79 :
80 : /**
81 : * Update this serializable from its JSON representation.
82 : * @return true on success, false on error.
83 : */
84 : SERVUS_API bool fromJSON(const std::string& json);
85 :
86 : /** @return the JSON representation of this serializable. */
87 : SERVUS_API std::string toJSON() const;
88 : //@}
89 :
90 : /** @name Change Notifications */
91 : //@{
92 : /** Callbacks for change notifications. */
93 : typedef std::function<void()> DeserializedCallback;
94 : typedef std::function<void()> SerializeCallback;
95 :
96 : /**
97 : * Register a function called after the object has been updated remotely
98 : * (via a subscriber, a http server, loading from file...).
99 : * Only one callback is supported at the moment, to deregister the callback,
100 : * call this function with a 'nullptr' (or 0) parameter.
101 : *
102 : * @throw if a DeserializedCallback is already registered and the specified
103 : * callback is not 'nullptr' (or 0)
104 : */
105 : SERVUS_API void registerDeserializedCallback(const DeserializedCallback&);
106 :
107 : /**
108 : * Register a function to be called when the serializable object is about
109 : * to be serialized.
110 : * Only one callback is supported at the moment, to deregister the callback,
111 : * call this function with a 'nullptr' (or 0) parameter.
112 : *
113 : * @throw if a SerializedCallback is already registered and the specified
114 : * callback is not 'nullptr' (or 0)
115 : */
116 : SERVUS_API void registerSerializeCallback(const SerializeCallback&);
117 : //@}
118 :
119 : protected:
120 : SERVUS_API Serializable(const Serializable&);
121 : SERVUS_API Serializable& operator=(const Serializable&);
122 : SERVUS_API Serializable(Serializable&&);
123 : SERVUS_API Serializable& operator=(Serializable&&);
124 :
125 : private:
126 : /**
127 : * @name API for serializable sub classes.
128 : *
129 : * Endian-safe and 64-bit safe binary encoding is the responsability of the
130 : * subclass implementation, if needed.
131 : */
132 : //@{
133 0 : virtual bool _fromBinary(const void* /*data*/, const size_t /*size*/)
134 : {
135 0 : throw std::runtime_error("Binary deserialization not implemented");
136 : }
137 1 : virtual Data _toBinary() const
138 : {
139 1 : throw std::runtime_error("Binary serialization not implemented");
140 : }
141 :
142 0 : virtual bool _fromJSON(const std::string& /*json*/)
143 : {
144 0 : throw std::runtime_error("JSON deserialization not implemented");
145 : }
146 1 : virtual std::string _toJSON() const
147 : {
148 1 : throw std::runtime_error("JSON serialization not implemented");
149 : }
150 : //@}
151 :
152 : class Impl;
153 : Impl* _impl;
154 : };
155 : }
156 :
157 : #endif // SERVUS_SERIALIZABLE_H
|
