micro_api.hpp

Go to the documentation of this file.
00001 #ifndef s11nlite_MICROAPI_HPP_INCLUDED
00002 #define s11nlite_MICROAPI_HPP_INCLUDED 1
00003 
00004 #include <s11n.net/s11n/s11nlite.hpp>
00005 namespace s11nlite
00006 {
00007 
00008     /**
00009        micro_api is of arguable utility, written just to see what
00010        happens. It is intended to be used for saving and loading
00011        sets of like-typed Serializables. For apps which do lots of
00012        loading and saving of homogeonous Serializables, micro_api
00013        can cut down on the amount of typing (intentionally
00014        ambiguous) needed:
00015 
00016 <pre>
00017 s11nlite::micro_api<MyT> micro;
00018 MyT my;
00019 ... populate my ...
00020 micro.save( my, "somefile" );
00021 ...
00022 MyT * your = micro.load( "somefile" );
00023 </pre>
00024 
00025            Unlike the s11nlite interface, micro_api explicitely hides
00026            all node-level details. It does allow the user to set an
00027            output format (serializer class), as it may be desirable to
00028            save different collections of objects in different formats.
00029            For loading it uses s11nlite, so it supports any formats
00030        supported there.
00031 
00032        Templatized on:
00033 
00034        - SerializableType must be the base-most Serializable type
00035        in a given Serializable hierarchy (or the Serializable type
00036        itself, for monomorphs).
00037 
00038        Any functions in this class might throw if their s11n[lite]
00039        counterparts do.
00040     */
00041 
00042     template <typename SerializableType>
00043     class micro_api
00044     {
00045     public:
00046         /**
00047            The base Serializable interface associated with
00048            this object.
00049         */
00050         typedef SerializableType serializable_type;
00051 
00052     private:
00053         typedef s11nlite::node_type node_type;
00054         typedef s11nlite::node_traits node_traits;
00055         typedef s11nlite::serializer_interface serializer_interface;
00056         std::string m_serclass;
00057         std::string m_buffer;
00058         /**
00059            Internal helper to reduce a small amount of code duplication
00060            in the two save() variants.
00061 
00062            Serializes src to dest, returning 0 if that fails.
00063            If serialization to the node succeeds, it returns
00064            s11nlite::create_serialize(this->serializer_class()). The
00065            caller owns the returned pointer, which may be 0.
00066         */
00067         serializer_interface *
00068         prepare_save( node_type & dest, const serializable_type & src ) const
00069         {
00070             if( ! ::s11n::serialize<node_type,serializable_type>( dest, src ) )
00071             {
00072                 return 0;
00073             }
00074             return ::s11nlite::create_serializer(this->m_serclass);
00075         }
00076     public:
00077         /**
00078            Constructs an object with the given serializer_class().
00079         */
00080         micro_api( const std::string & serclass ) : m_serclass(serclass),m_buffer()
00081         {
00082         }
00083 
00084         /** Does nothing. */
00085         ~micro_api() {}
00086         
00087         /**
00088            Constructs an object with the same
00089            serializer_class() as s11nlite::serializer_class().
00090         */
00091         micro_api() : m_serclass(::s11nlite::serializer_class()),m_buffer()
00092         {
00093         }
00094 
00095         /** Returns the current serializer class name. */
00096         std::string serializer_class() const
00097         {
00098             return this->m_serclass;
00099         }
00100 
00101         /** Sets the current serializer class name. */
00102         void serializer_class(const std::string & s)
00103         {
00104             this->m_serclass = s;
00105         }
00106 
00107         /**
00108            Serializes src to an internal buffer, which may be fetched
00109            and cleared with buffer() and clear_buffer(), respectively.
00110         */
00111         bool buffer( const serializable_type & src )
00112         {
00113             std::ostringstream os;
00114             if( ! this->save( src, os ) ) return false;
00115             this->m_buffer = os.str();
00116             return true;
00117         }
00118 
00119         /**
00120            Returns this object's buffered data, if any has
00121            been set using buffer(serializable_type). The
00122            buffer can be deserialized by wrapping it in an
00123            istringstream.
00124         */
00125         std::string buffer() const { return this->m_buffer; }
00126 
00127         /**
00128            Clears any buffered data saved using
00129            buffer(serializable_type).
00130         */
00131         void clear_buffer() { this->m_buffer = std::string(); }
00132 
00133         /**
00134            Saves src to dest, returning true on success and false on error.
00135            If the underlying call(s) to serialize throw then this function
00136            pass on the exception.
00137         */
00138         bool save( const serializable_type & src, const std::string & dest ) const
00139         {
00140             node_type n;
00141             std::auto_ptr<serializer_interface> sap( this->prepare_save( n, src ) );
00142             return sap.get() ? sap->serialize( n, dest ) : false;
00143         }
00144 
00145         /** Overload taking an ostream. */
00146         bool save( const serializable_type & src, std::ostream & dest ) const
00147         {
00148             node_type n;
00149             std::auto_ptr<serializer_interface> sap( this->prepare_save( n, src ) );
00150             return sap.get() ? sap->serialize( n, dest ) : false;
00151         }
00152 
00153         /**
00154            Loads a serializable_type from src, returning 0 on
00155            failure and a valid pointer on success (which the
00156            caller owns). If the underlying call(s) to
00157            serialize throw then this function passes on the
00158            exception. In that case the object which was allocated
00159            for the process (if any) is destroyed, cleaned up
00160            by the s11n_traits::cleanup_functor mechanism, which is
00161            believed to be relatively safe from memory leaks.
00162         */
00163         serializable_type * load( const std::string & src ) const
00164         {
00165             return ::s11nlite::load_serializable<serializable_type>( src );
00166         }
00167     
00168         /**
00169            An overload which takes an istream instead of a string.
00170         */
00171         serializable_type * load( std::istream & src ) const
00172         {
00173             return ::s11nlite::load_serializable<serializable_type>( src );
00174         }
00175 
00176         /**
00177            Loads a Serializable from the buffer() content, if any.
00178            The caller owns the returned pointer, which may be 0.
00179         */
00180         serializable_type * load_buffer() const
00181         {
00182             if( this->m_buffer.empty() ) return 0;
00183             std::istringstream is( this->m_buffer );
00184             return ::s11nlite::load_serializable<serializable_type>( is );
00185         }
00186         
00187 
00188     };
00189 
00190 
00191 } // namespace s11nlite
00192 
00193 
00194 #endif // s11nlite_MICROAPI_HPP_INCLUDED

Generated on Thu Feb 8 10:20:44 2007 for libs11n-1.2.5 by  doxygen 1.5.0