include/comphelper/componentmodule.hxx

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19 #ifndef INCLUDED_COMPHELPER_COMPONENTMODULE_HXX
  20 #define INCLUDED_COMPHELPER_COMPONENTMODULE_HXX
  21
  22 #include <comphelper/comphelperdllapi.h>
  23
  24 #include <com/sun/star/lang/XSingleServiceFactory.hpp>
  25 #include <com/sun/star/uno/Sequence.hxx>
  26
  27 #include <cppuhelper/factory.hxx>
  28
  29 #include <osl/mutex.hxx>
  30
  31 #include <rtl/string.hxx>
  32 #include <rtl/instance.hxx>
  33
  34 //........................................................................
  35 namespace comphelper
  36 {
  37 //........................................................................
  38
  39     /** factory factory declaration
  40     */
  41     typedef ::com::sun::star::uno::Reference< ::com::sun::star::lang::XSingleComponentFactory > (SAL_CALL *FactoryInstantiation)
  42     (
  43         ::cppu::ComponentFactoryFunc _pFactoryFunc,
  44         OUString const& _rComponentName,
  45         ::com::sun::star::uno::Sequence< OUString > const & _rServiceNames,
  46         rtl_ModuleCount*
  47     ) SAL_THROW(());
  48
  49     //=========================================================================
  50     //= ComponentDescription
  51     //=========================================================================
  52     struct COMPHELPER_DLLPUBLIC ComponentDescription
  53     {
  54         /// the implementation name of the component
  55         OUString                                     sImplementationName;
  56         /// the services supported by the component implementation
  57         ::com::sun::star::uno::Sequence< OUString >  aSupportedServices;
  58         /** the name under which the component implementation should be registered as singleton,
  59             or empty if the component does not implement a singleton.
  60         */
  61         OUString                                     sSingletonName;
  62         /// the function to create an instance of the component
  63         ::cppu::ComponentFactoryFunc                        pComponentCreationFunc;
  64         /// the function to create a factory for the component (usually <code>::cppu::createSingleComponentFactory</code>)
  65         FactoryInstantiation                                pFactoryCreationFunc;
  66
  67         ComponentDescription()
  68             :sImplementationName()
  69             ,aSupportedServices()
  70             ,sSingletonName()
  71             ,pComponentCreationFunc( NULL )
  72             ,pFactoryCreationFunc( NULL )
  73         {
  74         }
  75
  76         ComponentDescription(
  77                 const OUString& _rImplementationName,
  78                 const ::com::sun::star::uno::Sequence< OUString >& _rSupportedServices,
  79                 const OUString& _rSingletonName,
  80                 ::cppu::ComponentFactoryFunc _pComponentCreationFunc,
  81                 FactoryInstantiation _pFactoryCreationFunc
  82             )
  83             :sImplementationName( _rImplementationName )
  84             ,aSupportedServices( _rSupportedServices )
  85             ,sSingletonName( _rSingletonName )
  86             ,pComponentCreationFunc( _pComponentCreationFunc )
  87             ,pFactoryCreationFunc( _pFactoryCreationFunc )
  88         {
  89         }
  90     };
  91
  92     //=========================================================================
  93     //= OModule
  94     //=========================================================================
  95     class OModuleImpl;
  96     class COMPHELPER_DLLPUBLIC OModule
  97     {
  98     private:
  99         oslInterlockedCount     m_nClients;     /// number of registered clients
 100         OModuleImpl*            m_pImpl;        /// impl class. lives as long as at least one client for the module is registered
 101
 102     protected:
 103         mutable ::osl::Mutex    m_aMutex;       /// access safety
 104
 105     public:
 106         OModule();
 107
 108         virtual ~OModule();
 109
 110         /** register a component implementing a service with the given data.
 111             @param _rImplementationName
 112                 the implementation name of the component
 113             @param _rServiceNames
 114                 the services the component supports
 115             @param _pCreateFunction
 116                 a function for creating an instance of the component
 117             @param _pFactoryFunction
 118                 a function for creating a factory for that component
 119         */
 120         void registerImplementation(
 121             const OUString& _rImplementationName,
 122             const ::com::sun::star::uno::Sequence< OUString >& _rServiceNames,
 123             ::cppu::ComponentFactoryFunc _pCreateFunction,
 124             FactoryInstantiation _pFactoryFunction = ::cppu::createSingleComponentFactory );
 125
 126         /** registers a component given by ComponentDescription
 127         */
 128         void registerImplementation( const ComponentDescription& _rComp );
 129
 130         /** creates a Factory for the component with the given implementation name.
 131             <p>Usually used from within component_getFactory.<p/>
 132             @param _pImplementationName
 133                 the implementation name of the component
 134             @return
 135                 the XInterface access to a factory for the component
 136         */
 137         ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface > getComponentFactory(
 138             const OUString& _rImplementationName );
 139
 140         /** version of getComponentFactory which directly takes the char argument you got in your component_getFactory call
 141         */
 142         void* getComponentFactory( const sal_Char* _pImplementationName );
 143
 144     public:
 145         class ClientAccess { friend class OModuleClient; private: ClientAccess() { } };
 146         /// register a client for the module
 147         void registerClient( ClientAccess );
 148         /// revoke a client for the module
 149         void revokeClient( ClientAccess );
 150
 151     protected:
 152         /** called when the first client has been registered
 153             @precond
 154                 <member>m_aMutex</member> is locked
 155         */
 156         virtual void onFirstClient();
 157
 158         /** called when the last client has been revoked
 159             @precond
 160                 <member>m_aMutex</member> is locked
 161         */
 162         virtual void onLastClient();
 163
 164     private:
 165         OModule( const OModule& );              // never implemented
 166         OModule& operator=( const OModule& );   // never implemented
 167     };
 168
 169     //=========================================================================
 170     //= OModuleClient
 171     //=========================================================================
 172     /** base class for objects which uses any global module-specific resources
 173     */
 174     class COMPHELPER_DLLPUBLIC OModuleClient
 175     {
 176     protected:
 177         OModule&    m_rModule;
 178
 179     public:
 180         OModuleClient( OModule& _rModule ) :m_rModule( _rModule )   { m_rModule.registerClient( OModule::ClientAccess() ); }
 181         ~OModuleClient()                                            { m_rModule.revokeClient( OModule::ClientAccess() ); }
 182     };
 183
 184     //==========================================================================
 185     //= OAutoRegistration
 186     //==========================================================================
 187     template <class TYPE>
 188     class OAutoRegistration
 189     {
 190     public:
 191         /** automatically provides all component information to an OModule instance
 192             <p>Assumed that the template argument has the three methods
 193                 <ul>
 194                     <li><code>static OUString getImplementationName_static()</code><li/>
 195                     <li><code>static ::com::sun::star::uno::Sequence< OUString > getSupportedServiceNames_static()</code><li/>
 196                     <li><code>static ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >
 197                         Create(const ::com::sun::star::uno::Reference< ::com::sun::star::lang::XMultiServiceFactory >&)</code>
 198                         </li>
 199                 <ul/>
 200             the instantiation of this object will automatically register the class via <member>OModule::registerImplementation</member>.
 201             <p/>
 202             The factory creation function used is <code>::cppu::createSingleComponentFactory</code>.
 203         */
 204         OAutoRegistration( OModule& _rModule );
 205     };
 206
 207     template <class TYPE>
 208     OAutoRegistration<TYPE>::OAutoRegistration( OModule& _rModule )
 209     {
 210         _rModule.registerImplementation(
 211             TYPE::getImplementationName_static(),
 212             TYPE::getSupportedServiceNames_static(),
 213             TYPE::Create
 214         );
 215     }
 216
 217     //==========================================================================
 218     //= OSingletonRegistration
 219     //==========================================================================
 220     template <class TYPE>
 221     class OSingletonRegistration
 222     {
 223     public:
 224         /** automatically provides all component information to an OModule instance,
 225             for a singleton component
 226
 227             <p>Assumed that the template argument has the three methods
 228                 <ul>
 229                     <li><code>static OUString getImplementationName_static()</code><li/>
 230                     <li><code>static ::com::sun::star::uno::Sequence< OUString > getSupportedServiceNames_static()</code><li/>
 231                     <li><code>static OUString getSingletonName_static()</code></li>
 232                     <li><code>static ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >
 233                         Create(const ::com::sun::star::uno::Reference< ::com::sun::star::lang::XMultiServiceFactory >&)</code>
 234                         </li>
 235                 <ul/>
 236             the instantiation of this object will automatically register the class via <member>OModule::registerImplementation</member>.
 237             </p>
 238         */
 239         OSingletonRegistration( OModule& _rModule );
 240     };
 241
 242     template <class TYPE>
 243     //--------------------------------------------------------------------------
 244     OSingletonRegistration<TYPE>::OSingletonRegistration( OModule& _rModule )
 245     {
 246         _rModule.registerImplementation( ComponentDescription(
 247             TYPE::getImplementationName_static(),
 248             TYPE::getSupportedServiceNames_static(),
 249             TYPE::getSingletonName_static(),
 250             &TYPE::Create,
 251             &::cppu::createSingleComponentFactory
 252         ) );
 253     }
 254
 255 //........................................................................
 256 } // namespace comphelper
 257 //........................................................................
 258
 259 #endif // INCLUDED_COMPHELPER_COMPONENTMODULE_HXX
 260
 261 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */