listish.hpp

Go to the documentation of this file.
00001 ////////////////////////////////////////////////////////////////////////
00002 //
00003 ////////////////////////////////////////////////////////////////////////
00004 #ifndef s11n_net_s11n_v1_1_LIST_HPP_INCLUDED
00005 #define s11n_net_s11n_v1_1_LIST_HPP_INCLUDED 1
00006 
00007 
00008 namespace s11n {
00009 
00010 
00011     /**
00012            The s11n::list namespace defines functors and algorithms for
00013            working with std::list/vector-style containers.
00014         */
00015         namespace list {
00016 
00017                 /**
00018                    serialize_list() supports list/vector-like types containing
00019                    any Serializable type. Serializes (src.begin(),src.end()]
00020                    to dest. Each item has a node name of that given to the
00021                    ctor or an unspecified dummy value.
00022            
00023                    Returns true on success. If false is returned then dest is
00024                    in an undefined state: some number of serializations may
00025                    have succeeded before the failure. This operation stops
00026                    processing at the first serialization error.
00027 
00028            If serialization of a child fails, the child is not
00029            added to dest and any exception is propagated back
00030            to the caller.
00031 
00032                    Compatible ListTypes must support:
00033            
00034                    - a value_type typedef describing the type of it's contents.
00035 
00036                    - push_back( value_type )
00037 
00038                    - const_iterator typedefs.
00039 
00040                    Restrictions on value_type's type:
00041 
00042                    - Must be a Serializable. This includes any i/o streamable
00043                    type which has a proxy installed by s11n (includes all PODs
00044                    and std::string by default).
00045 
00046                    - May be a pointer type. NodeType must not be a pointer.
00047 
00048                    Some s11n-side requirements:
00049 
00050                    - ListType must be registered with the ListType classloader.
00051 
00052            If the underlying call to ::s11n::serialize()
00053            throws then the exception is propagated. If it
00054            throws, then dest is left in an undefined state,
00055            but no memory is leaked here because NodeType is
00056            responsible for cleaning up any of its children.
00057 
00058                    ACHTUNG: never pass the same destination container to 
00059                    this function more than once or you will get duplicate and/or
00060                    incorrect data.
00061 
00062            As of version 1.1.3, this function throws an s11n_exception
00063            if dest is not empty. The reason for this is to enforce
00064            that clients do not accidentally re-use the same (populated)
00065            node for serialization of multiple objects, which would cause
00066            deserialization of the container to fail.
00067                 */
00068                 template <typename NodeType, typename SerType>
00069                 bool serialize_list( NodeType & dest, const SerType & src );
00070 
00071 
00072 
00073                 /**
00074                    Identical to the two-argument form of serialize_list(), but
00075                    serializes src into a subnode of dest, named subnodename.
00076 
00077            If serialization into dest child fails, the child
00078            node is not added to dest and the error (possibly
00079            an exception) is propagated back to the caller.
00080                 */
00081                 template <typename NodeType, typename SerType>
00082                 bool serialize_list( NodeType & dest, const std::string & subnodename, const SerType & src );
00083 
00084 
00085         /**
00086            Functor equivalent of serialize_list().
00087 
00088            Added in version 1.1.3.
00089         */
00090                 struct serialize_list_f : ::s11n::serialize_binary_f_tag
00091         {
00092             template <typename NodeType, typename SerType>
00093             inline bool operator()( NodeType & dest, const SerType & src ) const
00094             {
00095                 return serialize_list<NodeType,SerType>( dest, src );
00096             }
00097 
00098             template <typename NodeType, typename SerType>
00099             inline bool operator()( NodeType & dest, const std::string & subnodename, const SerType & src ) const
00100             {
00101                 return serialize_list<NodeType,SerType>( dest, src );
00102             }
00103         };
00104 
00105 
00106                 /**
00107                    For each [src.children().begin(),end()) an object
00108                    of type SerType::value_type is created, deserialized,
00109                    and is added to dest via push_back( item ).
00110 
00111                    See serialize_list() for the list type requirements.
00112 
00113                    If SerType::value_type is a pointer type then dest owns any
00114                    newly-created pointers, and it's owner (or the container
00115                    itself) is responsible for cleaning them up. (Non-pointer
00116                    types need no explicit clean-up, of course.)
00117 
00118            SerType requirements:
00119 
00120            - Must be a Serializable type, as must contained type(s).
00121 
00122            - May not be a pointer type, but may contain pointer types.
00123 
00124            - A working s11n_traits<SerType>::cleanup_functor must be
00125            installed which properly frees up list entries.
00126 
00127            - Must have a swap() member function, to support the
00128            no-change-on-error policy.
00129 
00130            dest must be empty upon calling this function, or
00131            its contents will be irrevocably lost when this
00132            function succeeds (which would lead to a leak if
00133            dest contained unmanaged pointers, even
00134            indirectly).
00135 
00136 
00137                    Returns true if all deserializations succeed.
00138                    Stops processing and returns false at the first
00139                    error, in which case dest is not modified: some
00140                    children may or may not have been successfully
00141                    deserialized, but we destroy them if
00142                    deserialization of any fail. One immediate
00143                    implication of this is that it will fail if src
00144                    contains any other children than the type which
00145                    dest expects. The s11n_traits::cleanup_functor
00146            is used to ensure that cleanup walks through
00147            any containers which hold pointers, deallocating
00148            them as well.
00149 
00150            This function only throws if an underlying call to
00151            deserialize() or the classloader throws or if there
00152            is some sort of internal error (e.g., src contains
00153            child pointers which point to NULL).
00154 
00155            Major behaviour change in 1.1.3+:
00156 
00157            If this function throws or returns false then the
00158            target list is left untouched. See
00159            ::s11n::map::deserialize_map() for more
00160            information.
00161                 */
00162                 template <typename NodeType, typename SerType>
00163                 bool deserialize_list( const NodeType & src, SerType & dest );
00164 
00165 
00166 
00167                 /**
00168                    Identical to the two-argument form of deserialize_list(), but
00169                    deserializes a subnode of src, named subnodename. If no such
00170                    child is found in src then false is returned.
00171                 */
00172                 template <typename NodeType, typename SerType>
00173                 bool deserialize_list( const NodeType & src, const std::string & subnodename, SerType & dest );
00174 
00175 
00176         /**
00177            Functor equivalent of deserialize_list().
00178 
00179            Added in version 1.1.3.
00180         */
00181                 struct deserialize_list_f : ::s11n::deserialize_binary_f_tag
00182         {
00183 
00184             template <typename NodeType, typename SerType>
00185             inline bool operator()( const NodeType & src, SerType & dest ) const
00186             {
00187                 return deserialize_list<NodeType,SerType>( src, dest );
00188             }
00189 
00190             template <typename NodeType, typename SerType>
00191             inline bool operator()( const NodeType & src, const std::string & subnodename, SerType & dest ) const
00192             {
00193                 return deserialize_list<NodeType,SerType>( src, dest );
00194             }
00195         };
00196 
00197 
00198                 /**
00199                    serialize_streamable_list serializes objects of type
00200                    <tt>std::list&lt;X&gt;</tt> (and compatible list types,
00201                    such as std::vector). It stores them in such a way that
00202                    they can be loaded into any compatible container via
00203                    deserialize_streamable_list().
00204 
00205                    Conventions:
00206 
00207                    - NodeType must support a generic set(Key,Val) function, as
00208                    implemented by the s11n::data_node interface.
00209 
00210                    - ListType must conform to std::list conventions and it's
00211                    value_type must be a non-pointer type which is
00212                    i/ostreamable (this includes all PODs and
00213                    std::string). Pointers are not supported by
00214                    this function.
00215 
00216                    ACHTUNG:
00217 
00218                    - Never call this on a node for which you store other
00219                    properties, as deserialize_streamable_list() will consume them
00220                    if you use that function.
00221 
00222                    - This function sets dummy property keys, both to please
00223                    the conventions of keys having non-empty values and to keep
00224                    the list in the proper order. It uses keys which should be
00225                    portable to, e.g., standard XML.
00226 
00227                    Always returns true - the bool return value is for API consistency.
00228 
00229                    ACHTUNG 2:
00230 
00231                    - The return type of this function was changed from size_t
00232                    to bool in version 0.9.10.
00233                 */
00234                 template <typename NodeType, typename ListType>
00235                 bool serialize_streamable_list( NodeType & dest, const ListType & src );
00236 
00237 
00238                 /**
00239                    Identical to serialize_streamable_list(dest,src), but
00240                    creates a subnode in dest, named subnodename, where the
00241                    data is stored.
00242 
00243                    ACHTUNG:
00244 
00245                    - The return type of this function was changed from size_t
00246                    to bool in version 0.9.10.
00247                 */
00248                 template <typename NodeType, typename ListType>
00249                 bool serialize_streamable_list( NodeType & dest, const std::string & subnodename, const ListType & src );
00250 
00251 
00252         /**
00253            Functor equivalent of serialize_streamable_list().
00254 
00255            Added in version 1.1.3.
00256         */
00257                 struct serialize_streamable_list_f : ::s11n::serialize_binary_f_tag
00258         {
00259             template <typename NodeType, typename ListType>
00260             inline bool operator()( NodeType & dest, const ListType & src ) const
00261             {
00262                 return serialize_streamable_list<NodeType,ListType>( dest, src );
00263             }
00264 
00265             template <typename NodeType, typename ListType>
00266             inline bool operator()( NodeType & dest, const std::string & subnodename, const ListType & src ) const
00267             {
00268                 return serialize_streamable_list<NodeType,ListType>( dest, src );
00269             }
00270         };
00271 
00272 
00273                 /**
00274                    Deserializes dest from src. It reads in all properties from
00275                    src, ignoring their keys and taking only their values. This
00276                    is suitable for use with the result of a
00277                    serialize_streamable_list() call. See that function for more
00278                    information, including the conventions which must be
00279                    supported by NodeType and ListType.
00280            
00281                    Always returns true - the bool return value is for API consistency.
00282 
00283                    ACHTUNG:
00284 
00285                    - The return type of this function was changed from size_t
00286                    to bool in version 0.9.10.
00287 
00288                 */
00289                 template <typename NodeType, typename ListType>
00290                 bool deserialize_streamable_list( const NodeType & src, ListType & dest );
00291 
00292 
00293 
00294                 /**
00295                    Identical to deserialize_streamable_list(), but looks for
00296                    the data in a subnode of src named subnodename.
00297 
00298                    Returns false if no child could be found.
00299 
00300                    ACHTUNG:
00301 
00302                    - The return type of this function was changed from size_t
00303                    to bool in version 0.9.10.
00304 
00305                 */
00306                 template <typename NodeType, typename ListType>
00307                 bool deserialize_streamable_list( const NodeType & src, const std::string & subnodename, ListType & dest );
00308 
00309 
00310 
00311 
00312 
00313         /**
00314            Functor equivalent of deserialize_streamable_list().
00315 
00316            Added in version 1.1.3.
00317         */
00318                 struct deserialize_streamable_list_f : ::s11n::deserialize_binary_f_tag
00319         {
00320             template <typename NodeType, typename ListType>
00321             inline bool operator()( const NodeType & src, const std::string & subnodename, ListType & dest ) const
00322             {
00323                 return deserialize_streamable_list<NodeType,ListType>( src, dest );
00324             }
00325 
00326             template <typename NodeType, typename ListType>
00327             inline bool operator()( const NodeType & src, ListType & dest ) const
00328             {
00329                 return deserialize_streamable_list<NodeType,ListType>( src, dest );
00330             }
00331         };
00332 
00333 
00334                 /**
00335                    list_serializable_proxy is a functor for de/serializing lists
00336                    of Serializables.
00337                 */
00338                 class list_serializable_proxy : ::s11n::serialize_binary_f_tag,
00339                         ::s11n::deserialize_binary_f_tag
00340                 {
00341                 public:
00342                         list_serializable_proxy()
00343                         {}
00344 
00345                         /**
00346                            see serialize_list().
00347 
00348                         */
00349                         template <typename NodeType, typename SerType>
00350                         inline bool operator()( NodeType & dest, const SerType & src ) const
00351                         {
00352                                 return serialize_list( dest, src );
00353                         }
00354 
00355                         /** see deserialize_list(). */
00356                         template <typename NodeType, typename SerType>
00357                         inline bool operator()( const NodeType & src, SerType & dest ) const
00358                         {
00359                                 return deserialize_list( src, dest );
00360                         }
00361                 };
00362 
00363                 /**
00364                    streamable_list_serializable_proxy is a functor for de/serializing lists
00365                    of i/ostreamable Serializables (e.g., PODs).
00366                 */
00367                 class streamable_list_serializable_proxy : ::s11n::serialize_binary_f_tag,
00368                                ::s11n::deserialize_binary_f_tag
00369                 {
00370                 public:
00371                         streamable_list_serializable_proxy()
00372                         {}
00373 
00374                         /**
00375                            see serialize_streamable_list().
00376 
00377                         */
00378                         template <typename NodeType, typename SerType>
00379                         inline bool operator()( NodeType & dest, const SerType & src ) const
00380                         {
00381                                 return serialize_streamable_list( dest, src );
00382                         }
00383 
00384                         /** see deserialize_streamable_list(). */
00385                         template <typename NodeType, typename SerType>
00386                         inline bool operator()( const NodeType & src, SerType & dest ) const
00387                         {
00388                                 return deserialize_streamable_list( src, dest );
00389                         }
00390                 };
00391 
00392 
00393 
00394         } // namespace list
00395 } // namespace s11n
00396 
00397 #include <s11n.net/s11n/proxy/listish.tpp> // implementations
00398 
00399 #endif // s11n_net_s11n_v1_1_LIST_HPP_INCLUDED

Generated on Wed Jun 4 21:44:19 2008 for libs11n by  doxygen 1.5.3