defines a collection of UNO components, where every component will get its own unique number. More...

#include <numberedcollection.hxx>

Inheritance diagram for comphelper::NumberedCollection:

Collaboration diagram for comphelper::NumberedCollection:

Classes
struct	TNumberedItem

Public Member Functions
	NumberedCollection ()
	lightweight constructor. More...

virtual	~NumberedCollection () override
	free all internally used resources. More...

void	setOwner (const css::uno::Reference< css::uno::XInterface > &xOwner)
	set an outside component which uses this container and must be set as source of all broadcasted messages, exceptions. More...

void	setUntitledPrefix (const OUString &sPrefix)
	set the localized prefix to be used for untitled components. More...

virtual ::sal_Int32 SAL_CALL	leaseNumber (const css::uno::Reference< css::uno::XInterface > &xComponent) override

virtual void SAL_CALL	releaseNumber (::sal_Int32 nNumber) override

virtual void SAL_CALL	releaseNumberForComponent (const css::uno::Reference< css::uno::XInterface > &xComponent) override

virtual OUString SAL_CALL	getUntitledPrefix () override

Private Types
typedef std::unordered_map< long, TNumberedItem >	TNumberedItemHash

typedef ::std::vector< long >	TDeadItemList

Private Member Functions
::sal_Int32	impl_searchFreeNumber ()
	tries to find a unique number not already used within this collection. More...

Static Private Member Functions
static void	impl_cleanUpDeadItems (TNumberedItemHash &lItems, const TDeadItemList &lDeadItems)

Private Attributes
OUString	m_sUntitledPrefix
	localized string to be used for untitled components More...

TNumberedItemHash	m_lComponents
	cache of all "leased numbers" and its bound components More...

css::uno::WeakReference< css::uno::XInterface >	m_xOwner
	used as source of broadcasted messages or exceptions (can be null !) More...

Private Attributes inherited from cppu::BaseMutex
mutable::osl::Mutex	m_aMutex

Detailed Description

defines a collection of UNO components, where every component will get its own unique number.

Such number will be unique at runtime only... but it supports fragmentation. Note: This collection uses weak references only to know her components. So lifetime of these components must be controlled outside.

Definition at line 47 of file numberedcollection.hxx.

Member Typedef Documentation

typedef ::std::vector< long > comphelper::NumberedCollection::TDeadItemList

private

Definition at line 64 of file numberedcollection.hxx.

typedef std::unordered_map< long, TNumberedItem > comphelper::NumberedCollection::TNumberedItemHash

private

Definition at line 62 of file numberedcollection.hxx.

Constructor & Destructor Documentation

comphelper::NumberedCollection::NumberedCollection ( )

lightweight constructor.

Definition at line 30 of file numberedcollection.cxx.

comphelper::NumberedCollection::~NumberedCollection ( )

overridevirtual

free all internally used resources.

Definition at line 39 of file numberedcollection.cxx.

Member Function Documentation

OUString SAL_CALL comphelper::NumberedCollection::getUntitledPrefix ( )

overridevirtual

See also: css.frame.XUntitledNumbers

Definition at line 160 of file numberedcollection.cxx.

References aLock, cppu::BaseMutex::m_aMutex, and m_sUntitledPrefix.

void comphelper::NumberedCollection::impl_cleanUpDeadItems	(	TNumberedItemHash &	lItems,
		const TDeadItemList &	lDeadItems
	)

staticprivate

Definition at line 229 of file numberedcollection.cxx.

Referenced by impl_searchFreeNumber(), and releaseNumber().

sal_Int32 comphelper::NumberedCollection::impl_searchFreeNumber ( )

private

tries to find a unique number not already used within this collection.

create an ordered list of all possible numbers ...

It reuses the smallest number which isn't used by any component of this collection. (fragmentation!) If collection is full (means there is no free number) the special value INVALID_NUMBER will be returned.

Note: Those method can't be called within a multithreaded environment. Because such number won't be "reserved" for the call of these method it can happen that two calls returns the same number (reasoned by the fact that first call doesn't used the returned number already.

So the outside code has to make sure that retrieving and using of those numbers will be an atomic operation.

Returns: a unique number or special value INVALID_NUMBER if collection is full.

e.g. {1,2,3,...,N} Max size of these list will be current size of component list + 1 .

"+1" ... because in case all numbers in range 1..n are in use we need a new number n+1 :-)

Every item which is already used as unique number will be removed. At the end a list of e.g. {3,6,...,M} exists where the first item represent the lowest free number (in this example 3).

Definition at line 183 of file numberedcollection.cxx.

References aLock, i, impl_cleanUpDeadItems(), cppu::BaseMutex::m_aMutex, and m_lComponents.

Referenced by leaseNumber().

sal_Int32 SAL_CALL comphelper::NumberedCollection::leaseNumber ( const css::uno::Reference< css::uno::XInterface > & xComponent )

override

See also: css.frame.XUntitledNumbers

Definition at line 66 of file numberedcollection.cxx.

References aLock, impl_searchFreeNumber(), cppu::BaseMutex::m_aMutex, m_lComponents, m_xOwner, comphelper::NumberedCollection::TNumberedItem::nNumber, and comphelper::NumberedCollection::TNumberedItem::xItem.

void SAL_CALL comphelper::NumberedCollection::releaseNumber ( ::sal_Int32 nNumber )

overridevirtual

See also: css.frame.XUntitledNumbers

Definition at line 101 of file numberedcollection.cxx.

References aLock, impl_cleanUpDeadItems(), cppu::BaseMutex::m_aMutex, m_lComponents, m_xOwner, comphelper::NumberedCollection::TNumberedItem::nNumber, and comphelper::NumberedCollection::TNumberedItem::xItem.

void SAL_CALL comphelper::NumberedCollection::releaseNumberForComponent ( const css::uno::Reference< css::uno::XInterface > & xComponent )

overridevirtual

See also: css.frame.XUntitledNumbers

Definition at line 138 of file numberedcollection.cxx.

References aLock, cppu::BaseMutex::m_aMutex, m_lComponents, and m_xOwner.

void comphelper::NumberedCollection::setOwner ( const css::uno::Reference< css::uno::XInterface > & xOwner )

set an outside component which uses this container and must be set as source of all broadcasted messages, exceptions.

It's holded weak only so we do not need any complex dispose sessions.

Note: Passing NULL as parameter will be allowed. It will reset the internal member reference only.

Parameters

xOwner the new owner of this collection.

Definition at line 44 of file numberedcollection.cxx.

References aLock, cppu::BaseMutex::m_aMutex, and m_xOwner.

void comphelper::NumberedCollection::setUntitledPrefix ( const OUString & sPrefix )

set the localized prefix to be used for untitled components.

Localization has to be done outside. This container will return those value then. There are no further checks. Its up to you to define a suitable string here :-)

Parameters

sPrefix the new prefix for untitled components.

Definition at line 55 of file numberedcollection.cxx.

References aLock, cppu::BaseMutex::m_aMutex, m_sUntitledPrefix, and sPrefix.