s11n.hpp

Go to the documentation of this file.
00001 #ifndef s11n_S11N_H_INCLUDED
00002 #define s11n_S11N_H_INCLUDED 1
00003 
00004 ////////////////////////////////////////////////////////////////////////
00005 // s11n.hpp:
00006 // Author: stephan beal <stephan@s11n.net>
00007 // License: Public Domain
00008 //
00009 // This header includes "everything most clients would want" regarding
00010 // the core s11n library. It does not include any i/o- or s11nlite-
00011 // related headers.
00012 //
00013 // The s11n namespace docs go here so doxygen will pick them up nicely.
00014 ////////////////////////////////////////////////////////////////////////
00015 
00016 #include <string>
00017 
00018 /**
00019    The s11n serialization (s11n) framework is an object serialization
00020    framework for C++ modelled heavily off work by Rusty Ballinger
00021    (bozo@users.sourceforge.net http://libfunutil.sourceforge.net). 
00022    It provides a framework off of which a wide variety of C++ objects
00023    can be serialized and deserialized (saved and loaded) with a
00024    trivial amount of effort.
00025 
00026    As far as i know Rusty was the one to coin the phrase "s11n" (short
00027    for "serialization", in the same way that i18n is short for
00028    "internationalization").
00029 
00030    In addition to the API documentation, please see the library
00031    manual, available in the source tree, in the docs subdir.
00032    It is also available for download on our web site in other
00033    formats (i.e., not LyX).
00034 
00035    The most important concepts for clients to understand:
00036 
00037    - Data Node (a.k.a. S11n Node or SNode), as described in the
00038    library manual and demonstrated by the reference implementation,
00039    s11n::s11n_node.
00040 
00041    - the serialize() and deserialize() family of free functions.
00042 
00043    - Serializable type registration, as covered in the library manual.
00044 
00045    See the source tree, under <tt>src/client/sample</tt>, for
00046    many examples of client code.
00047 */
00048 namespace s11n
00049 {
00050 
00051         /**
00052            Returns the string form of the s11n library version.
00053         */
00054         std::string library_version();
00055 
00056         /**
00057            The Private namespace holds internal library types: these
00058            should not be used in client code.
00059         */
00060         namespace Private
00061         {
00062         /**
00063            Internal, not for client use. Adds a symbol which
00064            is checked by s11nconvert, so that s11nconvert will
00065            not link against an s11n 1.0 library. The problem
00066            is that the 1.1 s11nconvert can build using the 1.1
00067            s11n headers and link to the 1.0 lib, resulting in
00068            segfaults at runtime instead of a link error. This
00069            symbol is only to work around that, and it does not
00070            perform any operations. It won't necessarily
00071            trigger a link error until s11nconvert is actually
00072            run, in which case dynamic linking will fail (as
00073            expected).
00074 
00075            e.g., the following binary is inadvertently linked
00076            to the 1.0 lib:
00077 
00078 <pre>
00079 stephan@owl:~/cvs/s11n.net/1.1/s11n/src/client/s11nconvert> ldd s11nconvert
00080 ...
00081         libs11n.so.1 => /home/stephan/lib/libs11n.so.1 (0x40019000)
00082 ...
00083         libs11n_zfstream.so.2004 => /home/stephan/lib/libs11n_zfstream.so.2004 (0x4026e000)
00084         libs11n_stringutil.so.2004 => /home/stephan/lib/libs11n_stringutil.so.2004 (0x40279000)
00085         libs11n_class_loader.so.2005 => /home/stephan/lib/libs11n_class_loader.so.2005 (0x40281000)
00086 ...
00087         libs11n_acme.so.2005 => /home/stephan/lib/libs11n_acme.so.2005 (0x402b5000)
00088 ...
00089 </pre>
00090 
00091         So we force it fail at link-time by simply linking against a symbol we know isn't
00092     in the 1.0 library:
00093 
00094 <pre>
00095 stephan@owl:~/cvs/s11n.net/1.1/s11n/src/client/s11nconvert> ./s11nconvert
00096 ./s11nconvert: symbol lookup error: ./s11nconvert: undefined symbol: _ZN4s11n7Private18s11n_1_1_assertionEv
00097 </pre>
00098 
00099         In any case, this is a lame kludge and will go away someday.
00100 
00101          */
00102         void s11n_1_1_assertion();
00103 
00104         }
00105 
00106         /**
00107            The s11n::io namespace defines some i/o-related types which
00108            conform to the conventions expected by the
00109            <code>s11n::de/serialize()</code> core functions. This
00110            namespace deals with the de/serialization of Data Nodes at
00111            the stream/file level, leaving the s11n core to only deal
00112            with de/serialization of containers.
00113 
00114            Clients can swap out these types and still use the core
00115            s11n interface. The core has no dependencies on this
00116            namespace. s11nlite combines the s11n core and i/o
00117            interfaces into a single, easy-to-use API, and users who
00118            don't <em>need</em> to directly act with the Serializers
00119            are strongly encouraged to stick to using s11nlite for
00120            their save/load needs.
00121 
00122            s11n's default Serializer implementations all live
00123            in the s11n::io namespace, and are derived from
00124            <code>serializer<NodeT></code>. Clients
00125            who subclass this type and follow the conventions
00126            laid out by the reference implementations can plug
00127            their own Serializers into the framework with very
00128            little effort. For an example of a plug-in Serializer
00129            see the <a href="http://s11n.net/mysql/">mysql_serializer</a>.
00130         */
00131         namespace io {
00132         }
00133 
00134 
00135     /**
00136        The Detail namespace holds types which aren't strictly
00137        internal/private, but are nonetheless considered to be
00138        "implementation details." Unless specifically documented
00139        otherwise, clients are discouraged from using the
00140        Detail-namespace API from client code, as any part of it
00141        may change significantly or be replaced/removed without any
00142        warning.
00143 
00144        Clients wishing to use Detail-namespace code are instead
00145        encouraged to make their own copy, rename the namespace,
00146        and tweak to suit.
00147 
00148        The main difference between the Private and Detail
00149        namespaces is... well, vague. As a "general guideline",
00150        most Private code is specific to one certain area of this
00151        library, where as Detail code might have utility in
00152        throughout the library, or even play a fundamental role in
00153        the implementation. An example of a Detail is the phoenix<>
00154        class: it plays no direct part in serialization proper, and
00155        thus was moved out of the top-level s11n namespace, but is
00156        used throughout the framework to provide shared object
00157        instances for many purposes.
00158     */
00159     namespace Detail {
00160     }
00161 
00162 }
00163 
00164 #include <s11n.net/s11n/s11n_config.hpp> // configure/build-time config vars
00165 #include <s11n.net/s11n/classload.hpp> // classloader API
00166 #include <s11n.net/s11n/traits.hpp> // node_traits and s11n_traits
00167 #include <s11n.net/s11n/exception.hpp> // exception types
00168 #include <s11n.net/s11n/serialize.hpp> // serialize() and friends
00169 #include <s11n.net/s11n/algo.hpp> // generic algos used by the framework
00170 #include <s11n.net/s11n/s11n_node.hpp> // Reference Data Node implementation
00171 #include <s11n.net/s11n/tags.hpp> // de/serialize operator tags
00172 
00173 #endif // s11n_S11N_H_INCLUDED

Generated on Wed Jun 4 21:42:00 2008 for libs11n-1.2.7 by  doxygen 1.5.3