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 00172 #endif // s11n_S11N_H_INCLUDED