1 /****************************************************************************** 2 3 Terminology 4 ----------- 5 6 *serializer* : collection of algorithms responsible for representing data 7 structure in domain-specific format. Serializers are not supposed to deal with 8 any kind of metadata, just raw data representation. 9 10 *deserializer* : collection of algorithms responsible for converting serialized 11 data to a D data structure. Similar to serializer, it is not supposed to deal 12 with metadata. 13 14 *decorator* : collection of algorithms that work on top of already defined 15 (de)serializer and augment stored data in some way. It can be adding version 16 information or gzip compressing of serialized data, any kind of higher 17 level post-processing. 18 19 Package Structure 20 ----------------- 21 22 ``ocean.util.serialize.model.*`` 23 collection of generic parts of serializer/decorator implementations 24 25 ``ocean.util.serialize.pkgname.Serializer`` 26 ``ocean.util.serialize.pkgname.Deserializer`` 27 ``ocean.util.serialize.pkgname.*Decorator`` 28 actual modules to be used by applications. ``pkgname`` here represents 29 specific serialization format, one sub-package for each new format. There can 30 be more modules exposed to applications depending on specific format but 31 those are minimal ones you should expect. Decorator implementation count may 32 vary from 0 to many depending on actual needs. 33 34 ``ocean.util.serialize.pgkname.model.*`` 35 any internal modules used to implement ``pkgname`` serializer / decorators 36 37 Usage 38 ----- 39 40 Refer to documentation of any specific sub-package for further usage details. 41 42 Contribution 43 ------------ 44 45 If you are going to implement and new serialization format, more detailed 46 knowledge of this package internal is needed. Most important module to become 47 familiar with is ``ocean.util.model.Traits`` - it defines set of ``isSomething`` 48 templates that help to ensure that given serializer / decorators conforms the 49 standard API. ``ocean.util.serialize`` uses duck typing approach so there does 50 not need to be any common base. In fact, serializers are commonly implemented 51 as static structs. 52 53 New format package must have at minimum ``Serializer`` and ``Deserilaizer`` 54 modules. Put ``static assert (isSerializer!(This));`` and 55 ``static assert (isDeserializer!(This))`` at the beginning of actual aggregate 56 definition to ensure that API is conformant. However you may want to disable 57 that asssertion during initial development stage because DMD1 tends to hide 58 any compiler error messages showing assertion failure instead. 59 60 ``Decorator`` implementation is allowed to be non-static (so that it can keep 61 any intermediate data buffers). As decorator methods are typically templated, 62 one can't use abstract class / override approach for common parts. Technique 63 used in existing ``VersionDecorator`` is to define set of template mixins that 64 implement common methods and inject those directly to implementation classes. 65 66 Copyright: 67 Copyright (c) 2009-2016 dunnhumby Germany GmbH. 68 All rights reserved. 69 70 License: 71 Boost Software License Version 1.0. See LICENSE_BOOST.txt for details. 72 Alternatively, this file may be distributed under the terms of the Tango 73 3-Clause BSD License (see LICENSE_BSD.txt for details). 74 75 ******************************************************************************/ 76 77 module ocean.util.serialize; 78 79 public import ocean.util.serialize.contiguous;