include/ucbhelper/contenthelper.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
  20 #ifndef INCLUDED_UCBHELPER_CONTENTHELPER_HXX
  21 #define INCLUDED_UCBHELPER_CONTENTHELPER_HXX
  22
  23 #include <com/sun/star/beans/XPropertyContainer.hpp>
  24 #include <com/sun/star/beans/XPropertiesChangeNotifier.hpp>
  25 #include <com/sun/star/ucb/XCommandProcessor.hpp>
  26 #include <com/sun/star/ucb/XContent.hpp>
  27 #include <com/sun/star/beans/XPropertySetInfoChangeNotifier.hpp>
  28 #include <com/sun/star/ucb/XCommandInfoChangeNotifier.hpp>
  29 #include <com/sun/star/container/XChild.hpp>
  30 #include <com/sun/star/lang/XMultiServiceFactory.hpp>
  31 #include <com/sun/star/lang/XTypeProvider.hpp>
  32 #include <com/sun/star/lang/XServiceInfo.hpp>
  33 #include <com/sun/star/lang/XComponent.hpp>
  34 #include <com/sun/star/ucb/CommandAbortedException.hpp>
  35 #include <cppuhelper/weak.hxx>
  36
  37 #include <osl/mutex.hxx>
  38 #include <rtl/ref.hxx>
  39 #include <ucbhelper/macros.hxx>
  40 #include <ucbhelper/ucbhelperdllapi.h>
  41
  42 namespace com { namespace sun { namespace star { namespace ucb {
  43     struct CommandInfo;
  44     class XCommandEnvironment;
  45     class XCommandInfo;
  46     class XPersistentPropertySet;
  47 } } } }
  48
  49 namespace com { namespace sun { namespace star { namespace beans {
  50     struct Property;
  51     class XPropertySetInfo;
  52 } } } }
  53
  54 namespace ucbhelper_impl { struct ContentImplHelper_Impl; }
  55
  56 namespace ucbhelper
  57 {
  58
  59 //=========================================================================
  60
  61 class ContentProviderImplHelper;
  62
  63 /**
  64   * This is an abstract base class for implementations of the service
  65   * com.sun.star.ucb.Content. Implementations derived from this class are
  66   * objects provided by implementations derived from
  67   * class ucb::ContentProviderImplHelper.
  68   *
  69   * Features of the base class implementation:
  70   * - standard interfaces ( XInterface, XTypeProvider, XServiceInfo )
  71   * - all required interfaces for service com::sun::star::ucb::Content
  72   * - all required listener containers
  73   *   ( XComponent, XPropertiesChangeNotifier, XPropertySetInfoChangeNotifier,
  74   *     XCommandInfoChangeNotifier )
  75   * - XPropertyContainer implementation ( persistence is implemented using
  76   *   service com.sun.star.ucb.Store )
  77   * - complete XPropertySetInfo implementation ( including Additioanl Core
  78   *   Properties supplied via XPropertyContainer interface )
  79   *   -> protected method: getPropertySetInfo
  80   * - complete XCommandInfo implementation
  81   *    -> protected method: getCommandInfo
  82   */
  83 class UCBHELPER_DLLPUBLIC ContentImplHelper :
  84                 public cppu::OWeakObject,
  85                 public com::sun::star::lang::XTypeProvider,
  86                 public com::sun::star::lang::XServiceInfo,
  87                 public com::sun::star::lang::XComponent,
  88                 public com::sun::star::ucb::XContent,
  89                 public com::sun::star::ucb::XCommandProcessor,
  90                 public com::sun::star::beans::XPropertiesChangeNotifier,
  91                 public com::sun::star::beans::XPropertyContainer,
  92                 public com::sun::star::beans::XPropertySetInfoChangeNotifier,
  93                 public com::sun::star::ucb::XCommandInfoChangeNotifier,
  94                 public com::sun::star::container::XChild
  95 {
  96     friend class PropertySetInfo;
  97     friend class CommandProcessorInfo;
  98
  99     ucbhelper_impl::ContentImplHelper_Impl* m_pImpl;
 100
 101 protected:
 102     osl::Mutex                       m_aMutex;
 103     com::sun::star::uno::Reference< com::sun::star::uno::XComponentContext >
 104                                      m_xContext;
 105     com::sun::star::uno::Reference< com::sun::star::ucb::XContentIdentifier >
 106                                      m_xIdentifier;
 107     rtl::Reference< ContentProviderImplHelper >
 108                                      m_xProvider;
 109     sal_uInt32                       m_nCommandId;
 110
 111 private:
 112     /**
 113       * Your implementation of this method must return a sequence containing
 114       * the meta data of the properties supported by the content.
 115       * Note: If you wish to provide your own implementation of the interface
 116       * XPropertyContainer ( completely override addContent and removeContent
 117       * implementation of this base class in this case ), you can supply the
 118       * meta data for your Additional Core Properties here to get a fully
 119       * featured getPropertySetInfo method ( see below ).
 120       *
 121       * @param xEnv is an environment to use for example, for interactions.
 122       * @return a sequence containing the property meta data.
 123       */
 124     UCBHELPER_DLLPRIVATE
 125     virtual com::sun::star::uno::Sequence< com::sun::star::beans::Property >
 126     getProperties( const com::sun::star::uno::Reference<
 127                     com::sun::star::ucb::XCommandEnvironment > & xEnv ) = 0;
 128
 129     /**
 130       * Your implementation of this method must return a sequence containing
 131       * the meta data of the commands supported by the content.
 132       *
 133       * @param xEnv is an environment to use for example, for interactions.
 134       * @return a sequence containing the command meta data.
 135       */
 136     UCBHELPER_DLLPRIVATE
 137     virtual com::sun::star::uno::Sequence< com::sun::star::ucb::CommandInfo >
 138     getCommands( const com::sun::star::uno::Reference<
 139                     com::sun::star::ucb::XCommandEnvironment > & xEnv ) = 0;
 140
 141     /**
 142       * The implementation of this method shall return the URL of the parent
 143       * of your content.
 144       *
 145       * @return the URL of the parent content or an empty string.
 146       *         Note that not all contents must have one parent. There may
 147       *         be contents with no parent. In that case an empty string must
 148       *         be returned. If your content has more than one parent you may
 149       *         return the URL of one "preferred" parent or an empty string.
 150       */
 151     UCBHELPER_DLLPRIVATE virtual OUString getParentURL() = 0;
 152
 153 protected:
 154     /**
 155       * This method returns complete meta data for the properties ( including
 156       * Additional Core Properties supplied via XPropertyContainer interface )
 157       * supported by the content. To implement the required command
 158       * "getPropertySetInfo" simply return the return value of this method.
 159       *
 160       * @param xEnv is an environment to use for example, for interactions.
 161       * @param bCache indicates, whether the implemetation should use
 162       *        cached data, if exist.
 163       * @return an XPropertySetInfo implementation object containing meta data
 164       *         for the properties supported by this content.
 165       */
 166     com::sun::star::uno::Reference< com::sun::star::beans::XPropertySetInfo >
 167     getPropertySetInfo( const com::sun::star::uno::Reference<
 168                             com::sun::star::ucb::XCommandEnvironment > & xEnv,
 169                         sal_Bool bCache = sal_True );
 170
 171     /**
 172       * This method returns complete meta data for the commands supported by
 173       * the content. To implement the required command "getCommandInfo" simply
 174       * return the return value of this method.
 175       *
 176       * @param xEnv is an environment to use for example, for interactions.
 177       * @param bCache indicates, whether the implemetation should use
 178       *        cached data, if exist.
 179       * @return an XCommandInfo implementation object containing meta data
 180       *         for the commands supported by this content.
 181       */
 182     com::sun::star::uno::Reference< com::sun::star::ucb::XCommandInfo >
 183     getCommandInfo( const com::sun::star::uno::Reference<
 184                             com::sun::star::ucb::XCommandEnvironment > & xEnv,
 185                     sal_Bool bCache = sal_True );
 186
 187     /**
 188       * This method can be used to propagate changes of property values.
 189       *
 190       * @param evt is a sequence of property change events.
 191       */
 192     void notifyPropertiesChange(
 193         const com::sun::star::uno::Sequence<
 194                 com::sun::star::beans::PropertyChangeEvent >& evt ) const;
 195
 196     /**
 197       * This method can be used to propagate changes of the propertyset
 198       * info of your content (i.e. this happens if a new property is added
 199       * to your content via its XPropertyContainer interface). This base class
 200       * automatically generates events when the propertyset info changes. If
 201       * you provide your own implementations of addproperty and removeProperty,
 202       * then you must call "notifyPropertySetInfoChange" by yourself.
 203       *
 204       * @param evt is a sequence of property change events.
 205       */
 206     void notifyPropertySetInfoChange(
 207         const com::sun::star::beans::PropertySetInfoChangeEvent& evt ) const;
 208
 209     /**
 210       * This method can be used to propagate content events.
 211       *
 212       * @param evt is a sequence of content events.
 213       */
 214     void notifyContentEvent(
 215             const com::sun::star::ucb::ContentEvent& evt ) const;
 216
 217     /**
 218       * Use this method to announce the insertion of this content at
 219       * the end of your implementation of the command "insert". The
 220       * implementation of is method propagates a ContentEvent( INSERTED ).
 221       */
 222     void inserted();
 223
 224     /**
 225       * Use this method to announce the destruction of this content at
 226       * the end of your implementation of the command "delete". The
 227       * implementation of is method propagates a ContentEvent( DELETED )
 228       * and a ContentEvent( REMOVED ) at the parent of the deleted content,
 229       * if a parent exists.
 230       */
 231     void deleted();
 232
 233     /**
 234       * Use this method to change the identity of a content. The implementation
 235       * of this method will replace the content identifier of the content and
 236       * propagate the appropriate ContentEvent( EXCHANGED ).
 237       *
 238       * @param  rNewId is the new content identifier for the contant.
 239       * @return a success indicator.
 240       */
 241     sal_Bool exchange( const com::sun::star::uno::Reference<
 242                         com::sun::star::ucb::XContentIdentifier >& rNewId );
 243
 244     /**
 245       * Use this method to get access to the Additional Core Properties of
 246       * the content ( added using content's XPropertyContainer interface ).
 247       * If you supply your own XPropertyContainer implementation, this method
 248       * will always return an empty propertyset.
 249       *
 250       * @param  bCreate indicates whether a new propertyset shall be created
 251       *         if it does not exist.
 252       * @return the implementation of the service
 253       *         com.sun.star.ucb.PersistentPropertySet.
 254       */
 255     com::sun::star::uno::Reference<
 256         com::sun::star::ucb::XPersistentPropertySet >
 257     getAdditionalPropertySet( sal_Bool bCreate );
 258
 259     /**
 260       * This method renames the propertyset containing the Additional Core
 261       * Properties of the content.
 262       *
 263       * @param  rOldKey is the old key of the propertyset.
 264       * @param  rNewKey is the new key for the propertyset.
 265       * @param  bRecursive is a flag indicating whether propertysets for
 266       *         children described by rOldKey shall be renamed too.
 267       * @return True, if the operation succeeded - False, otherwise.
 268       */
 269     sal_Bool renameAdditionalPropertySet( const OUString& rOldKey,
 270                                           const OUString& rNewKey,
 271                                           sal_Bool bRecursive );
 272
 273     /**
 274       * This method copies the propertyset containing the Additional Core
 275       * Properties of the content.
 276       *
 277       * @param  rSourceKey is the key of the source propertyset.
 278       * @param  rTargetKey is the key of the target propertyset.
 279       * @param  bRecursive is a flag indicating whether propertysets for
 280       *         children described by rSourceKey shall be copied too.
 281       * @return True, if the operation succeeded - False, otherwise.
 282       */
 283     sal_Bool copyAdditionalPropertySet( const OUString& rSourceKey,
 284                                         const OUString& rTargetKey,
 285                                         sal_Bool bRecursive );
 286
 287     /**
 288       * This method removes the propertyset containing the Additional Core
 289       * Properties of the content.
 290       *
 291       * @param  bRecursive is a flag indicating whether propertysets for
 292       *         children described by rOldKey shall be removed too.
 293       * @return True, if the operation succeeded - False, otherwise.
 294       */
 295     sal_Bool removeAdditionalPropertySet( sal_Bool bRecursive );
 296
 297 public:
 298     /**
 299       * Constructor.
 300       *
 301       * Note that the implementation of this ctor registers itself at its
 302       * content provider. The provider implementation inserts the content
 303       * in a hash map. So it easyly can be found and reused when the provider
 304       * is asked for a content.
 305       *
 306       * @param rxContext is a Service Manager.
 307       * @param rxProvider is the provider for the content.
 308       * @param Identifier is the content identifier for the content.
 309       */
 310     ContentImplHelper(
 311             const com::sun::star::uno::Reference<
 312                 com::sun::star::uno::XComponentContext >& rxContext,
 313             const rtl::Reference< ContentProviderImplHelper >& rxProvider,
 314             const com::sun::star::uno::Reference<
 315                 com::sun::star::ucb::XContentIdentifier >& Identifier );
 316
 317     /**
 318       * Destructor.
 319       *
 320       * Note that the implementation of this dtor deregisters itself from its
 321       * content provider. The provider implementation removes the content
 322       * from a hash map.
 323       */
 324     virtual ~ContentImplHelper();
 325
 326     // XInterface
 327     XINTERFACE_DECL()
 328
 329     // XTypeProvider
 330     XTYPEPROVIDER_DECL()
 331
 332     // XServiceInfo
 333     virtual OUString SAL_CALL
 334     getImplementationName()
 335         throw( ::com::sun::star::uno::RuntimeException ) = 0;
 336     virtual sal_Bool SAL_CALL
 337     supportsService( const OUString& ServiceName )
 338         throw( ::com::sun::star::uno::RuntimeException );
 339     virtual ::com::sun::star::uno::Sequence< OUString > SAL_CALL
 340     getSupportedServiceNames()
 341         throw( ::com::sun::star::uno::RuntimeException ) = 0;
 342
 343     // XComponent
 344     virtual void SAL_CALL
 345     dispose()
 346         throw( com::sun::star::uno::RuntimeException );
 347     virtual void SAL_CALL
 348     addEventListener( const com::sun::star::uno::Reference<
 349                         com::sun::star::lang::XEventListener >& Listener )
 350         throw( com::sun::star::uno::RuntimeException );
 351     virtual void SAL_CALL
 352     removeEventListener( const com::sun::star::uno::Reference<
 353                             com::sun::star::lang::XEventListener >& Listener )
 354         throw( com::sun::star::uno::RuntimeException );
 355
 356     // XContent
 357     virtual com::sun::star::uno::Reference<
 358                 com::sun::star::ucb::XContentIdentifier > SAL_CALL
 359     getIdentifier()
 360         throw( com::sun::star::uno::RuntimeException );
 361     virtual OUString SAL_CALL
 362     getContentType()
 363         throw( com::sun::star::uno::RuntimeException ) = 0;
 364     virtual void SAL_CALL
 365     addContentEventListener(
 366         const com::sun::star::uno::Reference<
 367             com::sun::star::ucb::XContentEventListener >& Listener )
 368         throw( com::sun::star::uno::RuntimeException );
 369     virtual void SAL_CALL
 370     removeContentEventListener(
 371         const com::sun::star::uno::Reference<
 372             com::sun::star::ucb::XContentEventListener >& Listener )
 373         throw( com::sun::star::uno::RuntimeException );
 374
 375     // XCommandProcessor
 376     virtual sal_Int32 SAL_CALL
 377     createCommandIdentifier()
 378         throw( com::sun::star::uno::RuntimeException );
 379     virtual com::sun::star::uno::Any SAL_CALL
 380     execute( const com::sun::star::ucb::Command& aCommand,
 381              sal_Int32 CommandId,
 382              const com::sun::star::uno::Reference<
 383                  com::sun::star::ucb::XCommandEnvironment >& Environment )
 384         throw( com::sun::star::uno::Exception,
 385                com::sun::star::ucb::CommandAbortedException,
 386                com::sun::star::uno::RuntimeException ) = 0;
 387     virtual void SAL_CALL
 388     abort( sal_Int32 CommandId )
 389         throw( com::sun::star::uno::RuntimeException ) = 0;
 390
 391     // XPropertiesChangeNotifier
 392     virtual void SAL_CALL
 393     addPropertiesChangeListener(
 394         const com::sun::star::uno::Sequence< OUString >& PropertyNames,
 395          const com::sun::star::uno::Reference<
 396             com::sun::star::beans::XPropertiesChangeListener >& Listener )
 397         throw( com::sun::star::uno::RuntimeException );
 398     virtual void SAL_CALL
 399     removePropertiesChangeListener(
 400         const com::sun::star::uno::Sequence< OUString >& PropertyNames,
 401         const com::sun::star::uno::Reference<
 402             com::sun::star::beans::XPropertiesChangeListener >& Listener )
 403         throw( com::sun::star::uno::RuntimeException );
 404
 405     // XCommandInfoChangeNotifier
 406     virtual void SAL_CALL
 407     addCommandInfoChangeListener(
 408         const com::sun::star::uno::Reference<
 409             com::sun::star::ucb::XCommandInfoChangeListener >& Listener )
 410         throw( com::sun::star::uno::RuntimeException );
 411     virtual void SAL_CALL
 412     removeCommandInfoChangeListener(
 413         const com::sun::star::uno::Reference<
 414             ::com::sun::star::ucb::XCommandInfoChangeListener >& Listener )
 415         throw( com::sun::star::uno::RuntimeException );
 416
 417     // XPropertyContainer
 418
 419     /**
 420       * This method adds a property to the content according to the interface
 421       * specification. The properties will be stored using the service
 422       * com.sun.star.ucb.Store.
 423       *
 424       * Note: You may provide your own implementation of this method, for
 425       * instance, if your data source supports adding/removing of properties.
 426       * Don't forget to return the meta data for these properties in your
 427       * implementation of getPropertyInfoTable.
 428       */
 429     virtual void SAL_CALL
 430     addProperty( const OUString& Name,
 431                  sal_Int16 Attributes,
 432                  const com::sun::star::uno::Any& DefaultValue )
 433         throw( com::sun::star::beans::PropertyExistException,
 434                com::sun::star::beans::IllegalTypeException,
 435                com::sun::star::lang::IllegalArgumentException,
 436                com::sun::star::uno::RuntimeException );
 437
 438     /**
 439       * This method removes a property from the content according to the
 440       * interface specification. The properties will be stored using the
 441       * service com.sun.star.ucb.Store.
 442       *
 443       * Note: You may provide your own implementation of this method, for
 444       * instance, if your data source supports adding/removing of properties.
 445       * Don't forget to return the meta data for these properties in your
 446       * implementation of getPropertyInfoTable.
 447       */
 448     virtual void SAL_CALL
 449     removeProperty( const OUString& Name )
 450         throw( com::sun::star::beans::UnknownPropertyException,
 451                com::sun::star::beans::NotRemoveableException,
 452                com::sun::star::uno::RuntimeException );
 453
 454     // XPropertySetInfoChangeNotifier
 455     virtual void SAL_CALL
 456     addPropertySetInfoChangeListener(
 457         const com::sun::star::uno::Reference<
 458             com::sun::star::beans::XPropertySetInfoChangeListener >& Listener )
 459         throw( com::sun::star::uno::RuntimeException );
 460     virtual void SAL_CALL
 461     removePropertySetInfoChangeListener(
 462         const com::sun::star::uno::Reference<
 463             com::sun::star::beans::XPropertySetInfoChangeListener >& Listener )
 464         throw( com::sun::star::uno::RuntimeException );
 465
 466     // XChild
 467
 468     /**
 469       * This method returns the content representing the parent of a content,
 470       * if such a parent exists. The implementation of this method uses your
 471       * implementation of getParentURL.
 472       */
 473     virtual com::sun::star::uno::Reference<
 474                 com::sun::star::uno::XInterface > SAL_CALL
 475     getParent()
 476         throw( com::sun::star::uno::RuntimeException );
 477
 478     /**
 479       * The implementation of this method always throws a NoSupportException.
 480       */
 481     virtual void SAL_CALL
 482     setParent( const com::sun::star::uno::Reference<
 483                         com::sun::star::uno::XInterface >& Parent )
 484         throw( com::sun::star::lang::NoSupportException,
 485                com::sun::star::uno::RuntimeException );
 486
 487     //////////////////////////////////////////////////////////////////////
 488     // Non-interface methods.
 489     //////////////////////////////////////////////////////////////////////
 490
 491     /**
 492       * This method returns the provider of the content.
 493       *
 494       * @return the provider of the content.
 495       */
 496     const rtl::Reference< ContentProviderImplHelper >& getProvider() const
 497     { return m_xProvider; }
 498 };
 499
 500 } // namespace ucbhelper
 501
 502 #endif /* ! INCLUDED_UCBHELPER_CONTENTHELPER_HXX */
 503
 504 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */