Arxx::Archive Class Reference

#include <Archive.h>

Collaboration diagram for Arxx::Archive:

[legend]List of all members.

---

Detailed Description

The Arxx::Archive class is a container for an arbitrary amount of Arxx::Item objects.

The main purpose of Arxx::Archive is to handle input and output from and to ARX archives. But it also is responsible for the management of unique IDs and lets you access items you only know by ID.

In order to be able to manage input and output Arxx::Archive provides two functions: Arxx::Archive::bLoad() and Arxx::Archive::vSave().

Public Types
typedef std::map< Arxx::u4byte, Arxx::Item * >::size_type	size_type
Public Member Functions
	Archive (void)
	The default constructor.
	Archive (Arxx::ItemFactory &ItemFactory)
	The default constructor with the ability to define an Item factory for this archive.
virtual	~Archive (void)
	The destructor for a Arxx::Archive.
bool	bLoad (Arxx::URI URI)
	Load the content of an ARX archive into this Arxx::Archive.
bool	bMerge (Arxx::Archive &Archive, std::vector< Arxx::Rule * > &Rules)
	Merge the content of another Arxx::Archive into this Arxx::Archive.
void	vSave (Arxx::URI URI, bool bAutoCompress=false)
	Saves the content to an ARX archive.
void	vClose (void)
	Closes the Archive.
void	vRegisterItem (Arxx::Item &Item)
	Registers an Item to be a part of an Archive.
void	vUnregisterItem (Arxx::Item &Item)
	Unregisters an Item.
void	vSetRootItem (Item *pItem)
	Sets a root Item.
Arxx::ItemFactory *	pGetItemFactory (void)
	This function returns the m_pItemFactory member.
Arxx::Item *	pGetItem (Arxx::u4byte u4UniqueID)
	This function finds the Item associated with a given unique ID.
const Arxx::Item *	pGetItem (Arxx::u4byte u4UniqueID) const
	This function finds the Item associated with a given unique ID.
Arxx::Item *	pGetRootItem (void)
	Provides access to the root Item.
const Arxx::Item *	pGetRootItem (void) const
	Provides const access to the root Item.
Arxx::Reference	GetReference (Arxx::u4byte u4UniqueID)
	Returns a Arxx::Reference for a given unique ID.
Arxx::Archive::iterator	begin (void)
	Returns a Arxx::Archive::iterator to the first Item.
Arxx::Archive::iterator	end (void)
	Returns a Arxx::Archive::iterator behind the last Item.
Arxx::Archive::const_iterator	begin (void) const
	Returns a Arxx::Archive::const_iterator to the first Item.
Arxx::Archive::const_iterator	end (void) const
	Returns a Arxx::Archive::const_iterator behind the last Item.
Arxx::Archive::size_type	size (void) const
	Returns the number of Item objects.
Arxx::u4byte	u4GetNumberOfReferences (void) const
	Returns the number of resolved and unresolved references in the Archive.
void	vReleaseReference (Arxx::ReferenceImplementation *pReference)
	This function releases a Reference inside the Archive.
Private Member Functions
	Archive (const Archive &Archive)
	No copy semantic.
Archive &	operator= (const Archive &Archive)
	No assignment semantic.
void	vRead (Arxx::LocalArchiveChannel *pLocalArchiveChannel, Arxx::u4byte u4ItemCount)
	The reader function that retrieves Item header information from a channel.
Private Attributes
std::map< Arxx::u4byte, Arxx::Item * >	m_Items
std::map< Arxx::u4byte, Arxx::Reference >	m_References
Arxx::Item *	m_pRootItem
Arxx::ItemFactory *	m_pItemFactory
Classes
class	const_iterator
	An iterator class defining basic operations to iterate the Arxx::Item objects in an Arxx::Archive. More...
class	iterator
	An iterator class defining basic operations to iterate the Arxx::Item objects in an archive. More...

---

Member Typedef Documentation

typedef std::map< Arxx::u4byte, Arxx::Item * >::size_type Arxx::Archive::size_type

---

Constructor & Destructor Documentation

Arxx::Archive::Archive

(

void

)

The default constructor.

This constructor creates and initializes a Arxx::Archive. It will set the m_pItemFactory to the global default Item factory which is of type Arxx::DefaultItemFactory.

Arxx::Archive::Archive

(

Arxx::ItemFactory &

ItemFactory

)

The default constructor with the ability to define an Item factory for this archive.

Parameters:

ItemFactory

A reference to the Item factory that should be used for this archive.

This constructor creates and initializes a Arxx::Archive.

Arxx::Archive::~Archive

(

void

)

[virtual]

The destructor for a Arxx::Archive.

The destructor will call Arxx::Archive::vClose().

Arxx::Archive::Archive

(

const Archive &

Archive

)

[private]

No copy semantic.

---

Member Function Documentation

Arxx::Archive::const_iterator Arxx::Archive::begin

(

void

)

const

Returns a Arxx::Archive::const_iterator to the first Item.

This function is provided so you can iterate through all the Item objects registered in a const Archive. It follows STL standards.

Arxx::Archive::iterator Arxx::Archive::begin

(

void

)

Returns a Arxx::Archive::iterator to the first Item.

This function is provided so you can iterate through all the Item objects registered in an Archive. It follows STL standards.

bool Arxx::Archive::bLoad

(

Arxx::URI

URI

)

Load the content of an ARX archive into this Arxx::Archive.

Parameters:

URI

The URI defining the location of the ARXX archive to load.

Returns:

A boolean value indicating whether the ARX archive could be loaded or not. An error can have many reasons (file existance, permissions and content) but there is no facility to report which error occured. If you feel a need for it, please notify me.

This function tries to load the ARX archive at the location indicated by URI. If the archive is found and could be opened, the current content of the Arxx::Archive will be closed (via Arxx::Archive::vClose()). Note that if the archive proves to be no valid ARX archive the current content is not available anymore.

Note:

Since there is no such thing as relative paths in URI format, you always have to supply absolute paths to the ARX archives you want to load.

The URI is passed by value because the scheme may be left out and will be rewritten defaulting to "file". Therefore a copy has to be taken anyway.

bool Arxx::Archive::bMerge	(	Arxx::Archive &	Archive,
		std::vector< Arxx::Rule * > &	Rules
	)

Merge the content of another Arxx::Archive into this Arxx::Archive.

Parameters:

	Archive	The other archive that is to be merge into this one.
	Rules	A vector of Arxx::Rule objects which constitute the constraints for the merging process.

In essence this function is very simple and straight forward. It will iterate through the Arxx:Item objects in Archive and will subject every Item to the rules defined in Rules. The rules will be processed sequentially beginning with Rules.begin(). Processing a rule is done by at least matching it against the current context and if the rule indeed matched the context by returning the rule's action to the merger.

See also:

Rule, Action, Context.

Arxx::Archive::const_iterator Arxx::Archive::end

(

void

)

const

Returns a Arxx::Archive::const_iterator behind the last Item.

This function is provided so you can iterate through all the Item objects registered in a const Archive. It follows STL standards.

Arxx::Archive::iterator Arxx::Archive::end

(

void

)

Returns a Arxx::Archive::iterator behind the last Item.

This function is provided so you can iterate through all the Item objects registered in an Archive. It follows STL standards.

Arxx::Reference Arxx::Archive::GetReference

(

Arxx::u4byte

u4UniqueID

)

Returns a Arxx::Reference for a given unique ID.

Parameters:

u4UniqueID

The unique ID which you will get a Arxx::Reference for.

If a Arxx::Item object with the given unique ID is registered in the Archive the Reference will be resolved. If no such Item is registered the Reference will be unresolved, but will be linked to the Archive, so that, once an Item with that unique ID is registered at the Archive, the Reference will be resolved.

Archive& Arxx::Archive::operator=

(

const Archive &

Archive

)

[private]

No assignment semantic.

const Arxx::Item * Arxx::Archive::pGetItem

(

Arxx::u4byte

u4UniqueID

)

const

This function finds the Item associated with a given unique ID.

Parameters:

u4UniqueID

The unique ID of an Item which is to be found in the Archive.

If the unique ID is not known in the Archive this function will return 0.

Note:

This function guarantees to be of complexity in O(log(n)) where n is the number of Item objects in the Archive.

Arxx::Item * Arxx::Archive::pGetItem

(

Arxx::u4byte

u4UniqueID

)

This function finds the Item associated with a given unique ID.

Parameters:

u4UniqueID

The unique ID of an Item which is to be found in the Archive.

If the unique ID is not known in the Archive the function will return 0.

Note:

This function guarantees to be of complexity in O(log(n)) where n is the number of Item objects in the Archive.

Arxx::ItemFactory * Arxx::Archive::pGetItemFactory

(

void

)

This function returns the m_pItemFactory member.

const Arxx::Item * Arxx::Archive::pGetRootItem

(

void

)

const

Provides const access to the root Item.

This function returns the m_pRootItem member of the Archive, so if the Archive has no root Item set the function will return 0.

Arxx::Item * Arxx::Archive::pGetRootItem

(

void

)

Provides access to the root Item.

This function returns the m_pRootItem member of the Archive, so if the Archive has no root Item set the function will return 0.

Arxx::Archive::size_type Arxx::Archive::size

(

void

)

const

Returns the number of Item objects.

This function returns the number of Arxx::Item objects registered in the Archive. It is designed to be STL compatible.

Arxx::u4byte Arxx::Archive::u4GetNumberOfReferences

(

void

)

const

Returns the number of resolved and unresolved references in the Archive.

void Arxx::Archive::vClose

(

void

)

Closes the Archive.

Closing an Archive means purging it of all Arxx::Item objects. All Item objects in the Archive will be deleted by their respective Arxx::ItemFactory objects. If an Item has no associated Arxx::ItemFactory set it won't get deleted since the Archive does not know how. In most cases this will be true for Items on the stack but may also be true for wrongly done ItemFactory derivates.

Note:

Not every ItemFactory, that does not set an Item's ItemFactory member correctly on creation, can be considered 'wrong'. If the ItemFactory still has references to the Items, it is absolutely perfect for having persistent Items inside an Archive.

void Arxx::Archive::vRead	(	Arxx::LocalArchiveChannel *	pLocalArchiveChannel,
		Arxx::u4byte	u4ItemCount
	)			[private]

The reader function that retrieves Item header information from a channel.

Todo:

Since we don't save parent external data IDs yet this is safe, but we have to handle it.

Todo:

Here the handling of the data sizes and compression state from the ItemHeader is missing.

void Arxx::Archive::vRegisterItem

(

Arxx::Item &

Item

)

Registers an Item to be a part of an Archive.

Parameters:

Item

A reference to the Item that is to be registerd.

Exceptions:

std::invalid_argument

If Item is already registered at another Archive.

First of all this function will check whether the item is already assigned to an Archive and will throw an exception of type std::invalid_argument.

If the Item is not yet registered at another Archive, this function will set Arxx::Item::m_pArchive to point to this Archive.

If the Item is not yet associated to any Arxx::Archive this function will decide on one of the following behavior, depending on whether the unique ID of Item is equal to g_u4InvalidID or not.

• If the unique ID is equal to g_u4InvalidID this function will search for a unique ID not yet used inside this Archive.
• If the unique ID is any other value, this function will allow the registration if that ID is not yet used by another item in this Archive. Not alowing a registration means to throw an exception of the type Arxx::id_not_unique.

Todo:

the following is the brute force implementation. It can be done much faster with a merge sort

void Arxx::Archive::vReleaseReference

(

Arxx::ReferenceImplementation *

pReference

)

This function releases a Reference inside the Archive.

This is an internal function, but as the API user will never lay hands on a Arxx::ReferenceImplementation object it is still public to avoid friend declarations.

This function is called whenever the reference count of an unresolved Arxx::ReferenceImplementation object reaches `1`, because in that case the associated Archive object is the only reference holder of the ReferenceImplementation object. Since unresolved References serve no purpose other than to be resolved magically there is no sense in keeping it only inside the Archive.

This function will retrieve the associated Reference object and will remove it from the m_References map thus releasing the ReferenceImplementation object which then is deleted.

void Arxx::Archive::vSave	(	Arxx::URI	URI,
		bool	bAutoCompress = false
	)

Saves the content to an ARX archive.

Parameters:

	URI	The URI you want the ARX archive saved to.
	bAutoCompress	Whether all Arxx::Item objects should be auto-compressed.

Exceptions:

	Arxx::invalid_argument	If the given URI is non-valid.
	Arxx::file_error	If the temporary archive in /tmp cannot be created for writing.

Given a URI, the content of an Arxx::Archive instance will be saved to the location it indicates. The target will be overwritten if it exists but only after it has been fully assembled in a temporary archive. The temorary archive will be stored under "/tmp/" with the name "ARX" followed by the timestamp. After the saving process to that temporary file it will be moved to the target location, using the command `mv --force PathToTemporaryFile URI`

void Arxx::Archive::vSetRootItem

(

Item *

pItem

)

Sets a root Item.

Parameters:

pItem

A pointer to a Arxx::Item that is to be set as the Archive's root Item or 0.

Exceptions:

std::invalid_argument

If the Item that pItem points to is not registered in the Archive.

This function will modify the m_pRootItem member of the Archive setting it to pItem.

You may pass pItem `0` to unset the root Item of the Archive.

void Arxx::Archive::vUnregisterItem

(

Arxx::Item &

Item

)

Unregisters an Item.

Parameters:

Item

A reference to the Item that is to be unregisterd.

Exceptions:

std::invalid_argument

If Item is not registered in the Archive.

This function will remove Item from an Archive by erasing the appropriate iterator from the Item object container owned by the Archive.

If Item is not correctly registered in the Archive an std::invalid_argument exception is thrown.

Note:

This function will change Item! Note that Item's Arxx::Item::m_pArchive field will be set to `0` if no errors occure.

---

Member Data Documentation

std::map< Arxx::u4byte, Arxx::Item * > Arxx::Archive::m_Items [private]

Arxx::ItemFactory* Arxx::Archive::m_pItemFactory [private]

Arxx::Item* Arxx::Archive::m_pRootItem [private]

std::map< Arxx::u4byte, Arxx::Reference > Arxx::Archive::m_References [private]

---

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

• Archive.h
• Archive.cxx

---