framework/inc/services/detectorfactory.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: detectorfactory.hxx,v $
  10  * $Revision: 1.4 $
  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
  31 #ifndef __FRAMEWORK_SERVICES_DETECTORFACTORY_HXX_
  32 #define __FRAMEWORK_SERVICES_DETECTORFACTORY_HXX_
  33
  34 //_______________________________________________
  35 // includes of own project
  36
  37 #include <classes/filtercache.hxx>
  38 #include <threadhelp/threadhelpbase.hxx>
  39 #include <macros/xinterface.hxx>
  40 #include <macros/xtypeprovider.hxx>
  41 #include <macros/xserviceinfo.hxx>
  42 #include <macros/generic.hxx>
  43 #include <macros/debug.hxx>
  44 #include <general.h>
  45
  46 //_______________________________________________
  47 // includes of interfaces
  48 #include <com/sun/star/beans/PropertyValue.hpp>
  49 #include <com/sun/star/lang/XInitialization.hpp>
  50 #include <com/sun/star/lang/WrappedTargetException.hpp>
  51 #include <com/sun/star/lang/IllegalArgumentException.hpp>
  52 #include <com/sun/star/container/ElementExistException.hpp>
  53 #include <com/sun/star/container/NoSuchElementException.hpp>
  54 #include <com/sun/star/container/XNameContainer.hpp>
  55 #include <com/sun/star/container/NoSuchElementException.hpp>
  56 #include <com/sun/star/io/XInputStream.hpp>
  57 #include <com/sun/star/util/XFlushable.hpp>
  58
  59 //_______________________________________________
  60 // includes of other projects
  61 #include <cppuhelper/interfacecontainer.hxx>
  62 #include <cppuhelper/weak.hxx>
  63
  64 //_______________________________________________
  65 // namespace
  66
  67 namespace framework{
  68
  69 //_______________________________________________
  70 // exported const
  71
  72 //_______________________________________________
  73 // exported definitions
  74
  75 /// @HTML
  76 /** @short      factory to create detect service objects and initialize it in the right way.
  77
  78     @descr      This class can be used to create new detect services for specified contents.
  79                 It uses cached values of the configuration to lay down, which detector match
  80                 a given name. Further this class provides full access to the configuration data
  81                 of such detect services and following implementations will support some special
  82                 query modes.
  83
  84     @author     as96863
  85
  86     @docdate    07.03.2003 by as96863
  87
  88     @todo       <ul>
  89                     <li>implementation of query mode</li>
  90                     <li>simple restore mechanism of last consistent cache state,
  91                         if flush failed</li>
  92                 </ul>
  93  */
  94 /// @NOHTML
  95
  96 class DetectorFactory : // interfaces
  97                         public  css::lang::XTypeProvider                        ,
  98                         public  css::lang::XServiceInfo                         ,
  99                         public  css::lang::XMultiServiceFactory         ,
 100                         public  css::container::XNameContainer          ,               // => XNameReplace => XNameAccess => XElementAccess
 101                         public  css::util::XFlushable                           ,
 102                         // base classes
 103                         // Order is neccessary for right initialization of it!
 104                         private ThreadHelpBase                      ,
 105                         public  ::cppu::OWeakObject
 106 {
 107     //-------------------------------------------
 108     // member
 109
 110     private:
 111
 112         /** reference to the global uno service manager.
 113             It will be used to create own needed services on demand. */
 114         css::uno::Reference< css::lang::XMultiServiceFactory > m_xSMGR;
 115
 116         /** singleton, which contains all needed configuration data and provides
 117             read/write access on it. */
 118         FilterCache m_aCache;
 119
 120         /** contains all registered listener. */
 121         ::cppu::OMultiTypeInterfaceContainerHelper m_aListenerContainer;
 122
 123     //-------------------------------------------
 124     // interface
 125
 126     public:
 127
 128         //---------------------------------------
 129         // XInterface, XTypeProvider, XServiceInfo
 130
 131         DECLARE_XINTERFACE
 132         DECLARE_XTYPEPROVIDER
 133         DECLARE_XSERVICEINFO
 134
 135         #ifdef ENABLE_AUTODOC_FIX
 136         ;
 137         #endif
 138
 139         //---------------------------------------
 140
 141         /** @short  initialize new instance of this class.
 142
 143             @param  xSMGR
 144                     reference to the global uno service manager, which created this new factory instance.
 145                     It must be used during runtime to create own needed services.
 146          */
 147
 148         DetectorFactory( const css::uno::Reference< css::lang::XMultiServiceFactory >& xSMGR );
 149
 150         //---------------------------------------
 151
 152         /** @short  release internal structures.
 153          */
 154
 155         virtual ~DetectorFactory();
 156
 157         //---------------------------------------
 158         // XMultiServiceFactory
 159
 160         /** @short  create a new detect service and initialize it with it's own configuration data.
 161
 162             @param  sName
 163                     means the uno implementation name of a detect service.
 164
 165             @exception  com::sun::star::uno::Exception
 166                         if the requested service could not be created or initialized.
 167          */
 168
 169         virtual css::uno::Reference< css::uno::XInterface > SAL_CALL createInstance( const ::rtl::OUString& sName )
 170             throw(css::uno::Exception       ,
 171                   css::uno::RuntimeException);
 172
 173         //---------------------------------------
 174         // XMultiServiceFactory
 175
 176         /** @short  does the same as createInstance() method, but initialize created detect service with some
 177                     additional data.
 178
 179             @param  sName
 180                     means the uno implementation name of a detect service.
 181
 182             @param  lArguments
 183                     the optional arguments, which are passed to the created detect service against
 184                     it's own configuration data.
 185
 186             @exception  com::sun::star::uno::Exception
 187                         if the requested service could not be created or initialized.
 188          */
 189
 190         virtual css::uno::Reference< css::uno::XInterface > SAL_CALL createInstanceWithArguments( const ::rtl::OUString&                     sName      ,
 191                                                                                                   const css::uno::Sequence< css::uno::Any >& lArguments )
 192             throw(css::uno::Exception       ,
 193                   css::uno::RuntimeException);
 194
 195         //---------------------------------------
 196         // XMultiServiceFactory
 197
 198         /** @short  return list of all well know detect services, which can be created by this factory.
 199
 200             @attention  Because this service implements read/write access to the configuration too,
 201                         this list is dynamic. Means: in multithreaded environments some items of this
 202                         return list could be invalid next time!
 203
 204             @return A list of all registered detect services.
 205          */
 206
 207         virtual css::uno::Sequence< ::rtl::OUString > SAL_CALL getAvailableServiceNames()
 208             throw(css::uno::RuntimeException);
 209
 210         //---------------------------------------
 211         // XNameContainer
 212
 213         /** @short  add new detect service entry to this container.
 214
 215             @descr  This will change all internal structures only!
 216                     Updating of the configuration layer and notify of all registered
 217                     listener will be done inside API call XFlushable::flush() on this
 218                     container.
 219
 220             @param  sName
 221                     means the uno implementation name of this new detect service entry.
 222
 223             @param  aPropertySet [sequence< com::sun::star::beans::PropertyValue >!]
 224                     describe this new entry. For a list of all supported properties
 225                     have a look on method >>getByName()<<.
 226                     Note: Missing values will be created with defaults!
 227
 228             @exception  com::sun::star::lang::IllegalArgumentException
 229                         if one of the incoming parameters seams to be invalid.
 230                         That doesn't include the check, if this item already exist!
 231
 232             @exception  com::sun::star::container::ElementExistException
 233                         if this item already exist inside this container.
 234
 235             @exception  com::sun::star::lang::WrappedTargetException
 236                         f creation of the internal structures failed.
 237          */
 238
 239         virtual void SAL_CALL insertByName( const ::rtl::OUString& sName        ,
 240                                             const css::uno::Any&   aPropertySet )
 241             throw(css::lang::IllegalArgumentException  ,
 242                   css::container::ElementExistException,
 243                   css::lang::WrappedTargetException    ,
 244                   css::uno::RuntimeException           );
 245
 246         //---------------------------------------
 247         // XNameContainer
 248
 249         /** @short  remove a detect service entry from this container.
 250
 251             @descr  This will change all internal structures only!
 252                     Updating of the configuration layer and notify of all registered
 253                     listener will be done inside API call XFlushable::flush() on this
 254                     container.
 255
 256             @param  sName
 257                     means the uno implementation name of a detect service entry.
 258
 259             @exception  com::sun::star::container::NoSuchElementException
 260                         if the requested item does not exist inside this container.
 261
 262             @exception  com::sun::star::lang::WrappedTargetException
 263                         if creation of the internal structures failed.
 264          */
 265
 266         virtual void SAL_CALL removeByName( const ::rtl::OUString& sName )
 267             throw(css::container::NoSuchElementException,
 268                   css::lang::WrappedTargetException     ,
 269                   css::uno::RuntimeException            );
 270
 271         //---------------------------------------
 272         // XNameReplace
 273
 274         /** @short  change a detect service entry inside this container.
 275
 276             @descr  This will change all internal structures only!
 277                     Updating of the configuration layer and notify of all registered
 278                     listener will be done inside API call XFlushable::flush() on this
 279                     container.
 280
 281             @param  sName
 282                     means the uno implementation name of a detect service entry.
 283
 284             @param  aPropertySet [sequence< com::sun::star::beans::PropertyValue >!]
 285                     describe the changes on this entry. For a list of all supported properties
 286                     have a look on method getByName().
 287                     Note: Missing properties will be untouched.
 288
 289             @exception  com::sun::star::lang::IllegalArgumentException
 290                         if one of the incoming parameters seams to be invalid.
 291                         That doesn't include the check, if this item exist!
 292
 293             @exception  com::sun::star::container::NoSuchElementException
 294                         if the requested item does not exist inside this container.
 295
 296             @exception  com::sun::star::lang::WrappedTargetException
 297                         if updating of the internal structures failed.
 298          */
 299
 300         virtual void SAL_CALL replaceByName( const ::rtl::OUString& sName        ,
 301                                              const css::uno::Any&   aPropertySet )
 302             throw(css::lang::IllegalArgumentException   ,
 303                   css::container::NoSuchElementException,
 304                   css::lang::WrappedTargetException     ,
 305                   css::uno::RuntimeException            );
 306
 307         //---------------------------------------
 308         // XNameAccess
 309
 310         /// @HTML
 311         /** @short  return properties of queried detector item.
 312
 313             @descr  Use this method to get all informations about a detector item of this cache.
 314                     A sequence< com::sun::star::beans::PropertyValue > packed inside an Any will be returned.
 315                     Following properties are defined:
 316                     <table border=1>
 317                     <tr>
 318                         <td><b>Property</b></td>
 319                         <td><b>Value<b></td>
 320                         <td><b>Description<b></td>
 321                     </tr>
 322                     <tr>
 323                         <td>Name</td>
 324                         <td>[string]</td>
 325                             <td>the uno implementation name for this detect service</td>
 326                     </tr>
 327                     <tr>
 328                         <td>Types</td>
 329                         <td>[sequence< string >]</td>
 330                         <td>a list of all internbal type names, which this detect service is registered for</td>
 331                     </tr>
 332                     </table>
 333
 334             @param  sName
 335                     the uno implementation name the requested detector.
 336
 337             @return A property set, which describe this detect service.
 338                     It uses a sequence< com::sun::star::beans::PropertyValue > internaly.
 339
 340             @exception  com::sun::star::container::NoSuchElementException
 341                         if the requested entry does not exist inside this container.
 342          */
 343         /// @NOHTML
 344
 345         virtual css::uno::Any SAL_CALL getByName( const ::rtl::OUString& sName )
 346             throw(css::container::NoSuchElementException,
 347                   css::lang::WrappedTargetException     ,
 348                   css::uno::RuntimeException            );
 349
 350         //---------------------------------------
 351         // XNameAccess
 352
 353         /** @short  return list of all well know container entries available on this container.
 354
 355             @attention  Because this service implements read/write access to the configuration too,
 356                         this list is dynamic. Means: in multithreaded environments some items of this
 357                         return list could be invalid next time!
 358
 359             @return A list of all well known container items.
 360          */
 361
 362         virtual css::uno::Sequence< ::rtl::OUString > SAL_CALL getElementNames()
 363             throw(css::uno::RuntimeException);
 364
 365         //---------------------------------------
 366         // XNameAccess
 367
 368         /** @short  check if searched entry exist inside this container.
 369
 370             @attention  In multithreaded environments it's not guaranteed, that a
 371                         queried item exist next time realy! It can be deleted by
 372                         another thread ...
 373
 374             @param  sName
 375                     the name of the queried container entry.
 376
 377             @return TRUE if the requested item exist; FALSE otherwise.
 378          */
 379
 380         virtual sal_Bool SAL_CALL hasByName( const ::rtl::OUString& sName )
 381             throw(css::uno::RuntimeException);
 382
 383         //---------------------------------------
 384         // XElementAccess
 385
 386         /** @short  return the uno type, which is used for all container items.
 387
 388             @return Type of sequence< com::sun::star::beans::PropertyValue > everytime - because it's fix.
 389          */
 390
 391         virtual css::uno::Type SAL_CALL getElementType()
 392             throw(css::uno::RuntimeException);
 393
 394         //---------------------------------------
 395         // XElementAccess
 396
 397         /** @short  return fill state of this cache.
 398
 399             @return TRUE if any item exist inside this conatiner; FALSE otherwhise.
 400          */
 401
 402         virtual sal_Bool SAL_CALL hasElements()
 403             throw(css::uno::RuntimeException);
 404
 405         //---------------------------------------
 406         // XFlushable
 407
 408         /** @short  update the configuration layer and notify all registered listener.
 409
 410             @descr  All container interface methods update the internal structures of
 411                     this container only. But the underlying configuration layer and
 412                     may some possible other caches was not updated.
 413                     Calling of flush() will do that.
 414                     At the same time all currently registered flush listener will be informed,
 415                     so they can update her structures too.
 416                     Note: Before all these operations are started realy, all changes will be
 417                     verified and if neccessary some corrections will be done.
 418                     In case the cache will be invalid and could not be repaired an exception is thrown!
 419                     Normaly this container will not work correctly afterwards ...
 420
 421             @exception  com::sun::star::uno::RuntimeException
 422                         if the changes on this container was invald and could not be repaired.
 423          */
 424
 425         virtual void SAL_CALL flush()
 426             throw(css::uno::RuntimeException);
 427
 428         //---------------------------------------
 429         // XFlushable
 430
 431         /** @short  register listener for container updates.
 432
 433             @param  xListener
 434                     reference to listener, which wish to be registered.
 435
 436             @exception  com::sun::star::uno::RuntimeException
 437                         if the given listener is an invalid reference.
 438                         Note: multiple calls of this method for the same listener won't be checked!
 439          */
 440
 441         virtual void SAL_CALL addFlushListener( const css::uno::Reference< css::util::XFlushListener >& xListener )
 442             throw(css::uno::RuntimeException);
 443
 444         //---------------------------------------
 445         // XFlushable
 446
 447         /** @short  deregister listener for container updates.
 448
 449             @param  xListener
 450                     reference to listener, which wish to be deregistered.
 451
 452             @exception  com::sun::star::uno::RuntimeException
 453                         if the given listener is an invalid reference.
 454                         Note: multiple calls of this method for the same listener won't be checked!
 455          */
 456
 457         virtual void SAL_CALL removeFlushListener( const css::uno::Reference< css::util::XFlushListener >& xListener )
 458             throw(css::uno::RuntimeException);
 459
 460 }; // class DetectorFactory
 461
 462 } // namespace framework
 463
 464 #endif // #ifndef __FRAMEWORK_SERVICES_DETECTORFACTORY_HXX_