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.
00001 /* ========================================================================
00002  * Copyright (C) 2000-2004  Technische Universit� Mnchen
00003  *
00004  * This framework is free software; you can redistribute it and/or modify
00005  * it under the terms of the GNU General Public License as published by
00006  * the Free Software Foundation; either version 2 of the License, or
00007  * (at your option) any later version.
00008  *
00009  * This framework is distributed in the hope that it will be useful,
00010  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00011  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00012  * GNU General Public License for more details.
00013  *
00014  * You should have received a copy of the GNU General Public License
00015  * along with this framework; if not, write to the Free Software
00016  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
00017  *
00018  * For further information please contact the DWARF team at
00019  * <dwarf-gnu@augmentedreality.de>
00020  * ========================================================================
00021  * PROJECT: DWARF
00022  * ======================================================================== */
00023 
00024 /*
00025  * Base class for DWARF services
00026  * TemplateService.h
00027  * Martin Wagner, October 2003
00028  * Distributed Wearable Augmented Reality Framework - www.augmentedreality.de
00029  *
00030  * For documentation and instructions, see the DWARF documentation website at
00031  * http://wwwbruegge.in.tum.de/projects/dwarf/doc/
00032  *
00033  * For further questions about DWARF, please contact us at
00034  * dwarf@augmentedreality.de
00035  * For questions about this particular service, contact
00036  * Martin Wagner <martin@augmentedreality.de>
00037  *
00038  * $Id: TemplateService.h,v 1.7 2006/02/15 17:41:45 pustka Exp $
00039  */
00040 
00041 
00042 /**
00043  * @file TemplateService.h
00044  * @brief The file containing the template service class declaration.
00045  *
00046  * This file contains the TemplateService class declaration.  It is
00047  * responsible for setting up objects for all abilities and needs of
00048  * the service. In addition, it checks whether these objects implement
00049  * the interfaces necessary for the specified connectors.
00050  *
00051  * @author Martin Wagner <martin@augmentedreality.de>
00052  * @ingroup CPPServiceTemplate
00053  */
00054 
00055 
00056 #ifndef __TEMPLATESERVICE_H_
00057 #define __TEMPLATESERVICE_H_
00058 
00059 #include <string>
00060 #include <map>
00061 #include <set>
00062 // defines std::pair
00063 #include <utility>
00064 #include <vector>
00065 
00066 #include <omnithread.h>
00067 
00068 // include the service idl header
00069 #include <DWARF/Service.h>
00070 #include <DWARF/ContextSwitch.h>
00071 
00072 // forward decl
00073 class ContextSwitch;
00074 
00075 /**
00076  * @class TemplateService TemplateService.h "corbainit_cpp/TemplateService.h"
00077  * @brief The class handling service startup and shutdown.
00078  *
00079  * This class is derived from the DWARF::BasicService interface
00080  * and handles service startup and shutdown.
00081  *
00082  * @author Martin Wagner <martin@augmentedreality.de>
00083  * @ingroup CPPServiceTemplate
00084  */
00085 class TemplateService: public POA_DWARF::BasicService {
00086 
00087 public:
00088         /**
00089          * @brief Sets the service's name to "Unknown", the real name
00090          * is set at startService
00091          */
00092         TemplateService();
00093 
00094         /**
00095          * @brief Calls stopService to destroy all ability and need objects
00096          */
00097         virtual ~TemplateService();
00098 
00099 
00100 
00101         // Service interface
00102         /**
00103          * @brief Returns the current status.
00104          */
00105         virtual char * getStatus();
00106 
00107         //SvcStartup interface
00108         /**
00109          * @brief Called by Service Manager on startup.
00110          */
00111         void startService(DWARF::ActiveServiceDescription_ptr serviceDesc);
00112         /**
00113          * @brief Called by Service Manager on shutdown.
00114          */
00115         void stopService(DWARF::ActiveServiceDescription_ptr serviceDesc);
00116 
00117         // Access to abilities, needs and service description
00118         /**
00119          * @brief returns a list with all abilities' names
00120          */
00121         std::vector<std::string>* getAbilities();
00122         /**
00123          * @brief returns a list with all needs' names
00124          */
00125         std::vector<std::string>* getNeeds();
00126         /**
00127          * @brief add a CORBA object registered for ability <name>
00128          */
00129         void addAbility(CORBA::String_var name, CORBA::Object_ptr object);
00130         /**
00131          * @brief returns the CORBA object registered for ability <name>
00132          */
00133         CORBA::Object_var getAbility(std::string name);
00134         /**
00135          * @brief add a CORBA object registered for need <name>
00136          */
00137         void addNeed(CORBA::String_var name, CORBA::Object_ptr object);
00138         /**
00139          * @brief returns the CORBA object registered for need <name>
00140          */
00141         CORBA::Object_var getNeed(std::string name);
00142         /**
00143          * @brief returns this service's description object
00144          */
00145         DWARF::ActiveServiceDescription_ptr getServiceDesc();
00146 
00147         /**
00148          * @brief Blocks the execution until the service is running
00149          *
00150          * This method blocks the execution until startService() is called
00151          * and the thread executing the run() is created.
00152          */
00153         void blockUntilRunning();
00154 
00155         /**
00156          * @brief Blocks the execution until the service has stopped
00157          *
00158          * This method blocks the execution until stopService() is
00159          * called.
00160          */
00161         void blockUntilStopped();
00162 
00163 protected:
00164 
00165         typedef std::map<std::string, CORBA::Object_var> ObjectMap;
00166 
00167 private:
00168         //! A map containing all abilities
00169         ObjectMap m_abilityMap;
00170         //! A map containing all needs
00171         ObjectMap m_needMap;
00172 
00173         omni_mutex m_mutexShouldRun; //!< Mutex for access to m_shouldRun
00174         omni_condition m_signalShouldRun; //!< Condition variable to signal the start of the run() method
00175 
00176 protected:
00177         //! The service's name, set on startService
00178         std::string m_name;
00179 
00180         /**
00181          * @brief State variable containing whether the service should run
00182          *
00183          * This member enables to implement an execution loop in run(). This
00184          * variable is set to false on construction of the service. When
00185          * startService() is called, it will be set to true and the new
00186          * service thread which executes run() is started. If set to false,
00187          * run() should return.
00188          *
00189          * @warning The direct access to this variable is not
00190          * threadsafe. Please use the m_mutexShouldRun mutex variable to ensure
00191          * thread safety. This variable should be private,
00192          * however the interface was defined to allow protected access.
00193          */
00194         volatile bool m_shouldRun;
00195 
00196         //! This service's description object
00197         DWARF::ActiveServiceDescription_ptr m_serviceDesc;
00198 
00199         //! @brief Parse all abilities and set up corresponding objects.
00200         void parseAbilities(DWARF::ActiveServiceDescription_ptr serviceDesc);
00201         /**
00202          * @brief Create an Ability object for a given description.
00203          *
00204          * Create a CORBA object that can corresponds to the ability
00205          * name given in the abilitydescription.
00206          * Override this method for your own service.
00207          * Take care that your method puts the newly created object in
00208          * the m_abilityMap
00209          *
00210          * @param abilityDescr The description of the ability
00211          * @return The created C++ Object_ptr
00212          */
00213         virtual CORBA::Object_ptr createAbilityObject(DWARF::AbilityDescription_ptr abilityDescr)
00214            { return CORBA::Object::_nil(); }
00215 
00216         //! @brief Check whether a given Ability implements all connector protocols.
00217         virtual bool checkAbilityObject(CORBA::Object_ptr ability, DWARF::AbilityDescription_ptr abilityDescr);
00218 
00219         //! @brief Parse all needs and set up corresponding objects.
00220         void parseNeeds(DWARF::ActiveServiceDescription_ptr serviceDesc);
00221         /**
00222          * @brief Create a Need object for a given description.
00223          *
00224          * Create a CORBA object that can corresponds to the need
00225          * name given in the need description.
00226          * Override this method for your own service.
00227          * Take care that your method puts the newly created object in
00228          * the m_needMap
00229          *
00230          * @param needDescr The description of the ability
00231          *
00232          * @return If the Object could be created, it is returned, otherwise NULL is returned.
00233          */
00234         virtual CORBA::Object_ptr createNeedObject(DWARF::NeedDescription_ptr needDescr)
00235            { return CORBA::Object::_nil(); }
00236 
00237         //! @brief Check whether a given Need implements all connector protocols.
00238         virtual bool checkNeedObject(CORBA::Object_ptr need, DWARF::NeedDescription_ptr needDescr);
00239 
00240 
00241         /**
00242          * @brief Sets up ContextSwitch need
00243          *
00244          * This method checks for a need of type ContextSwitch. If it exists,
00245          * it sets up an object of type ContextSwitch and registers it with the
00246          * service manager. This object provides an ObjRef interface of type
00247          * ContextSwitch that allows context estimation components to change this
00248          * service's attributes. If an attribute is changed, set or deleted, this
00249          * service's attributes get adjusted accordingly. Thus, all abilities not
00250          * overriding the contextual attribute have this attribute set, too. In
00251          * addition, the predicates of all needs with attribute "ContextAffected"
00252          * set to "true" are adjusted such that they require the contextual attribute.
00253          * For example, if a need's predicate was (AnimalType=Sheep) before a call
00254          * changeContextAttribute( "AnimalType", "Cow" ); was received, it will be
00255          * (AnimalType=Cow) afterwards. If a call setContextAttribute( "User", "Joe");
00256          * is received, the new value of the predicate will be
00257          * (&(User=Joe)(AnimalType=Cow)).
00258          *
00259          * @param serviceDesc This service's service description
00260          */
00261         void checkContextSwitch(DWARF::ActiveServiceDescription_ptr serviceDesc);
00262 
00263         /**
00264          * @brief Method to provide a ContextSwitch object
00265          *
00266          * Override this method to change the default behavior that is
00267          * described with the ContextSwitch class
00268          *
00269          * @param needDescr the need description
00270          * @param ServiceDescr This service's service description
00271          *
00272          * @return A CORBA object that can be registered with the service manager.
00273          */
00274         virtual CORBA::Object_ptr createContextSwitchObject( DWARF::NeedDescription_ptr needDescr,
00275                 DWARF::ActiveServiceDescription_ptr serviceDesc );
00276 
00277         //! @brief Calls the run() method of the given controller object.
00278         static void* controlThreadStarter(void* data);
00279 
00280         /**
00281          * @brief The ccre method of the service. Started in a separate thread
00282          *        Once this method returns, this thread is terminated.
00283          *
00284          * The default implementation returns immediately.
00285          * Use this method as the central workhorse of your
00286          * service. First, initailize everything that's needed, then do some
00287          * more or less useful work and finally return when m_shouldRun is
00288          * set to false or some other conditions occurr.
00289          */
00290         virtual void run();
00291 
00292         /**
00293          * @brief Returns whether the service is running
00294          *
00295          * This method returns the value of m_shouldRun which indicates
00296          * if startService() was called and the service is running
00297          *
00298          * @return True if the service is running, else false
00299          */
00300         bool shouldRun();
00301 
00302         /**
00303          * @brief Return a reference to the ability map
00304          *
00305          * @return Constant reference to the ability map
00306          */
00307         const ObjectMap& getAbilityMap() const {return m_abilityMap;}
00308 
00309 
00310         /**
00311          * @brief Return a reference to the need map
00312          *
00313          * @return Constant reference to the need map
00314          */
00315         const ObjectMap& getNeedMap() const {return m_needMap;}
00316 
00317 };
00318 
00319 
00320 /**
00321  * @class ContextNotification
00322  * @brief Abstract interface for needs and abilities wanting to get notified of context changes
00323  *
00324  * Implement this interface in your need or ability class to get notified
00325  * whenever the context of the service gets changed.
00326  *
00327  * @author Martin Wagner <martin@augmentedreality.de>
00328  * @ingroup CPPServiceTemplate
00329  */
00330 class ContextNotification
00331 {
00332 public:
00333         /**
00334          * @brief this method gets called if a context attribute is changed
00335          */
00336         virtual void notifyContextChange( const char *attrName, const char *attrVal )=0;
00337 };
00338 
00339 #endif  //__TEMPLATESERVICE_H_
00340 
00341 

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