comphelper/inc/comphelper/componentmodule.hxx

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: componentmodule.hxx,v $
  10  * $Revision: 1.7 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30 #ifndef COMPHELPER_INC_COMPHELPER_COMPONENTMODULE_HXX
  31 #define COMPHELPER_INC_COMPHELPER_COMPONENTMODULE_HXX
  32
  33 #include <comphelper/comphelperdllapi.h>
  34 #include <comphelper/legacysingletonfactory.hxx>
  35
  36 /** === begin UNO includes === **/
  37 #include <com/sun/star/lang/XMultiServiceFactory.hpp>
  38 #include <com/sun/star/lang/XSingleServiceFactory.hpp>
  39 #include <com/sun/star/uno/Sequence.hxx>
  40 #include <com/sun/star/registry/XRegistryKey.hpp>
  41 /** === end UNO includes === **/
  42
  43 #include <cppuhelper/factory.hxx>
  44
  45 #include <osl/mutex.hxx>
  46
  47 #include <rtl/string.hxx>
  48 #include <rtl/instance.hxx>
  49
  50 //........................................................................
  51 namespace comphelper
  52 {
  53 //........................................................................
  54
  55     /** factory factory declaration
  56     */
  57     typedef ::com::sun::star::uno::Reference< ::com::sun::star::lang::XSingleComponentFactory > (SAL_CALL *FactoryInstantiation)
  58     (
  59         ::cppu::ComponentFactoryFunc _pFactoryFunc,
  60         ::rtl::OUString const& _rComponentName,
  61         ::com::sun::star::uno::Sequence< ::rtl::OUString > const & _rServiceNames,
  62         rtl_ModuleCount* _pModuleCounter
  63     ) SAL_THROW(());
  64
  65     //=========================================================================
  66     //= ComponentDescription
  67     //=========================================================================
  68     struct COMPHELPER_DLLPUBLIC ComponentDescription
  69     {
  70         /// the implementation name of the component
  71         ::rtl::OUString                                     sImplementationName;
  72         /// the services supported by the component implementation
  73         ::com::sun::star::uno::Sequence< ::rtl::OUString >  aSupportedServices;
  74         /** the name under which the component implementation should be registered as singleton,
  75             or empty if the component does not implement a singleton.
  76         */
  77         ::rtl::OUString                                     sSingletonName;
  78         /// the function to create an instance of the component
  79         ::cppu::ComponentFactoryFunc                        pComponentCreationFunc;
  80         /// the function to create a factory for the component (usually <code>::cppu::createSingleComponentFactory</code>)
  81         FactoryInstantiation                                pFactoryCreationFunc;
  82
  83         ComponentDescription()
  84             :sImplementationName()
  85             ,aSupportedServices()
  86             ,sSingletonName()
  87             ,pComponentCreationFunc( NULL )
  88             ,pFactoryCreationFunc( NULL )
  89         {
  90         }
  91
  92         ComponentDescription(
  93                 const ::rtl::OUString& _rImplementationName,
  94                 const ::com::sun::star::uno::Sequence< ::rtl::OUString >& _rSupportedServices,
  95                 const ::rtl::OUString& _rSingletonName,
  96                 ::cppu::ComponentFactoryFunc _pComponentCreationFunc,
  97                 FactoryInstantiation _pFactoryCreationFunc
  98             )
  99             :sImplementationName( _rImplementationName )
 100             ,aSupportedServices( _rSupportedServices )
 101             ,sSingletonName( _rSingletonName )
 102             ,pComponentCreationFunc( _pComponentCreationFunc )
 103             ,pFactoryCreationFunc( _pFactoryCreationFunc )
 104         {
 105         }
 106     };
 107
 108     //=========================================================================
 109     //= OModule
 110     //=========================================================================
 111     class OModuleImpl;
 112     class COMPHELPER_DLLPUBLIC OModule
 113     {
 114     private:
 115         oslInterlockedCount     m_nClients;     /// number of registered clients
 116         OModuleImpl*            m_pImpl;        /// impl class. lives as long as at least one client for the module is registered
 117
 118     protected:
 119         mutable ::osl::Mutex    m_aMutex;       /// access safety
 120
 121     public:
 122         OModule();
 123
 124         virtual ~OModule();
 125
 126         /** register a component implementing a service with the given data.
 127             @param _rImplementationName
 128                 the implementation name of the component
 129             @param _rServiceNames
 130                 the services the component supports
 131             @param _pCreateFunction
 132                 a function for creating an instance of the component
 133             @param _pFactoryFunction
 134                 a function for creating a factory for that component
 135         */
 136         void registerImplementation(
 137             const ::rtl::OUString& _rImplementationName,
 138             const ::com::sun::star::uno::Sequence< ::rtl::OUString >& _rServiceNames,
 139             ::cppu::ComponentFactoryFunc _pCreateFunction,
 140             FactoryInstantiation _pFactoryFunction = ::cppu::createSingleComponentFactory );
 141
 142         /** registers a component given by <type>ComponentDescription</type>
 143         */
 144         void registerImplementation( const ComponentDescription& _rComp );
 145
 146         /** write the registration information of all known components
 147
 148             Writes the registration information of all components which are currently registered into the
 149             specified registry.
 150
 151             Usually used from within component_writeInfo.
 152
 153             @param_rxServiceManager
 154                 the service manager
 155             @param _rRootKey
 156                 the registry key under which the information will be stored
 157             @return
 158                 <TRUE/> if the registration of all implementations was successfull, <FALSE/> otherwise
 159         */
 160         sal_Bool writeComponentInfos(
 161             const ::com::sun::star::uno::Reference< ::com::sun::star::lang::XMultiServiceFactory >& _rxServiceManager,
 162             const ::com::sun::star::uno::Reference< ::com::sun::star::registry::XRegistryKey >& _rRootKey);
 163
 164         /** version of writeComponentInfos which directly takes the arguments you got in your component_writeInfo call
 165         */
 166         sal_Bool writeComponentInfos( void* pServiceManager, void* pRegistryKey );
 167
 168         /** creates a Factory for the component with the given implementation name.
 169             <p>Usually used from within component_getFactory.<p/>
 170             @param _rxServiceManager
 171                 a pointer to an XMultiServiceFactory interface as got in component_getFactory
 172             @param _pImplementationName
 173                 the implementation name of the component
 174             @return
 175                 the XInterface access to a factory for the component
 176         */
 177         ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface > getComponentFactory(
 178             const ::rtl::OUString& _rImplementationName,
 179             const ::com::sun::star::uno::Reference< ::com::sun::star::lang::XMultiServiceFactory >& _rxServiceManager
 180         );
 181
 182         /** version of getComponentFactory which directly takes the arguments you got in your component_getFactory call
 183         */
 184         void* getComponentFactory(
 185             const sal_Char* _pImplementationName, void* _pServiceManager, void* _pRegistryKey
 186         );
 187
 188     public:
 189         class ClientAccess { friend class OModuleClient; private: ClientAccess() { } };
 190         /// register a client for the module
 191         void registerClient( ClientAccess );
 192         /// revoke a client for the module
 193         void revokeClient( ClientAccess );
 194
 195     protected:
 196         /** called when the first client has been registered
 197             @precond
 198                 <member>m_aMutex</member> is locked
 199         */
 200         virtual void onFirstClient();
 201
 202         /** called when the last client has been revoked
 203             @precond
 204                 <member>m_aMutex</member> is locked
 205         */
 206         virtual void onLastClient();
 207
 208     private:
 209         OModule( const OModule& );              // never implemented
 210         OModule& operator=( const OModule& );   // never implemented
 211     };
 212
 213     //=========================================================================
 214     //= OModuleClient
 215     //=========================================================================
 216     /** base class for objects which uses any global module-specific ressources
 217     */
 218     class COMPHELPER_DLLPUBLIC OModuleClient
 219     {
 220     protected:
 221         OModule&    m_rModule;
 222
 223     public:
 224         OModuleClient( OModule& _rModule ) :m_rModule( _rModule )   { m_rModule.registerClient( OModule::ClientAccess() ); }
 225         ~OModuleClient()                                            { m_rModule.revokeClient( OModule::ClientAccess() ); }
 226     };
 227
 228     //==========================================================================
 229     //= OAutoRegistration
 230     //==========================================================================
 231     template <class TYPE>
 232     class OAutoRegistration
 233     {
 234     public:
 235         /** automatically provides all component information to an OModule instance
 236             <p>Assumed that the template argument has the three methods
 237                 <ul>
 238                     <li><code>static ::rtl::OUString getImplementationName_static()</code><li/>
 239                     <li><code>static ::com::sun::star::uno::Sequence< ::rtl::OUString > getSupportedServiceNames_static()</code><li/>
 240                     <li><code>static ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >
 241                         Create(const ::com::sun::star::uno::Reference< ::com::sun::star::lang::XMultiServiceFactory >&)</code>
 242                         </li>
 243                 <ul/>
 244             the instantiation of this object will automatically register the class via <member>OModule::registerImplementation</member>.
 245             <p/>
 246             The factory creation function used is <code>::cppu::createSingleComponentFactory</code>.
 247         */
 248         OAutoRegistration( OModule& _rModule );
 249     };
 250
 251     template <class TYPE>
 252     OAutoRegistration<TYPE>::OAutoRegistration( OModule& _rModule )
 253     {
 254         _rModule.registerImplementation(
 255             TYPE::getImplementationName_static(),
 256             TYPE::getSupportedServiceNames_static(),
 257             TYPE::Create
 258         );
 259     }
 260
 261     //==========================================================================
 262     //= OSingletonRegistration
 263     //==========================================================================
 264     template <class TYPE>
 265     class OSingletonRegistration
 266     {
 267     public:
 268         /** automatically provides all component information to an OModule instance,
 269             for a singleton component
 270
 271             <p>Assumed that the template argument has the three methods
 272                 <ul>
 273                     <li><code>static ::rtl::OUString getImplementationName_static()</code><li/>
 274                     <li><code>static ::com::sun::star::uno::Sequence< ::rtl::OUString > getSupportedServiceNames_static()</code><li/>
 275                     <li><code>static ::rtl::OUString getSingletonName_static()</code></li>
 276                     <li><code>static ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >
 277                         Create(const ::com::sun::star::uno::Reference< ::com::sun::star::lang::XMultiServiceFactory >&)</code>
 278                         </li>
 279                 <ul/>
 280             the instantiation of this object will automatically register the class via <member>OModule::registerImplementation</member>.
 281             </p>
 282         */
 283         OSingletonRegistration( OModule& _rModule );
 284     };
 285
 286     template <class TYPE>
 287     //--------------------------------------------------------------------------
 288     OSingletonRegistration<TYPE>::OSingletonRegistration( OModule& _rModule )
 289     {
 290         _rModule.registerImplementation( ComponentDescription(
 291             TYPE::getImplementationName_static(),
 292             TYPE::getSupportedServiceNames_static(),
 293             TYPE::getSingletonName_static(),
 294             &TYPE::Create,
 295             &::cppu::createSingleComponentFactory
 296         ) );
 297     }
 298
 299     //==========================================================================
 300     //= OLegacySingletonRegistration
 301     //==========================================================================
 302     template <class TYPE>
 303     class OLegacySingletonRegistration
 304     {
 305     public:
 306         OLegacySingletonRegistration( OModule& _rModule );
 307     };
 308
 309     //--------------------------------------------------------------------------
 310     template <class TYPE>
 311     OLegacySingletonRegistration<TYPE>::OLegacySingletonRegistration( OModule& _rModule )
 312     {
 313         _rModule.registerImplementation( ComponentDescription(
 314             TYPE::getImplementationName_static(),
 315             TYPE::getSupportedServiceNames_static(),
 316             ::rtl::OUString(),
 317             &TYPE::Create,
 318             &::comphelper::createLegacySingletonFactory
 319         ) );
 320     }
 321
 322     //==========================================================================
 323     //= helpers
 324     //==========================================================================
 325
 326     //==========================================================================
 327     // declaring a OModule for a component library
 328
 329 #define DECLARE_COMPONENT_MODULE( ModuleClass, ClientClass ) \
 330     /* -------------------------------------------------------------------- */ \
 331     class ModuleClass : public ::comphelper::OModule \
 332     { \
 333         friend struct CreateModuleClass; \
 334         typedef ::comphelper::OModule BaseClass; \
 335     \
 336     public: \
 337         static ModuleClass& getInstance(); \
 338     \
 339     private: \
 340         ModuleClass(); \
 341     }; \
 342     \
 343     /* -------------------------------------------------------------------- */ \
 344     class ClientClass : public ::comphelper::OModuleClient \
 345     { \
 346     private: \
 347         typedef ::comphelper::OModuleClient BaseClass; \
 348     \
 349     public: \
 350         ClientClass() : BaseClass( ModuleClass::getInstance() ) \
 351         { \
 352         } \
 353     }; \
 354     \
 355     /* -------------------------------------------------------------------- */ \
 356     template < class TYPE > \
 357     class OAutoRegistration : public ::comphelper::OAutoRegistration< TYPE > \
 358     { \
 359     private: \
 360         typedef ::comphelper::OAutoRegistration< TYPE >    BaseClass; \
 361     \
 362     public: \
 363         OAutoRegistration() : BaseClass( ModuleClass::getInstance() ) \
 364         { \
 365         } \
 366     }; \
 367     /* -------------------------------------------------------------------- */ \
 368     template < class TYPE > \
 369     class OSingletonRegistration : public ::comphelper::OSingletonRegistration< TYPE > \
 370     { \
 371     private: \
 372         typedef ::comphelper::OSingletonRegistration< TYPE >    BaseClass; \
 373     \
 374     public: \
 375         OSingletonRegistration() : BaseClass( ModuleClass::getInstance() ) \
 376         { \
 377         } \
 378     }; \
 379     /* -------------------------------------------------------------------- */ \
 380     template < class TYPE > \
 381     class OLegacySingletonRegistration : public ::comphelper::OLegacySingletonRegistration< TYPE > \
 382     { \
 383     private: \
 384         typedef ::comphelper::OLegacySingletonRegistration< TYPE >  BaseClass; \
 385     \
 386     public: \
 387         OLegacySingletonRegistration() : BaseClass( ModuleClass::getInstance() ) \
 388         { \
 389         } \
 390     }; \
 391
 392     //==========================================================================
 393     //= implementing a OModule for a component library
 394
 395 #define IMPLEMENT_COMPONENT_MODULE( ModuleClass ) \
 396     struct CreateModuleClass \
 397     { \
 398         ModuleClass* operator()() \
 399         { \
 400             static ModuleClass* pModule = new ModuleClass; \
 401             return pModule; \
 402         } \
 403     }; \
 404     \
 405     ModuleClass::ModuleClass() \
 406         :BaseClass() \
 407     { \
 408     } \
 409     \
 410     ModuleClass& ModuleClass::getInstance() \
 411     { \
 412         return *rtl_Instance< ModuleClass, CreateModuleClass, ::osl::MutexGuard, ::osl::GetGlobalMutex >:: \
 413             create( CreateModuleClass(), ::osl::GetGlobalMutex() ); \
 414     } \
 415
 416     //==========================================================================
 417     //= implementing the API of a component library (component_*)
 418
 419 #define IMPLEMENT_COMPONENT_LIBRARY_API( module_class, initializer_function )   \
 420     extern "C" SAL_DLLPUBLIC_EXPORT void SAL_CALL \
 421     component_getImplementationEnvironment(    \
 422         const sal_Char **ppEnvTypeName, uno_Environment ** /*ppEnv*/ )  \
 423     {   \
 424         *ppEnvTypeName = CPPU_CURRENT_LANGUAGE_BINDING_NAME;    \
 425     }   \
 426     extern "C" SAL_DLLPUBLIC_EXPORT sal_Bool SAL_CALL component_writeInfo( \
 427         void* pServiceManager, void* pRegistryKey ) \
 428     {   \
 429         initializer_function(); \
 430         return module_class::getInstance().writeComponentInfos( pServiceManager, pRegistryKey );  \
 431     }   \
 432     extern "C" SAL_DLLPUBLIC_EXPORT void* SAL_CALL component_getFactory( \
 433         const sal_Char* pImplementationName, void* pServiceManager, void* pRegistryKey ) \
 434     { \
 435         initializer_function(); \
 436         return module_class::getInstance().getComponentFactory( pImplementationName, pServiceManager, pRegistryKey );   \
 437     }
 438
 439 //........................................................................
 440 } // namespace comphelper
 441 //........................................................................
 442
 443 #endif // COMPHELPER_INC_COMPHELPER_COMPONENTMODULE_HXX
 444