s11nlite::client_api< NodeType > Class Template Reference

client_api is an abstraction of the 1.0.x s11nlite interface (GAWD, NOT ANOTHER ABSTRACTION LAYER!), providing an interface which works with all compatible S11n Node types. More...

#include <client_api.hpp>

Collaboration diagram for s11nlite::client_api< NodeType >:

Collaboration graph
[legend]

List of all members.

Public Types

typedef NodeType node_type
 node_type is the type used to store/load a Serializable object's data.
typedef
s11n::node_traits
< node_type
node_traits
 The s11n::node_traits type for node_type.
typedef
s11n::io::data_node_serializer
< node_type
serializer_interface
 This is the base-most type of the serializers used by s11nlite clients.

Public Member Functions

 client_api ()
 client_api (const std::string &default_serializer_class)
virtual ~client_api ()
serializer_interfacecreate_serializer ()
 Returns create_serialize( serializer_class() ).
virtual
serializer_interface
create_serializer (const std::string &classname)
 Returns a new instance of the given serializer class, or 0 if one could not be loaded.
void serializer_class (const std::string &classname)
 Sets the current Serializer class used by s11nlite's create_serializer().
std::string serializer_class () const
 Gets the name of the current Serializer type.
virtual bool provides_serializer (const std::string &key)
 Returns true if key can be used to create a Serializer object via a call to serializer_class().
template<typename SerializableType>
bool serialize (node_type &dest, const SerializableType &src) const
 See s11n::serialize().
template<typename SerializableType>
bool serialize_subnode (node_type &dest, const std::string &subnodename, const SerializableType &src) const
 See s11n::serialize_subnode().
virtual bool save (const node_type &src, std::ostream &dest)
 Saves the given node to the given ostream using the default serializer type.
virtual bool save (const node_type &src, const std::string &filename)
 Saves the given node to the given filename using the default serializer type.
template<typename SerializableType>
bool save (const SerializableType &src, std::ostream &dest)
 Saves the given Serializable to the given ostream using the default serializer type.
template<typename SerializableType>
bool save (const SerializableType &src, const std::string &dest)
 Saves the given Serializable to the given filename using the default serializer type.
virtual node_typeload_node (const std::string &src)
 Tries to load a node from the given filename.
virtual node_typeload_node (std::istream &src)
 Tries to load a node from the given input stream.
template<typename SerializableType>
SerializableType * deserialize (const node_type &src) const
 Returns s11n::deserialize<node_type,SerializableType>(src).
template<typename DeserializableT>
bool deserialize (const node_type &src, DeserializableT &target) const
 See s11n::deserialize().
template<typename DeserializableT>
bool deserialize_subnode (const node_type &src, const std::string &subnodename, DeserializableT &target) const
 See s11n::deserialize_subnode().
template<typename DeserializableT>
DeserializableT * deserialize_subnode (const node_type &src, const std::string &subnodename) const
 See s11n::deserialize_subnode().
template<typename SerializableType>
SerializableType * load_serializable (std::istream &src)
 Tries to load a data_node from src, then deserialize that to a SerializableType.
template<typename SerializableType>
SerializableType * load_serializable (const std::string &src)
 Overloaded form which takes a file name.
template<typename SerializableType>
SerializableType * clone (const SerializableType &tocp) const
 See s11n::s11n_clone().
template<typename Type1, typename Type2>
bool cast (const Type1 &t1, Type2 &t2) const
 See s11n::s11n_cast().

Static Public Member Functions

static client_api
< node_type > & 
instance ()
 Returns a shared instance of this class.


Detailed Description

template<typename NodeType>
class s11nlite::client_api< NodeType >

client_api is an abstraction of the 1.0.x s11nlite interface (GAWD, NOT ANOTHER ABSTRACTION LAYER!), providing an interface which works with all compatible S11n Node types.

The intention of this class is for projects to have easy access to an s11nlite-like interface for their own node types. s11nlite, as of s11n 1.2, will be based off of this type.

Another use of this class is in conjunction with s11n::fac::instance_hook: clients may specialize that type to make this type's instance() function return a custom client_api object. The intention of this feature is to allow clients to extend the s11nlite interface "from inside" while allowing client code to keep using the s11nlite interface. This allows, amongst other things, extending s11nlite to support special i/o channels (as provided, e.g., by pclasses.com's libraries) without actually touching s11nlite. See http://s11n.net/ps11n/ for where this is headed...

Particularly observant users might notice that many of this type's functions which "probably should be" const are not const. This is because subclasses are encouraged to add features behind the basic API, and many would not be practical without a non-const object. As an example, a subclass might want to do DLL lookups and may need to modify internal tables when it does so. Template functions which can be made const are const. This would appear to be inconsistent, but it is in fact me trying to make up for more of the API not being const.

The NodeType parameterized type must be compatible with the s11n's "Data Node" type conventions (e.g., s11n::s11n_node).

Clients may notice that not much of this API is virtual. That's not because i'm anal, but because most of the API is template functions, and those can't be virual.

While this type's interface does not require it, it is believed that all of the member functions of client_api's base implementation are thread-safe and reentrant EXCEPT for the serializer_class() getter/setter pair. Even with thread locking, there are a lot of possible race conditions regarding setting that value and fetching it. Since the setter is rarely used (typically once per application), this is not considered to be a serious problem.

TODOs:

Definition at line 76 of file client_api.hpp.


Member Typedef Documentation

template<typename NodeType>
typedef NodeType s11nlite::client_api< NodeType >::node_type

node_type is the type used to store/load a Serializable object's data.

Definition at line 104 of file client_api.hpp.

template<typename NodeType>
typedef s11n::node_traits<node_type> s11nlite::client_api< NodeType >::node_traits

The s11n::node_traits type for node_type.

Definition at line 107 of file client_api.hpp.

template<typename NodeType>
typedef s11n::io::data_node_serializer<node_type> s11nlite::client_api< NodeType >::serializer_interface

This is the base-most type of the serializers used by s11nlite clients.

Definition at line 113 of file client_api.hpp.


Constructor & Destructor Documentation

template<typename NodeType>
s11nlite::client_api< NodeType >::client_api (  )  [inline]

Definition at line 84 of file client_api.hpp.

template<typename NodeType>
s11nlite::client_api< NodeType >::client_api ( const std::string &  default_serializer_class  )  [inline, explicit]

Definition at line 90 of file client_api.hpp.

template<typename NodeType>
virtual s11nlite::client_api< NodeType >::~client_api (  )  [inline, virtual]

Definition at line 96 of file client_api.hpp.


Member Function Documentation

template<typename NodeType>
serializer_interface* s11nlite::client_api< NodeType >::create_serializer (  )  [inline]

Returns create_serialize( serializer_class() ).

The caller owns the returned pointer.

Definition at line 120 of file client_api.hpp.

template<typename NodeType>
virtual serializer_interface* s11nlite::client_api< NodeType >::create_serializer ( const std::string &  classname  )  [inline, virtual]

Returns a new instance of the given serializer class, or 0 if one could not be loaded.

classname must represent a subtype of serializer_interface.

The caller owns the returned pointer.

You can also pass a serializer's cookie here, and that should return the same thing as it's class name would.

The internally-supported serializers all register a "friendly form" of the name, an alias registered with their classloader. Passing either this name or the cookie of the Serializer should return the same thing as the classname itself would.

Subclasses may do, e.g., lookups for externally-linked serializers.

Definition at line 146 of file client_api.hpp.

template<typename NodeType>
void s11nlite::client_api< NodeType >::serializer_class ( const std::string &  classname  )  [inline]

Sets the current Serializer class used by s11nlite's create_serializer().

Pass it a class name, or one of the convenience names, e.g.:

compact, funtxt, funxml, simplexml, parens, wesnoth, and expat (if your s11n was built with it).

You may use provides_serializer() to check for the existence of a class. This function does no validation of classname: this is delayed until save/load-time, to allow for DLL lookups during the normal classloading process (as opposed to duplicating that check here).

Definition at line 167 of file client_api.hpp.

template<typename NodeType>
std::string s11nlite::client_api< NodeType >::serializer_class (  )  const [inline]

Gets the name of the current Serializer type.

Definition at line 178 of file client_api.hpp.

template<typename NodeType>
virtual bool s11nlite::client_api< NodeType >::provides_serializer ( const std::string &  key  )  [inline, virtual]

Returns true if key can be used to create a Serializer object via a call to serializer_class().

Subclasses may do additional work here, like look up DLLs, which is why the function is not const.

Definition at line 189 of file client_api.hpp.

References s11nlite::instance().

template<typename NodeType>
template<typename SerializableType>
bool s11nlite::client_api< NodeType >::serialize ( node_type dest,
const SerializableType &  src 
) const [inline]

See s11n::serialize().

Definition at line 200 of file client_api.hpp.

Referenced by s11nlite::client_api< NodeType >::save().

template<typename NodeType>
template<typename SerializableType>
bool s11nlite::client_api< NodeType >::serialize_subnode ( node_type dest,
const std::string &  subnodename,
const SerializableType &  src 
) const [inline]

See s11n::serialize_subnode().

Definition at line 209 of file client_api.hpp.

References s11n::node_traits< NodeT >::children(), and s11n::node_traits< NodeT >::create().

template<typename NodeType>
virtual bool s11nlite::client_api< NodeType >::save ( const node_type src,
std::ostream &  dest 
) [inline, virtual]

Saves the given node to the given ostream using the default serializer type.

Returns true on success, false on error.

ONLY use this for saving root nodes!

Definition at line 236 of file client_api.hpp.

Referenced by s11nlite::client_api< NodeType >::save().

template<typename NodeType>
virtual bool s11nlite::client_api< NodeType >::save ( const node_type src,
const std::string &  filename 
) [inline, virtual]

Saves the given node to the given filename using the default serializer type.

Returns true on success, false on error.

ONLY use this for saving root nodes!

Subclasses are free to interpret the filename however they like, e.g., as a URL or database record name.

Definition at line 256 of file client_api.hpp.

template<typename NodeType>
template<typename SerializableType>
bool s11nlite::client_api< NodeType >::save ( const SerializableType &  src,
std::ostream &  dest 
) [inline]

Saves the given Serializable to the given ostream using the default serializer type.

Returns true on success, false on error.

ONLY use this for saving root nodes!

Subclassers: this function serializes src to a node and then calls save(node,dest).

Definition at line 287 of file client_api.hpp.

References s11nlite::client_api< NodeType >::save(), and s11nlite::client_api< NodeType >::serialize().

template<typename NodeType>
template<typename SerializableType>
bool s11nlite::client_api< NodeType >::save ( const SerializableType &  src,
const std::string &  dest 
) [inline]

Saves the given Serializable to the given filename using the default serializer type.

Returns true on success, false on error.

ONLY use this for saving root nodes!

Subclassers: this function serializes src to a node and then calls save(node,dest).

Definition at line 307 of file client_api.hpp.

References s11nlite::client_api< NodeType >::save(), and s11nlite::client_api< NodeType >::serialize().

template<typename NodeType>
virtual node_type* s11nlite::client_api< NodeType >::load_node ( const std::string &  src  )  [inline, virtual]

Tries to load a node from the given filename.

The caller owns the returned pointer.

Subclasses are free to interpret the filename however they like, e.g., as a URL or database record name.

Definition at line 329 of file client_api.hpp.

template<typename NodeType>
virtual node_type* s11nlite::client_api< NodeType >::load_node ( std::istream &  src  )  [inline, virtual]

Tries to load a node from the given input stream.

The caller owns the returned pointer, which may be 0.

Only usable for loading ROOT nodes.

Definition at line 343 of file client_api.hpp.

template<typename NodeType>
template<typename SerializableType>
SerializableType* s11nlite::client_api< NodeType >::deserialize ( const node_type src  )  const [inline]

Returns s11n::deserialize<node_type,SerializableType>(src).

Caller owns the returned pointer, which may be 0.

Note that this function is non-const because deserialization may indirectly classload other types or affect this object.

See the one-argument variant of s11n::deserialize() for IMPORTANT error-handling considerations for this function.

Definition at line 362 of file client_api.hpp.

template<typename NodeType>
template<typename DeserializableT>
bool s11nlite::client_api< NodeType >::deserialize ( const node_type src,
DeserializableT &  target 
) const [inline]

See s11n::deserialize().

Definition at line 373 of file client_api.hpp.

template<typename NodeType>
template<typename DeserializableT>
bool s11nlite::client_api< NodeType >::deserialize_subnode ( const node_type src,
const std::string &  subnodename,
DeserializableT &  target 
) const [inline]

See s11n::deserialize_subnode().

Definition at line 383 of file client_api.hpp.

template<typename NodeType>
template<typename DeserializableT>
DeserializableT* s11nlite::client_api< NodeType >::deserialize_subnode ( const node_type src,
const std::string &  subnodename 
) const [inline]

See s11n::deserialize_subnode().

Definition at line 392 of file client_api.hpp.

template<typename NodeType>
template<typename SerializableType>
SerializableType* s11nlite::client_api< NodeType >::load_serializable ( std::istream &  src  )  [inline]

Tries to load a data_node from src, then deserialize that to a SerializableType.

Definition at line 403 of file client_api.hpp.

template<typename NodeType>
template<typename SerializableType>
SerializableType* s11nlite::client_api< NodeType >::load_serializable ( const std::string &  src  )  [inline]

Overloaded form which takes a file name.

1.1.3: removed the never-used 2nd parameter.

Subclassers: the loading is done via load_node(), so you can intercept the src string there.

Definition at line 420 of file client_api.hpp.

template<typename NodeType>
template<typename SerializableType>
SerializableType* s11nlite::client_api< NodeType >::clone ( const SerializableType &  tocp  )  const [inline]

See s11n::s11n_clone().

Definition at line 432 of file client_api.hpp.

template<typename NodeType>
template<typename Type1, typename Type2>
bool s11nlite::client_api< NodeType >::cast ( const Type1 &  t1,
Type2 &  t2 
) const [inline]

See s11n::s11n_cast().

Definition at line 441 of file client_api.hpp.

References s11n::s11n_cast().

template<typename NodeType>
static client_api<node_type>& s11nlite::client_api< NodeType >::instance (  )  [inline, static]

Returns a shared instance of this class.

The object itself is post-main() safe (on most systems), meaning if this function is called after the shared object is destroy (after main() exits), it "should" actually behave properly be re-instantiating the object in-place. See s11n/phoenix.hpp for details and caveats. In the worst case, it's no less safe than any other post-main() object.

Definition at line 464 of file client_api.hpp.


The documentation for this class was generated from the following file:
Generated on Wed Jun 4 21:48:02 2008 for libs11n by  doxygen 1.5.3