persistable_object.hpp

Go to the documentation of this file.

//
// See license.txt for license information.
//
// persistable_object.hpp
//
// 17-Jul-2003  phamilton  Created
//

#ifndef incCOMMON_PERSISTABLE_OBJECT
#define incCOMMON_PERSISTABLE_OBJECT

// forwards
#include <string>
#include "object.hpp"
#include "boost/filesystem/path.hpp"

namespace ph {
namespace common {

// forwards
class persistable_object_context;
class object_writer;

class persistable_object_base
/**
        Abstract class representing the interface for an object to be persisted.
        
        NOTE: This class is completely independant of reflection, although it is
        obvious that reflection combined with persistance is the perfect solution
        for complex objects. It is kept separate for the purposes
        of reusability.
*/
{
public:
        virtual ~persistable_object_base() {}
                        
        virtual object_base *create(
                const std::string &type, 
                const std::string &name, 
                persistable_object_context *context) = 0;
                //!< Allow one object to create another. this is dependant
                //! on the way you want to build new objects, but usually 
                //! it involves the Abstract Factory pattern.
                
        virtual object_base *get_composite_object(const std::string &name) = 0;
                //!< return the object if it is a composite one.
                //!
                
        virtual bool has(const std::string &name) const = 0;
                //!< Does this member name exist?
                //!
                 
        virtual void set(const std::string &name, const std::string &value) = 0;
                //!< Set the value of a member in the class with a particular name.
                //!
        virtual std::string get(const std::string &name) const = 0;
                //!< Get the value of a member in the class with a particular name.
                //!
                
        virtual bool write(object_writer *writer) const
                { return true; }
                //!< Write out the object using the writer passed in.
                //!
                
        virtual void set_file_path(const std::string &path) {}
                //!< This object is coming as the root object from a file. 
                //! Allow it to receive the path to this file.
};

class persistable_object_context
/**
        Abstract class representing a context that is passed when objects
        are created.
*/
{
public:
        virtual ~persistable_object_context() {};

        virtual object_base *create(
                const std::string &type, 
                const std::string &name) = 0;
                //!< Create an object of the appropriate type and name. Usually
                //! implemented with an Abstract Factory pattern.
                
        virtual object_base *find_object(
                object_base *root, 
                object_base *obj, 
                const std::string &location) = 0;
                //!< Find the object and return it if it's Composite.
                //! "root" is the root object of the tree.
                //! "obj" is the current object for relative locations.
                //! "location" is the path location.
                //!

        virtual object_base *find_composite_object(
                object_base *root, 
                object_base *obj, 
                const std::string &location) = 0;
                //!< Find the object and return it if it's Composite.
                //! "root" is the root object of the tree.
                //! "obj" is the current object for relative locations.
                //! "location" is the path location.
                //!

        virtual bool delayed_import() { return false; }
                //!< The XML parser can do delayed importing. This means that instead of
                //! actually importing an external file, a placeholder object is created and
                //! then when this placeholder is referenced, the actual import is performed.
                //! This speeds up extremely large object systems, and you can enable this
                //! behaviour by returning true here. If your parser doesn't
                //! handle this type of importing, then throw an error if this is set to
                //! true (or something).

        virtual ph::common::object_base *create_delayed(
                std::ostream *console,
                const boost::filesystem::path &url, 
                const std::string &name, 
                unsigned int debug) { return 0 ; }
                //!< Create an object to hold delayed import information.
};

class object_writer
/**
        Abstract class used to write an object out.
*/
{
public:
        virtual ~object_writer() {};
        
        virtual bool start(const std::string &tagname) = 0;
                //!< Start a new tag with the writer.
                //!
        virtual bool attr(const std::string &name, const std::string &value) = 0;
                //!< Write out name/value pairs for the tag.
                //!
        virtual bool data(const std::string &d) = 0;
                //!< Write out arbitrary data for the tag.
                //!
        virtual bool end(const std::string &tagname) = 0;
                //!< End the tag. Note that it is usually possible for the
                //! implementation of the writer to save away the tag name,
                //! but for keeping the writers simple, it is included again.
};

class object_writer_context
/**
        A context used to start a tag, and then correctly end it
        upon destruction.
        
        This allows code such as:
        
        object_writer_context c(writer, "foo");
        c.attr("name", "foo_1");
        c.data("Hello World");
        
        To be used rather than explicitly starting and ending the tags.
*/
{
public:
        object_writer_context(object_writer *writer, const std::string &tagname) :
                _writer(writer), _tagname(tagname)
                { _writer->start(_tagname); }
        ~object_writer_context()
                { _writer->end(_tagname); }
        void attr(const std::string &name, const std::string &value)
                { _writer->attr(name, value); }
        void data(const std::string &d)
                { _writer->data(d); }
        
private:
        object_writer *_writer;
        std::string    _tagname;
};

inline bool get_persistable_obj_name(const object_base *obj, std::string *name)
/**
        Function to return an objects name using the persistance scheme.
*/
{
        if (!obj->persistable())
                return false;
                
        *name = obj->persistable()->get("name");
        return true;
}

inline bool get_persistable_obj_type(const object_base *obj, std::string *type)
/**
        Function to return an objects type using the persistance scheme.
*/
{
        if (!obj->persistable())
                return false;
                
        *type = obj->persistable()->get("type");
        return true;
}

inline bool set_persistable_obj_name(object_base *obj, const std::string &name)
/**
        Function to set an objects name using the persistance scheme.
*/
{
        if (!obj->persistable())
                return false;
                
        obj->persistable()->set("name", name);
        return true;
}

inline bool set_persistable_obj_type(object_base *obj, const std::string &type)
/**
        Function to set an objects type using the persistance scheme.
*/
{
        if (!obj->persistable())
                return false;
                
        obj->persistable()->set("type", type);
        return true;
}

}; // common
}; // ph

#endif // incCOMMON_PERSISTABLE_OBJECT

---