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>

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. There is a theoretical solution, for those wanting more control: subclass this type with another template type: serializable_api<SerializableType>. Then you can add virtual functions which take the place of the templated members. Not sure if overloading rules will let you get away with it, but it sounds halfway reasonable.

TODOs:

Definition at line 74 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 97 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 100 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 106 of file client_api.hpp.


Constructor & Destructor Documentation

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

Definition at line 81 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 85 of file client_api.hpp.

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

Definition at line 89 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 113 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 138 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 159 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 168 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 179 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 190 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 199 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 226 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 246 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 277 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 297 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 319 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 333 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 352 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 363 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 373 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 382 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 393 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 410 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 422 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 431 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 454 of file client_api.hpp.


The documentation for this class was generated from the following file:
Generated on Wed Jun 4 21:45:47 2008 for libs11n-1.2.7 by  doxygen 1.5.3