NamedXMLResourceManager.h

/***********************************************************************
    filename:   CEGUINamedXMLResourceManager.h
    created:    Fri Jul 17 2009
    author:     Paul D Turner <paul@cegui.org.uk>
*************************************************************************/
/***************************************************************************
 *   Copyright (C) 2004 - 2009 Paul D Turner & The CEGUI Development Team
 *
 *   Permission is hereby granted, free of charge, to any person obtaining
 *   a copy of this software and associated documentation files (the
 *   "Software"), to deal in the Software without restriction, including
 *   without limitation the rights to use, copy, modify, merge, publish,
 *   distribute, sublicense, and/or sell copies of the Software, and to
 *   permit persons to whom the Software is furnished to do so, subject to
 *   the following conditions:
 *
 *   The above copyright notice and this permission notice shall be
 *   included in all copies or substantial portions of the Software.
 *
 *   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 *   EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 *   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
 *   IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
 *   OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
 *   ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
 *   OTHER DEALINGS IN THE SOFTWARE.
 ***************************************************************************/
#ifndef _CEGUINamedXMLResourceManager_h_
#define _CEGUINamedXMLResourceManager_h_

#include "CEGUI/EventSet.h"
#include "CEGUI/String.h"
#include "CEGUI/Exceptions.h"
#include "CEGUI/Logger.h"
#include "CEGUI/InputEvent.h"
#include "CEGUI/System.h"
#include <map>

// Start of CEGUI namespace section
namespace CEGUI
{
enum XMLResourceExistsAction
{
    XREA_RETURN,
    XREA_REPLACE,
    XREA_THROW
};

//----------------------------------------------------------------------------//

class CEGUIEXPORT ResourceEventSet : public EventSet
{
public:
    static const String EventNamespace;
    static const String EventResourceCreated;
    static const String EventResourceDestroyed;
    static const String EventResourceReplaced;
};

//----------------------------------------------------------------------------//

template<typename T, typename U>
class NamedXMLResourceManager : public ResourceEventSet
{
public:
    NamedXMLResourceManager(const String& resource_type);

    virtual ~NamedXMLResourceManager();

    T& createFromContainer(const RawDataContainer& source,
                           XMLResourceExistsAction action = XREA_RETURN);

    T& createFromFile(const String& xml_filename, const String& resource_group = "",
                      XMLResourceExistsAction action = XREA_RETURN);

    T& createFromString(const String& source,
                        XMLResourceExistsAction action = XREA_RETURN);

    void destroy(const String& object_name);

    void destroy(const T& object);

    void destroyAll();

    T& get(const String& object_name) const;

    bool isDefined(const String& object_name) const;

    void createAll(const String& pattern, const String& resource_group);

protected:
    // singleton allocator fits here, resource managers are very likely to be singletons
    typedef std::map<String, T*, StringFastLessCompare
        CEGUI_MAP_ALLOC(String, T*)> ObjectRegistry;
    void destroyObject(typename ObjectRegistry::iterator ob);
    T& doExistingObjectAction(const String object_name, T* object,
                              const XMLResourceExistsAction action);
    virtual void doPostObjectAdditionAction(T& object);
    const String d_resourceType;
    ObjectRegistry d_objects;
};

//----------------------------------------------------------------------------//
template<typename T, typename U>
NamedXMLResourceManager<T, U>::NamedXMLResourceManager(
        const String& resource_type) :
    d_resourceType(resource_type)
{
}

//----------------------------------------------------------------------------//
template<typename T, typename U>
NamedXMLResourceManager<T, U>::~NamedXMLResourceManager()
{
}

//----------------------------------------------------------------------------//
template<typename T, typename U>
T& NamedXMLResourceManager<T, U>::createFromContainer(const RawDataContainer& source,
                                                      XMLResourceExistsAction action)
{
    U xml_loader;

    xml_loader.handleContainer(source);
    return doExistingObjectAction(xml_loader.getObjectName(),
                                  &xml_loader.getObject(), action);
}

//----------------------------------------------------------------------------//
template<typename T, typename U>
T& NamedXMLResourceManager<T, U>::createFromFile(const String& xml_filename,
                                                 const String& resource_group,
                                                 XMLResourceExistsAction action)
{
    U xml_loader;

    xml_loader.handleFile(xml_filename, resource_group);
    return doExistingObjectAction(xml_loader.getObjectName(),
                                  &xml_loader.getObject(), action);
}

//----------------------------------------------------------------------------//
template<typename T, typename U>
T& NamedXMLResourceManager<T, U>::createFromString(const String& source,
                                                   XMLResourceExistsAction action)
{
    U xml_loader;

    xml_loader.handleString(source);
    return doExistingObjectAction(xml_loader.getObjectName(),
                                  &xml_loader.getObject(), action);
}

//----------------------------------------------------------------------------//
template<typename T, typename U>
void NamedXMLResourceManager<T, U>::destroy(const String& object_name)
{
    typename ObjectRegistry::iterator i(d_objects.find(object_name));

    // exit if no such object.
    if (i == d_objects.end())
        return;

    destroyObject(i);
}

//----------------------------------------------------------------------------//
template<typename T, typename U>
void NamedXMLResourceManager<T, U>::destroy(const T& object)
{
    // don't want to force a 'getName' function on T here, so we'll look for the
    // object the hard way.
    typename ObjectRegistry::iterator i(d_objects.begin());
    for (; i != d_objects.end(); ++i)
        if (i->second == &object)
        {
            destroyObject(i);
            return;
        }
}

//----------------------------------------------------------------------------//
template<typename T, typename U>
void NamedXMLResourceManager<T, U>::destroyAll()
{
    while (!d_objects.empty())
        destroyObject(d_objects.begin());
}

//----------------------------------------------------------------------------//
template<typename T, typename U>
T& NamedXMLResourceManager<T, U>::get(const String& object_name) const
{
    typename ObjectRegistry::const_iterator i(d_objects.find(object_name));

    if (i == d_objects.end())
        CEGUI_THROW(UnknownObjectException(
            "No object of type '" + d_resourceType + "' named '" + object_name +
            "' is present in the collection."));

    return *i->second;
}

//----------------------------------------------------------------------------//
template<typename T, typename U>
bool NamedXMLResourceManager<T, U>::isDefined(const String& object_name) const
{
    return d_objects.find(object_name) != d_objects.end();
}

//----------------------------------------------------------------------------//
template<typename T, typename U>
void NamedXMLResourceManager<T, U>::destroyObject(
        typename ObjectRegistry::iterator ob)
{
    char addr_buff[32];
    sprintf(addr_buff, "(%p)", static_cast<void*>(ob->second));
    Logger::getSingleton().logEvent("Object of type '" + d_resourceType +
        "' named '" + ob->first + "' has been destroyed. " +
        addr_buff, Informative);

    // Set up event args for event notification
    ResourceEventArgs args(d_resourceType, ob->first);

    CEGUI_DELETE_AO ob->second;
    d_objects.erase(ob);

    // fire event signalling an object has been destroyed
    fireEvent(EventResourceDestroyed, args, EventNamespace);
}

//----------------------------------------------------------------------------//
template<typename T, typename U>
T& NamedXMLResourceManager<T, U>::doExistingObjectAction(
    const String object_name,
    T* object,
    const XMLResourceExistsAction action)
{
    String event_name;

    if (isDefined(object_name))
    {
        switch (action)
        {
        case XREA_RETURN:
            Logger::getSingleton().logEvent("---- Returning existing instance "
                "of " + d_resourceType + " named '" + object_name + "'.");
            // delete any new object we already had created
            CEGUI_DELETE_AO object;
            // return existing instance of object.
            return *d_objects[object_name];

        case XREA_REPLACE:
            Logger::getSingleton().logEvent("---- Replacing existing instance "
                "of " + d_resourceType + " named '" + object_name +
                "' (DANGER!).");
            destroy(object_name);
            event_name = EventResourceReplaced;
            break;

        case XREA_THROW:
            CEGUI_DELETE_AO object;
            CEGUI_THROW(AlreadyExistsException(
                "an object of type '" + d_resourceType + "' named '" +
                object_name + "' already exists in the collection."));

        default:
            CEGUI_DELETE_AO object;
            CEGUI_THROW(InvalidRequestException(
                "Invalid CEGUI::XMLResourceExistsAction was specified."));
        }
    }
    else
        event_name = EventResourceCreated;

    d_objects[object_name] = object;
    doPostObjectAdditionAction(*object);

    // fire event about this resource change
    ResourceEventArgs args(d_resourceType, object_name);
    fireEvent(event_name, args, EventNamespace);

    return *object;
}

//----------------------------------------------------------------------------//
template<typename T, typename U>
void NamedXMLResourceManager<T, U>::doPostObjectAdditionAction(T& /*object*/)
{
    // do nothing by default.
}

//----------------------------------------------------------------------------//
template<typename T, typename U>
void NamedXMLResourceManager<T, U>::createAll(const String& pattern,
                                              const String& resource_group)
{
    std::vector<String> names;
    const size_t num = System::getSingleton().getResourceProvider()->
        getResourceGroupFileNames(names, pattern, resource_group);

    for (size_t i = 0; i < num; ++i)
        createFromFile(names[i], resource_group);
}

//----------------------------------------------------------------------------//

} // End of  CEGUI namespace section

#endif  // end of guard _CEGUINamedXMLResourceManager_h_