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