include/comphelper/numberedcollection.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_COMPHELPER_NUMBEREDCOLLECTION_HXX
  21 #define INCLUDED_COMPHELPER_NUMBEREDCOLLECTION_HXX
  22
  23 #include <comphelper/comphelperdllapi.h>
  24
  25 #include <com/sun/star/uno/Reference.h>
  26 #include <com/sun/star/frame/XUntitledNumbers.hpp>
  27
  28 #include <cppuhelper/basemutex.hxx>
  29 #include <cppuhelper/weakref.hxx>
  30 #include <cppuhelper/implbase.hxx>
  31
  32 #include <unordered_map>
  33 #include <vector>
  34
  35 namespace com::sun::star::uno { class XInterface; }
  36
  37 namespace comphelper{
  38
  39 /** @short  defines a collection of UNO components, where every component will get its own unique number.
  40
  41     @descr  Such number will be unique at runtime only... but it supports fragmentation.
  42             Note: This collection uses weak references only to know her components.
  43             So lifetime of these components must be controlled outside.
  44
  45     @threadsafe
  46  */
  47 class COMPHELPER_DLLPUBLIC NumberedCollection final : private ::cppu::BaseMutex
  48                                               , public  ::cppu::WeakImplHelper< css::frame::XUntitledNumbers >
  49 {
  50
  51     // types, const
  52     private:
  53
  54         struct TNumberedItem
  55         {
  56             css::uno::WeakReference< css::uno::XInterface > xItem;
  57             ::sal_Int32 nNumber;
  58         };
  59
  60         typedef std::unordered_map<
  61                     sal_IntPtr,
  62                     TNumberedItem  > TNumberedItemHash;
  63
  64         typedef ::std::vector< sal_IntPtr > TDeadItemList;
  65
  66
  67     // interface
  68     public:
  69
  70
  71         /** @short  lightweight constructor.
  72          */
  73         NumberedCollection();
  74
  75
  76         /** @short  free all internally used resources.
  77          */
  78         virtual ~NumberedCollection() override;
  79
  80
  81         /** set an outside component which uses this container and must be set
  82             as source of all broadcasted messages, exceptions.
  83
  84             It's holded weak only so we do not need any complex dispose sessions.
  85
  86             Note: Passing NULL as parameter will be allowed. It will reset the internal
  87             member reference only.
  88
  89             @param  xOwner
  90                     the new owner of this collection.
  91          */
  92         void setOwner (const css::uno::Reference< css::uno::XInterface >& xOwner);
  93
  94
  95         /** set the localized prefix to be used for untitled components.
  96
  97             Localization has to be done outside. This container will return
  98             those value then. There are no further checks. Its up to you to define
  99             a suitable string here :-)
 100
 101             @param  sPrefix
 102                     the new prefix for untitled components.
 103          */
 104         void setUntitledPrefix(const OUString& sPrefix);
 105
 106
 107         /** @see css.frame.XUntitledNumbers */
 108         virtual ::sal_Int32 SAL_CALL leaseNumber(const css::uno::Reference< css::uno::XInterface >& xComponent) override;
 109
 110
 111         /** @see css.frame.XUntitledNumbers */
 112         virtual void SAL_CALL releaseNumber(::sal_Int32 nNumber) override;
 113
 114
 115         /** @see css.frame.XUntitledNumbers */
 116         virtual void SAL_CALL releaseNumberForComponent(const css::uno::Reference< css::uno::XInterface >& xComponent) override;
 117
 118
 119         /** @see css.frame.XUntitledNumbers */
 120         virtual OUString SAL_CALL getUntitledPrefix() override;
 121
 122
 123     // internal
 124     private:
 125
 126
 127         /** @short  tries to find a unique number not already used within this collection.
 128
 129             @descr  It reuses the smallest number which isn't used by any component
 130                     of this collection. (fragmentation!) If collection is full (means there
 131                     is no free number) the special value INVALID_NUMBER will be returned.
 132
 133             @note   Those method can't be called within a multithreaded environment.
 134                     Because such number won't be "reserved" for the call of these method
 135                     it can happen that two calls returns the same number (reasoned by the fact that first call
 136                     doesn't used the returned number already.
 137
 138                     So the outside code has to make sure that retrieving and using of those numbers
 139                     will be an atomic operation.
 140
 141             @return a unique number or special value INVALID_NUMBER if collection is full.
 142          */
 143         ::sal_Int32 impl_searchFreeNumber ();
 144
 145         static void impl_cleanUpDeadItems (      TNumberedItemHash& lItems    ,
 146                                            const TDeadItemList&     lDeadItems);
 147
 148
 149     // member
 150     private:
 151
 152         /// localized string to be used for untitled components
 153         OUString m_sUntitledPrefix;
 154
 155         /// cache of all "leased numbers" and its bound components
 156         TNumberedItemHash m_lComponents;
 157
 158         /// used as source of broadcasted messages or exceptions (can be null !)
 159         css::uno::WeakReference< css::uno::XInterface > m_xOwner;
 160 };
 161
 162 } // namespace comphelper
 163
 164 #endif // INCLUDED_COMPHELPER_NUMBEREDCOLLECTION_HXX
 165
 166 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */