objtree.h

Go to the documentation of this file.

/*
 * objtree.h
 * 
 * Copyright (C) 2006,2008  Thomas A. Vaughan
 * All rights reserved.
 *
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *     * Redistributions of source code must retain the above copyright
 *       notice, this list of conditions and the following disclaimer.
 *     * Redistributions in binary form must reproduce the above copyright
 *       notice, this list of conditions and the following disclaimer in the
 *       documentation and/or other materials provided with the distribution.
 *     * Neither the name of the <organization> nor the
 *       names of its contributors may be used to endorse or promote products
 *       derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THOMAS A. VAUGHAN ''AS IS'' AND ANY
 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL THOMAS A. VAUGHAN BE LIABLE FOR ANY
 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

#ifndef WAVEPACKET_OBJTREE_H__
#define WAVEPACKET_OBJTREE_H__


// includes --------------------------------------------------------------------
#include "common/common.h"
#include "datahash/datahash.h"

/// \ingroup general
/*@{*/

////////////////////////////////////////////////////////////////////////////////
///
/// \defgroup objtree Object Tree API
///
/// API for manipulating hierarchical trees of objects + properties.
///
/// This is typically used by UI applications when the user has selected a
/// number of different object, and then wants to see/edit properties.  This
/// low-level API abstracts the general (hierarchical) set of objects.
///
////////////////////////////////////////////////////////////////////////////////

/*@{*/


namespace objtree {


/// returns true if the given name is an acceptable property name
///
/// property names are very restricted!  alphanumerics and hyphens only
///  goal is names that do not need to be URL encoded etc
bool isValidPropertyName(IN const char * candidate_name) throw();


/// abstraction of a general property of an object
///
/// This attempts to capture the metadata around a property.  For instance,
/// the user may have selected a rectangle, and they want the properties of
/// the rectangle.  A single property of the rectangle (for instance the
/// line color) will be generally represented by this.  The "value" of the
/// property is the line color (red, black, whatever).  But there could be
/// other metadata fields such as the property type (it is a color, not a
/// weight or length etc.).  It could have units (lengths could be measured
/// in meters or miles, etc.).  And so on.
///
/// There are multiple
///     possible metadata fields (up to the client), such as the type (string?
///     float?  int?  color?), units (centimeters?  miles?  liters?) etc.
///
/// There is one "special" property, the value.  All property_t objects are
///     required to have a value entry, albeit empty.  All other fields may
///     not exist (and getFieldValue() can return null for those).  But
///     clients can rely on getValue() returning non-null at least.
struct property_t : public Dictionary {
        // constructor, manipulators
        property_t(IN const char * in_value) {
                        ASSERT(in_value, "null input value");
                        this->setValue(in_value);
                }
        property_t(void) throw() { this->clear(); }

        void clear(void) throw() {
                        Dictionary::clear();
                        this->setValue(NULL);
                }

        void setFieldValue(IN const char * field, IN const char * value) {
                        ASSERT(field, "null field");
                        ASSERT(value, "null value");
                        ASSERT(strcmp(field, "name"),
                            "'name' is a reserved property field value");
                        this->operator[](field) = value;
                }

        const char * getFieldValue(IN const char * field) const throw() {
                        ASSERT(field, "null field");
                        Dictionary::const_iterator i = this->find(field);
                        if (this->end() == i)
                                return NULL;            // field not found
                        return i->second.c_str();
                }

        const char * getOptionalFieldValue(IN const char * field,
                                IN const char * default_value) const throw() {
                        const char * val = this->getFieldValue(field);
                        return (val) ? val : default_value;
                }

        void setValue(IN const char * value) throw() {
                        if (!value)
                                value = "";
                        this->setFieldValue("value", value);
                }

        const char * getValue(void) const throw() {
                        return this->getFieldValue("value");
                }

        void dump(IN const char * title) const throw();
};



/// a set of properties.
///
/// For instance, a rectangle object could have a propert set which contained
/// a property "line_color", "line_style", "fill_color", etc.
struct property_set_t : public std::map<std::string, property_t> {
        // manipulators
        void addProperty(IN const char * name,
                                IN const char * value) {
                        ASSERT(isValidPropertyName(name),
                            "Bad property name: '%s'", name);
                        (*this)[name] = property_t(value);
                }

        property_t * getProperty(IN const char * name) throw() {
                        ASSERT(isValidPropertyName(name),
                            "Bad property name: '%s'", name);
                        property_set_t::iterator i = this->find(name);
                        if (this->end() == i)
                                return NULL;    // property not found
                        return &i->second;
                }

        const property_t * getProperty(IN const char * name) const throw() {
                        ASSERT(isValidPropertyName(name),
                            "Bad property name: '%s'", name);
                        property_set_t::const_iterator i = this->find(name);
                        if (this->end() == i)
                                return NULL;    // property not found
                        return &i->second;
                }

        const char * getValue(IN const char * name) const throw() {
                        ASSERT(isValidPropertyName(name),
                            "Bad property name: '%s'", name);
                        const property_t * p = this->getProperty(name);
                        if (!p)
                                return NULL;    // not found
                        return p->getValue();
                }

        const char * getOptionalValue(IN const char * name,
                                IN const char * default_value) const throw() {
                        const char * value = this->getValue(name);
                        return value ? value : default_value;
                }

        void dump(IN const char * title) const throw();
};



////////////////////////////////////////////////////////////////////////////////
///
///     How you interact with this object is the key to the objtree library.
///
///     You can add and remove objects by their (client-specified) ID.
///
///     You can then iteract with multiple objects at once by specifying the
///     targets as an id_query rather than a single ID.  For instance, you could
///     call
/// \code
///     list->setProperties("*", my_property_set);
/// \endcode
///     which would update that property for all objects in the list, provided
///     they already had a property of that name.
///
///     NOTE: query support is a bit limited.  At the moment you can only use
///     a specific ID, or the query "*" which specifies all IDs in the list.
///     Better query support could obviously be added but I haven't needed it.
///
////////////////////////////////////////////////////////////////////////////////
class List {
public:
        // virtual destructor --------------------------------------------------
        virtual ~List(void) throw();

        // objtree::List class interface methods -------------------------------
        virtual bool addObject(IN const char * id) = 0;
        virtual bool removeObject(IN const char * id) = 0;
        virtual void getObjects(IN const char * id_query,
                                OUT VecString& ids) = 0;

        /// getProperties -- retrieves properties common to all objects
        virtual void getProperties(IN const char * id_query,
                                OUT property_set_t& pset) = 0;

        /// addProperties -- adds if necessary, sets all properties on all objs
        virtual void addProperties(IN const char * id_query,
                                IN const property_set_t& pset) = 0;

        /// setProperties -- sets properties only if exists + matches on object
        virtual void setProperties(IN const char * id_query,
                                IN const property_set_t& pset) = 0;

        // public static methods (factories) -----------------------------------
        static smart_ptr<List> create(void);
};



/// the root object for discovering objects
///
/// Why isn't this recursive?  Because the lists already contain recursive
/// structure (you can use nested object IDs and treat them as paths).
///
/// So the List could properly be described as a Tree, and this is really a
/// Forest.
class Tree {
public:
        // virtual destructor --------------------------------------------------
        virtual ~Tree(void) throw();

        // objtree::Tree class interface methods -------------------------------
        /// return the list (and create if no list exists yet by that name)
        virtual List * getList(IN const char * name) = 0;

        /// return names of all lists
        virtual void getListNames(OUT VecString& names) = 0;

        // public static methods (factories) -----------------------------------
        static smart_ptr<Tree> create(void);
};



////////////////////////////////////////////////////////////////////////////////
//
//      helper methods
//
////////////////////////////////////////////////////////////////////////////////

bool isTrue(IN const char * text) throw();

/// given a property set, serialize into a datahash object
smart_ptr<Datahash> getDatahash(IN const property_set_t& pset);

/// given a datahash, deserialize into a property set
void getPropertySet(IN const Datahash * hash,
                                OUT property_set_t& pset);


};      // objtree namespace

#endif  // WAVEPACKET_OBJTREE_H__