comphelper::NumberedCollection Class Reference

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< sal_IntPtr, TNumberedItem >	TNumberedItemHash
typedef ::std::vector< sal_IntPtr >	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...
std::mutex	m_aMutex

Detailed Description

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

@descr 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.

@threadsafe

Definition at line 47 of file numberedcollection.hxx.

Member Typedef Documentation

TDeadItemList

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

private

Definition at line 64 of file numberedcollection.hxx.

TNumberedItemHash

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

private

Definition at line 62 of file numberedcollection.hxx.

Constructor & Destructor Documentation

NumberedCollection()

comphelper::NumberedCollection::NumberedCollection

(

)

lightweight constructor.

Definition at line 30 of file numberedcollection.cxx.

~NumberedCollection()

comphelper::NumberedCollection::~NumberedCollection ( )

overridevirtual

free all internally used resources.

Definition at line 35 of file numberedcollection.cxx.

Member Function Documentation

getUntitledPrefix()

OUString SAL_CALL comphelper::NumberedCollection::getUntitledPrefix ( )

overridevirtual

See also

css.frame.XUntitledNumbers

Definition at line 156 of file numberedcollection.cxx.

References aLock, m_aMutex, and m_sUntitledPrefix.

impl_cleanUpDeadItems()

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

staticprivate

Definition at line 202 of file numberedcollection.cxx.

Referenced by releaseNumber().

impl_searchFreeNumber()

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 ... e.g.

@descr 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.

{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 179 of file numberedcollection.cxx.

References find(), m_lComponents, and pos.

Referenced by leaseNumber().

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 62 of file numberedcollection.cxx.

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

releaseNumber()

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

overridevirtual

See also

css.frame.XUntitledNumbers

Definition at line 97 of file numberedcollection.cxx.

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

releaseNumberForComponent()

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

overridevirtual

See also

css.frame.XUntitledNumbers

Definition at line 134 of file numberedcollection.cxx.

References aLock, comphelper::ERRMSG_INVALID_COMPONENT_PARAM, m_aMutex, m_lComponents, and m_xOwner.

setOwner()

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 40 of file numberedcollection.cxx.

References aLock, m_aMutex, and m_xOwner.

setUntitledPrefix()

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 51 of file numberedcollection.cxx.

References aLock, m_aMutex, m_sUntitledPrefix, and sPrefix.

Member Data Documentation

m_aMutex

std::mutex comphelper::NumberedCollection::m_aMutex

private

Definition at line 161 of file numberedcollection.hxx.

Referenced by getUntitledPrefix(), leaseNumber(), releaseNumber(), releaseNumberForComponent(), setOwner(), and setUntitledPrefix().

m_lComponents

TNumberedItemHash comphelper::NumberedCollection::m_lComponents

private

cache of all "leased numbers" and its bound components

Definition at line 156 of file numberedcollection.hxx.

Referenced by impl_searchFreeNumber(), leaseNumber(), releaseNumber(), and releaseNumberForComponent().

m_sUntitledPrefix

OUString comphelper::NumberedCollection::m_sUntitledPrefix

private

localized string to be used for untitled components

Definition at line 153 of file numberedcollection.hxx.

Referenced by getUntitledPrefix(), and setUntitledPrefix().

m_xOwner

css::uno::WeakReference< css::uno::XInterface > comphelper::NumberedCollection::m_xOwner

private

used as source of broadcasted messages or exceptions (can be null !)

Definition at line 159 of file numberedcollection.hxx.

Referenced by leaseNumber(), releaseNumber(), releaseNumberForComponent(), and setOwner().

---

The documentation for this class was generated from the following files:

• numberedcollection.hxx
• numberedcollection.cxx