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 #include <memory>
  42
  43 namespace com { namespace sun { namespace star { namespace ucb {
  44     struct CommandInfo;
  45     class XCommandEnvironment;
  46     class XCommandInfo;
  47     class XPersistentPropertySet;
  48 } } } }
  49
  50 namespace com { namespace sun { namespace star { namespace beans {
  51     struct Property;
  52     class XPropertySetInfo;
  53 } } } }
  54
  55 namespace ucbhelper_impl { struct ContentImplHelper_Impl; }
  56
  57 namespace ucbhelper
  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 css::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 Additional 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 css::lang::XTypeProvider,
  86                 public css::lang::XServiceInfo,
  87                 public css::lang::XComponent,
  88                 public css::ucb::XContent,
  89                 public css::ucb::XCommandProcessor,
  90                 public css::beans::XPropertiesChangeNotifier,
  91                 public css::beans::XPropertyContainer,
  92                 public css::beans::XPropertySetInfoChangeNotifier,
  93                 public css::ucb::XCommandInfoChangeNotifier,
  94                 public css::container::XChild
  95 {
  96     friend class PropertySetInfo;
  97     friend class CommandProcessorInfo;
  98
  99     std::unique_ptr<ucbhelper_impl::ContentImplHelper_Impl> m_pImpl;
 100
 101 protected:
 102     osl::Mutex                       m_aMutex;
 103     css::uno::Reference< css::uno::XComponentContext >
 104                                      m_xContext;
 105     css::uno::Reference< css::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 css::uno::Sequence< css::beans::Property >
 126     getProperties( const css::uno::Reference< css::ucb::XCommandEnvironment > & xEnv ) = 0;
 127
 128     /**
 129       * Your implementation of this method must return a sequence containing
 130       * the meta data of the commands supported by the content.
 131       *
 132       * @param xEnv is an environment to use for example, for interactions.
 133       * @return a sequence containing the command meta data.
 134       */
 135     UCBHELPER_DLLPRIVATE
 136     virtual css::uno::Sequence< css::ucb::CommandInfo >
 137     getCommands( const css::uno::Reference< css::ucb::XCommandEnvironment > & xEnv ) = 0;
 138
 139     /**
 140       * The implementation of this method shall return the URL of the parent
 141       * of your content.
 142       *
 143       * @return the URL of the parent content or an empty string.
 144       *         Note that not all contents must have one parent. There may
 145       *         be contents with no parent. In that case an empty string must
 146       *         be returned. If your content has more than one parent you may
 147       *         return the URL of one "preferred" parent or an empty string.
 148       */
 149     UCBHELPER_DLLPRIVATE virtual OUString getParentURL() = 0;
 150
 151 protected:
 152     /**
 153       * This method returns complete meta data for the properties ( including
 154       * Additional Core Properties supplied via XPropertyContainer interface )
 155       * supported by the content. To implement the required command
 156       * "getPropertySetInfo" simply return the return value of this method.
 157       *
 158       * @param xEnv is an environment to use for example, for interactions.
 159       * @param bCache indicates, whether the implementation should use
 160       *        cached data, if exist.
 161       * @return an XPropertySetInfo implementation object containing meta data
 162       *         for the properties supported by this content.
 163       */
 164     css::uno::Reference< css::beans::XPropertySetInfo >
 165     getPropertySetInfo( const css::uno::Reference< css::ucb::XCommandEnvironment > & xEnv,
 166                         bool bCache = true );
 167
 168     /**
 169       * This method returns complete meta data for the commands supported by
 170       * the content. To implement the required command "getCommandInfo" simply
 171       * return the return value of this method.
 172       *
 173       * @param xEnv is an environment to use for example, for interactions.
 174       * @param bCache indicates, whether the implementation should use
 175       *        cached data, if exist.
 176       * @return an XCommandInfo implementation object containing meta data
 177       *         for the commands supported by this content.
 178       */
 179     css::uno::Reference< css::ucb::XCommandInfo >
 180     getCommandInfo( const css::uno::Reference< css::ucb::XCommandEnvironment > & xEnv,
 181                     bool bCache = true );
 182
 183     /**
 184       * This method can be used to propagate changes of property values.
 185       *
 186       * @param evt is a sequence of property change events.
 187       */
 188     void notifyPropertiesChange(
 189         const css::uno::Sequence< css::beans::PropertyChangeEvent >& evt ) const;
 190
 191     /**
 192       * This method can be used to propagate changes of the propertyset
 193       * info of your content (i.e. this happens if a new property is added
 194       * to your content via its XPropertyContainer interface). This base class
 195       * automatically generates events when the propertyset info changes. If
 196       * you provide your own implementations of addproperty and removeProperty,
 197       * then you must call "notifyPropertySetInfoChange" by yourself.
 198       *
 199       * @param evt is a sequence of property change events.
 200       */
 201     void notifyPropertySetInfoChange(
 202         const css::beans::PropertySetInfoChangeEvent& evt ) const;
 203
 204     /**
 205       * This method can be used to propagate content events.
 206       *
 207       * @param evt is a sequence of content events.
 208       */
 209     void notifyContentEvent(
 210             const css::ucb::ContentEvent& evt ) const;
 211
 212     /**
 213       * Use this method to announce the insertion of this content at
 214       * the end of your implementation of the command "insert". The
 215       * implementation of is method propagates a ContentEvent( INSERTED ).
 216       */
 217     void inserted();
 218
 219     /**
 220       * Use this method to announce the destruction of this content at
 221       * the end of your implementation of the command "delete". The
 222       * implementation of is method propagates a ContentEvent( DELETED )
 223       * and a ContentEvent( REMOVED ) at the parent of the deleted content,
 224       * if a parent exists.
 225       */
 226     void deleted();
 227
 228     /**
 229       * Use this method to change the identity of a content. The implementation
 230       * of this method will replace the content identifier of the content and
 231       * propagate the appropriate ContentEvent( EXCHANGED ).
 232       *
 233       * @param  rNewId is the new content identifier for the content.
 234       * @return a success indicator.
 235       */
 236     bool exchange( const css::uno::Reference< css::ucb::XContentIdentifier >& rNewId );
 237
 238     /**
 239       * Use this method to get access to the Additional Core Properties of
 240       * the content ( added using content's XPropertyContainer interface ).
 241       * If you supply your own XPropertyContainer implementation, this method
 242       * will always return an empty propertyset.
 243       *
 244       * @param  bCreate indicates whether a new propertyset shall be created
 245       *         if it does not exist.
 246       * @return the implementation of the service
 247       *         com.sun.star.ucb.PersistentPropertySet.
 248       */
 249     css::uno::Reference< css::ucb::XPersistentPropertySet >
 250     getAdditionalPropertySet( bool bCreate );
 251
 252     /**
 253       * This method renames the propertyset containing the Additional Core
 254       * Properties of the content.
 255       *
 256       * @param  rOldKey is the old key of the propertyset.
 257       * @param  rNewKey is the new key for the propertyset.
 258       * @return True, if the operation succeeded - False, otherwise.
 259       */
 260     bool renameAdditionalPropertySet( const OUString& rOldKey,
 261                                           const OUString& rNewKey );
 262
 263     /**
 264       * This method copies the propertyset containing the Additional Core
 265       * Properties of the content.
 266       *
 267       * @param  rSourceKey is the key of the source propertyset.
 268       * @param  rTargetKey is the key of the target propertyset.
 269       * @return True, if the operation succeeded - False, otherwise.
 270       */
 271     bool copyAdditionalPropertySet( const OUString& rSourceKey,
 272                                         const OUString& rTargetKey );
 273
 274     /**
 275       * This method removes the propertyset containing the Additional Core
 276       * Properties of the content.
 277       *
 278       * Propertysets for children described by rOldKey are removed too.
 279       *
 280       * @return True, if the operation succeeded - False, otherwise.
 281       */
 282     bool removeAdditionalPropertySet();
 283
 284 public:
 285     /**
 286       * Constructor.
 287       *
 288       * Note that the implementation of this ctor registers itself at its
 289       * content provider. The provider implementation inserts the content
 290       * in a hash map. So it easily can be found and reused when the provider
 291       * is asked for a content.
 292       *
 293       * @param rxContext is a Service Manager.
 294       * @param rxProvider is the provider for the content.
 295       * @param Identifier is the content identifier for the content.
 296       */
 297     ContentImplHelper(
 298             const css::uno::Reference< css::uno::XComponentContext >& rxContext,
 299             const rtl::Reference< ContentProviderImplHelper >& rxProvider,
 300             const css::uno::Reference< css::ucb::XContentIdentifier >& Identifier );
 301
 302     /**
 303       * Destructor.
 304       *
 305       * Note that the implementation of this dtor deregisters itself from its
 306       * content provider. The provider implementation removes the content
 307       * from a hash map.
 308       */
 309     virtual ~ContentImplHelper() override;
 310
 311     // XInterface
 312     virtual css::uno::Any SAL_CALL queryInterface( const css::uno::Type & rType ) override;
 313     virtual void SAL_CALL acquire()
 314         throw() override;
 315     virtual void SAL_CALL release()
 316         throw() override;
 317
 318     // XTypeProvider
 319     virtual css::uno::Sequence< sal_Int8 > SAL_CALL
 320     getImplementationId() override;
 321     virtual css::uno::Sequence< css::uno::Type > SAL_CALL
 322     getTypes() override;
 323
 324     // XServiceInfo
 325     virtual OUString SAL_CALL
 326     getImplementationName() override = 0;
 327     virtual sal_Bool SAL_CALL
 328     supportsService( const OUString& ServiceName ) override;
 329     virtual css::uno::Sequence< OUString > SAL_CALL
 330     getSupportedServiceNames() override = 0;
 331
 332     // XComponent
 333     virtual void SAL_CALL
 334     dispose() override;
 335     virtual void SAL_CALL
 336     addEventListener( const css::uno::Reference< css::lang::XEventListener >& Listener ) override;
 337     virtual void SAL_CALL
 338     removeEventListener( const css::uno::Reference< css::lang::XEventListener >& Listener ) override;
 339
 340     // XContent
 341     virtual css::uno::Reference< css::ucb::XContentIdentifier > SAL_CALL
 342     getIdentifier() override;
 343     virtual OUString SAL_CALL
 344     getContentType() override = 0;
 345     virtual void SAL_CALL
 346     addContentEventListener(
 347         const css::uno::Reference< css::ucb::XContentEventListener >& Listener ) override;
 348     virtual void SAL_CALL
 349     removeContentEventListener(
 350         const css::uno::Reference< css::ucb::XContentEventListener >& Listener ) override;
 351
 352     // XCommandProcessor
 353     virtual sal_Int32 SAL_CALL
 354     createCommandIdentifier() override;
 355     virtual css::uno::Any SAL_CALL
 356     execute( const css::ucb::Command& aCommand,
 357              sal_Int32 CommandId,
 358              const css::uno::Reference< css::ucb::XCommandEnvironment >& Environment ) override = 0;
 359     virtual void SAL_CALL
 360     abort( sal_Int32 CommandId ) override = 0;
 361
 362     // XPropertiesChangeNotifier
 363     virtual void SAL_CALL
 364     addPropertiesChangeListener(
 365         const css::uno::Sequence< OUString >& PropertyNames,
 366          const css::uno::Reference< css::beans::XPropertiesChangeListener >& Listener ) override;
 367     virtual void SAL_CALL
 368     removePropertiesChangeListener(
 369         const css::uno::Sequence< OUString >& PropertyNames,
 370         const css::uno::Reference< css::beans::XPropertiesChangeListener >& Listener ) override;
 371
 372     // XCommandInfoChangeNotifier
 373     virtual void SAL_CALL
 374     addCommandInfoChangeListener(
 375         const css::uno::Reference< css::ucb::XCommandInfoChangeListener >& Listener ) override;
 376     virtual void SAL_CALL
 377     removeCommandInfoChangeListener(
 378         const css::uno::Reference< css::ucb::XCommandInfoChangeListener >& Listener ) override;
 379
 380     // XPropertyContainer
 381
 382     /**
 383       * This method adds a property to the content according to the interface
 384       * specification. The properties will be stored using the service
 385       * com.sun.star.ucb.Store.
 386       *
 387       * Note: You may provide your own implementation of this method, for
 388       * instance, if your data source supports adding/removing of properties.
 389       * Don't forget to return the meta data for these properties in your
 390       * implementation of getPropertyInfoTable.
 391       */
 392     virtual void SAL_CALL
 393     addProperty( const OUString& Name,
 394                  sal_Int16 Attributes,
 395                  const css::uno::Any& DefaultValue ) override;
 396
 397     /**
 398       * This method removes a property from the content according to the
 399       * interface specification. The properties will be stored using the
 400       * service com.sun.star.ucb.Store.
 401       *
 402       * Note: You may provide your own implementation of this method, for
 403       * instance, if your data source supports adding/removing of properties.
 404       * Don't forget to return the meta data for these properties in your
 405       * implementation of getPropertyInfoTable.
 406       */
 407     virtual void SAL_CALL
 408     removeProperty( const OUString& Name ) override;
 409
 410     // XPropertySetInfoChangeNotifier
 411     virtual void SAL_CALL
 412     addPropertySetInfoChangeListener(
 413         const css::uno::Reference< css::beans::XPropertySetInfoChangeListener >& Listener ) override;
 414     virtual void SAL_CALL
 415     removePropertySetInfoChangeListener(
 416         const css::uno::Reference< css::beans::XPropertySetInfoChangeListener >& Listener ) override;
 417
 418     // XChild
 419
 420     /**
 421       * This method returns the content representing the parent of a content,
 422       * if such a parent exists. The implementation of this method uses your
 423       * implementation of getParentURL.
 424       */
 425     virtual css::uno::Reference< css::uno::XInterface > SAL_CALL
 426     getParent() override;
 427
 428     /**
 429       * The implementation of this method always throws a NoSupportException.
 430       */
 431     virtual void SAL_CALL
 432     setParent( const css::uno::Reference< css::uno::XInterface >& Parent ) override;
 433
 434
 435     // Non-interface methods.
 436
 437
 438     /**
 439       * This method returns the provider of the content.
 440       *
 441       * @return the provider of the content.
 442       */
 443     const rtl::Reference< ContentProviderImplHelper >& getProvider() const
 444     { return m_xProvider; }
 445 };
 446
 447 } // namespace ucbhelper
 448
 449 #endif /* ! INCLUDED_UCBHELPER_CONTENTHELPER_HXX */
 450
 451 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */