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