Terms & Definitions

Below is a list of core terms used in libs11n. The bolded words within the definitions highlight other important terms defined in this list, or denote particularly significant data types. This bolding is intended to help reinforce understanding of the relationships between the various elements of the s11n library.

• Data Node - a generic term for map-like types which store arbitrary key/value properties and child nodes, plus some meta-data (like type information for the stored data, if needed). They are structured in a tree-like fashion, DOM-style. In s11nlite this role is played by the s11n::data_node type, though core s11n supports any types which conform to the conventions laid out by that type. (The core doesn't actually know that type exists.)
• serializable (with a small ''s'')- the property of being able to be save and restore state, e.g., to allow persistent object states across application sessions, network connections, etc.
• Serializable Type or Serializable (with a big ''S'') - any type for which s11n recognizes a Serializable Interface, either implemented directly by a Serializable type or via a Serialization Proxy. Serializables store their data in Data Nodes during serialization and load their data from data nodes during deserialization.
• Serializable Proxy or Serialization Proxy - a functor (possibly two) which registers with s11n as being the handler for de/serialization of a given type. By extension, the proxied type is said to be Serializable. All de/serialize operations s11n performs on behalf of that type are delegated to the proxy type. This allows, amongst other things, transparent serialization of 3rd-party classes and class templates.
  Proxies are not technically Serializables - they are, more properly, the implementation for a Serializable's serialization operators. (Got that?)
• serialization, to serialize - several meanings:
  • To save the state of a Serializable into a Data Node.
  • To save a Data Node to a data stream. This emits it to a Serializer-specific grammar.
  • Several other subtle, context-specific meanings.
• deserialization, to deserialize - the converse of serialize:
  • To restore the state of a Serializable, presumably using data from a Data Node.
  • To load a Data Node from an input stream.
• de/serialization or de/serialize - shorthand forms of ''deserialization and serialization'' and ''deserialize and serialize.''
• Serializer - a type responsible for converting data nodes to and from a specific grammar. For example, some Serializers use a XML dialect, while others use custom formats. Theoretically, any data which can be structured in a DOM-like fashion (even if only via logical transformation) can be handled by Serializers. In s11n Serializers are also always Deserializers (at least logically, in terms of the interface), with the one minor exception that Serializable Proxies may be implemented in terms of two separate functors.
• serialization operators, de/serialize(), or Serializable Interface - a generic name for the pair of de/serialize functions which Serializables and Serializable Proxies have, regardless of the actual names or argument types of the functions. Sometimes also used to refer to the de/serialize functions within other interfaces, such as the s11n core.
• de/serialization operations - a generic term encompassing functions which trigger a chain of events which lead through the s11n de/serialization core (and, presumably, back). In plain English: s11n::de/serialize<>(), and related functions, fall into this category.
• Default Serializable Interface - Serializables which implement both of their serialization operators as operator() are said to follow the Default Serializable Interface. Types which do this do not need to tell s11n what their serialization interface looks like - it will pick them up automatically.
• Load/Save vs De/Serialize - By s11n convention, the words "save" and "load" are used when dealing with streams or files, and "serialize" and "deserialize" are used when dealing with saving or restoring the state of a Serializable to or from a Data Node. Sometimes the words are used interchangeably and, while it is technically correct in many cases, such usage is considered ''marginally ambiguous'' in s11n.
• Classloader - an object used to search for classes based on a lookup key. In s11n this lookup key is conventionally the string form of a class' name. Classloaders are used during deserialization to load the proper type for a given node (this is necessary in order to support polymorphic deserialization). The s11n classloader has support for loading classes from DLLs, but that feature is not covered much in these docs. Classloaders work primarily not off of specific ''concrete'' types, but off of Base Types, as described briefly below. See http://s11n.net/class_loader/ for more detail than you probably want to know about these.
• T's classloader, or the T classloader - Refers the the classloader which uses type T as it's point of reference for registering and loading classes. More specifically, it means cl::class_loader<T>, a classloader which supports loading T types. Subtypes of T should be registered with T's classloader, regardless of whether or not they also register with their own classloader (e.g., class_loader<SomeTSubType>).
• Base Type - in s11n, especially in the context of a classloader, this is used to mean the base-most type which a given classloader ''knows about.'' This type is used for registering subtypes of Base Types with the Base Type's Serializable Interface, and is critical for classloading purposes. It is covered in massive detail in the classloader's library manual. In a broader sense, Base Types are used as contexts for marshaling the s11n and client-side Serializable Interfaces into internally-compatible forms. Base Types are often used as contexts, in the form of template parameters for functions and classes for which this Base Type distinction is significant (e.g., those dealing with de/serialization and classloading).
• Streamable [types] - In the context of s11n this means any type for which istream>> and ostream<< operators can be applied to successfully save/restore the state of an object of that type. This inherently includes all PODs, std::string, and any client-supplied types which meet these conditions. This also implicitely excludes all pointer types. Note that Serializables are not implicitely Streamable, as s11n does not actually deal with streams at it's core.

Using the library is not as complex as the above list may imply, as the rest of this documentation will attempt to convince you. Yes, the details of serialization and classloading, especially in a lower-level language like C++, are downright scary. s11n tries to move the client as far away as possible from those scary details, and it goes to great pains to do so. However, some understanding of the above terms, and their inter-relationships, is critical to making full use of s11n.

For those interested in reading more about serialization in C++, including some if it's pitfalls, i highly recommend Marshall Kline's FAQ on the topic.