div class="twikiTopBar">

Chair for Computer Aided Medical Procedures & Augmented Reality Lehrstuhl für Informatikanwendungen in der Medizin & Augmented Reality

TemplateService.h

Go to the documentation of this file.

/* ========================================================================
 * Copyright (C) 2000-2004  Technische Universit� Mnchen
 *
 * This framework is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * This framework is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this framework; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 *
 * For further information please contact the DWARF team at
 * <dwarf-gnu@augmentedreality.de>
 * ========================================================================
 * PROJECT: DWARF
 * ======================================================================== */

/*
 * Base class for DWARF services
 * TemplateService.h
 * Martin Wagner, October 2003
 * Distributed Wearable Augmented Reality Framework - www.augmentedreality.de
 *
 * For documentation and instructions, see the DWARF documentation website at
 * http://wwwbruegge.in.tum.de/projects/dwarf/doc/
 *
 * For further questions about DWARF, please contact us at
 * dwarf@augmentedreality.de
 * For questions about this particular service, contact
 * Martin Wagner <martin@augmentedreality.de>
 *
 * $Id: TemplateService.h,v 1.7 2006/02/15 17:41:45 pustka Exp $
 */


/**
 * @file TemplateService.h
 * @brief The file containing the template service class declaration.
 *
 * This file contains the TemplateService class declaration.  It is
 * responsible for setting up objects for all abilities and needs of
 * the service. In addition, it checks whether these objects implement
 * the interfaces necessary for the specified connectors.
 *
 * @author Martin Wagner <martin@augmentedreality.de>
 * @ingroup CPPServiceTemplate
 */


#ifndef __TEMPLATESERVICE_H_
#define __TEMPLATESERVICE_H_

#include <string>
#include <map>
#include <set>
// defines std::pair
#include <utility>
#include <vector>

#include <omnithread.h>

// include the service idl header
#include <DWARF/Service.h>
#include <DWARF/ContextSwitch.h>

// forward decl
class ContextSwitch;

/**
 * @class TemplateService TemplateService.h "corbainit_cpp/TemplateService.h"
 * @brief The class handling service startup and shutdown.
 *
 * This class is derived from the DWARF::BasicService interface
 * and handles service startup and shutdown.
 *
 * @author Martin Wagner <martin@augmentedreality.de>
 * @ingroup CPPServiceTemplate
 */
class TemplateService: public POA_DWARF::BasicService {

public:
        /**
         * @brief Sets the service's name to "Unknown", the real name
         * is set at startService
         */
        TemplateService();

        /**
         * @brief Calls stopService to destroy all ability and need objects
         */
        virtual ~TemplateService();



        // Service interface
        /**
         * @brief Returns the current status.
         */
        virtual char * getStatus();

        //SvcStartup interface
        /**
         * @brief Called by Service Manager on startup.
         */
        void startService(DWARF::ActiveServiceDescription_ptr serviceDesc);
        /**
         * @brief Called by Service Manager on shutdown.
         */
        void stopService(DWARF::ActiveServiceDescription_ptr serviceDesc);

        // Access to abilities, needs and service description
        /**
         * @brief returns a list with all abilities' names
         */
        std::vector<std::string>* getAbilities();
        /**
         * @brief returns a list with all needs' names
         */
        std::vector<std::string>* getNeeds();
        /**
         * @brief add a CORBA object registered for ability <name>
         */
        void addAbility(CORBA::String_var name, CORBA::Object_ptr object);
        /**
         * @brief returns the CORBA object registered for ability <name>
         */
        CORBA::Object_var getAbility(std::string name);
        /**
         * @brief add a CORBA object registered for need <name>
         */
        void addNeed(CORBA::String_var name, CORBA::Object_ptr object);
        /**
         * @brief returns the CORBA object registered for need <name>
         */
        CORBA::Object_var getNeed(std::string name);
        /**
         * @brief returns this service's description object
         */
        DWARF::ActiveServiceDescription_ptr getServiceDesc();

        /**
         * @brief Blocks the execution until the service is running
         *
         * This method blocks the execution until startService() is called
         * and the thread executing the run() is created.
         */
        void blockUntilRunning();

        /**
         * @brief Blocks the execution until the service has stopped
         *
         * This method blocks the execution until stopService() is
         * called.
         */
        void blockUntilStopped();

protected:

        typedef std::map<std::string, CORBA::Object_var> ObjectMap;

private:
        //! A map containing all abilities
        ObjectMap m_abilityMap;
        //! A map containing all needs
        ObjectMap m_needMap;

        omni_mutex m_mutexShouldRun; //!< Mutex for access to m_shouldRun
        omni_condition m_signalShouldRun; //!< Condition variable to signal the start of the run() method

protected:
        //! The service's name, set on startService
        std::string m_name;

        /**
         * @brief State variable containing whether the service should run
         *
         * This member enables to implement an execution loop in run(). This
         * variable is set to false on construction of the service. When
         * startService() is called, it will be set to true and the new
         * service thread which executes run() is started. If set to false,
         * run() should return.
         *
         * @warning The direct access to this variable is not
         * threadsafe. Please use the m_mutexShouldRun mutex variable to ensure
         * thread safety. This variable should be private,
         * however the interface was defined to allow protected access.
         */
        volatile bool m_shouldRun;

        //! This service's description object
        DWARF::ActiveServiceDescription_ptr m_serviceDesc;

        //! @brief Parse all abilities and set up corresponding objects.
        void parseAbilities(DWARF::ActiveServiceDescription_ptr serviceDesc);
        /**
         * @brief Create an Ability object for a given description.
         *
         * Create a CORBA object that can corresponds to the ability
         * name given in the abilitydescription.
         * Override this method for your own service.
         * Take care that your method puts the newly created object in
         * the m_abilityMap
         *
         * @param abilityDescr The description of the ability
         * @return The created C++ Object_ptr
         */
        virtual CORBA::Object_ptr createAbilityObject(DWARF::AbilityDescription_ptr abilityDescr)
           { return CORBA::Object::_nil(); }

        //! @brief Check whether a given Ability implements all connector protocols.
        virtual bool checkAbilityObject(CORBA::Object_ptr ability, DWARF::AbilityDescription_ptr abilityDescr);

        //! @brief Parse all needs and set up corresponding objects.
        void parseNeeds(DWARF::ActiveServiceDescription_ptr serviceDesc);
        /**
         * @brief Create a Need object for a given description.
         *
         * Create a CORBA object that can corresponds to the need
         * name given in the need description.
         * Override this method for your own service.
         * Take care that your method puts the newly created object in
         * the m_needMap
         *
         * @param needDescr The description of the ability
         *
         * @return If the Object could be created, it is returned, otherwise NULL is returned.
         */
        virtual CORBA::Object_ptr createNeedObject(DWARF::NeedDescription_ptr needDescr)
           { return CORBA::Object::_nil(); }

        //! @brief Check whether a given Need implements all connector protocols.
        virtual bool checkNeedObject(CORBA::Object_ptr need, DWARF::NeedDescription_ptr needDescr);


        /**
         * @brief Sets up ContextSwitch need
         *
         * This method checks for a need of type ContextSwitch. If it exists,
         * it sets up an object of type ContextSwitch and registers it with the
         * service manager. This object provides an ObjRef interface of type
         * ContextSwitch that allows context estimation components to change this
         * service's attributes. If an attribute is changed, set or deleted, this
         * service's attributes get adjusted accordingly. Thus, all abilities not
         * overriding the contextual attribute have this attribute set, too. In
         * addition, the predicates of all needs with attribute "ContextAffected"
         * set to "true" are adjusted such that they require the contextual attribute.
         * For example, if a need's predicate was (AnimalType=Sheep) before a call
         * changeContextAttribute( "AnimalType", "Cow" ); was received, it will be
         * (AnimalType=Cow) afterwards. If a call setContextAttribute( "User", "Joe");
         * is received, the new value of the predicate will be
         * (&(User=Joe)(AnimalType=Cow)).
         *
         * @param serviceDesc This service's service description
         */
        void checkContextSwitch(DWARF::ActiveServiceDescription_ptr serviceDesc);

        /**
         * @brief Method to provide a ContextSwitch object
         *
         * Override this method to change the default behavior that is
         * described with the ContextSwitch class
         *
         * @param needDescr the need description
         * @param ServiceDescr This service's service description
         *
         * @return A CORBA object that can be registered with the service manager.
         */
        virtual CORBA::Object_ptr createContextSwitchObject( DWARF::NeedDescription_ptr needDescr,
                DWARF::ActiveServiceDescription_ptr serviceDesc );

        //! @brief Calls the run() method of the given controller object.
        static void* controlThreadStarter(void* data);

        /**
         * @brief The ccre method of the service. Started in a separate thread
         *        Once this method returns, this thread is terminated.
         *
         * The default implementation returns immediately.
         * Use this method as the central workhorse of your
         * service. First, initailize everything that's needed, then do some
         * more or less useful work and finally return when m_shouldRun is
         * set to false or some other conditions occurr.
         */
        virtual void run();

        /**
         * @brief Returns whether the service is running
         *
         * This method returns the value of m_shouldRun which indicates
         * if startService() was called and the service is running
         *
         * @return True if the service is running, else false
         */
        bool shouldRun();

        /**
         * @brief Return a reference to the ability map
         *
         * @return Constant reference to the ability map
         */
        const ObjectMap& getAbilityMap() const {return m_abilityMap;}


        /**
         * @brief Return a reference to the need map
         *
         * @return Constant reference to the need map
         */
        const ObjectMap& getNeedMap() const {return m_needMap;}

};


/**
 * @class ContextNotification
 * @brief Abstract interface for needs and abilities wanting to get notified of context changes
 *
 * Implement this interface in your need or ability class to get notified
 * whenever the context of the service gets changed.
 *
 * @author Martin Wagner <martin@augmentedreality.de>
 * @ingroup CPPServiceTemplate
 */
class ContextNotification
{
public:
        /**
         * @brief this method gets called if a context attribute is changed
         */
        virtual void notifyContextChange( const char *attrName, const char *attrVal )=0;
};

#endif  //__TEMPLATESERVICE_H_

TemplateService.h Source File | generated on Sun Apr 29 02:01:05 2007 by Doxygen 1.4.1 for DWARF