Accessor Class Reference

#include <adskDataAccessor.h>

Class Description

Class used to read and write metadata from/to an existing file.

This class is used to read and rewrite a collection of adsk::Data::Structure and adsk::Data::Associations from/to an existing file.

Examples:

Classes
struct	StructureNameLessThan
	Functor for Structure ordering in a std::set. More...

Public Types
typedef std::set< const Structure *, StructureNameLessThan >	StructureSet
	Structures are kept in a set that forbids duplicated names.
typedef std::map< std::string, Associations >	AssociationsMap
	Associations are kept in a map that forbids duplicated names. More...

Public Member Functions
virtual	~Accessor ()
	Releases any Structure and Associations objects currently held. More...
bool	read (const std::string &fileName, std::string &errors)
	Reads all the structures and associations from the specified file. More...
bool	read (const std::string &fileName, const std::set< std::string > *wantedStructures, const std::set< std::string > *wantedAssociations, std::string &errors)
	Reads the structures and specified associations from the file. More...
virtual bool	write (std::string &errors) const
	Rewrites the file with the edited structures and associations. More...
virtual bool	isFileSupported (const std::string &fileName) const
	Returns whether the file passed in is supported by this accessor. More...
const std::string &	fileName () const
	Returns the file name passed to the last invocation of read(). More...
const StructureSet &	structures () const
	Get the adsk::Data::Structures currently held by this instance. More...
void	setStructures (const StructureSet &structures)
	Changes the adsk::Data::Structures currently held by this class. More...
const AssociationsMap &	associations () const
	Get the adsk::Data::Associations currently held by this instance. More...
AssociationsMap &	associations ()
	Get the adsk::Data::Associations currently held by this instance. More...
void	clear ()
	Clears the structures and associations present in the instance. More...

Static Public Member Functions
static std::set< std::string >	supportedExtensions ()
	Returns the supported filename extensions. More...
static std::auto_ptr< Accessor >	accessorByExtension (const std::string &extension)
	Creates and returns an accessor to handle the specified extension. More...
static std::auto_ptr< Accessor >	readFile (const std::string &fileName, std::string &errors)
	Creates and returns an accessor that can handle the specified file. More...

Protected Member Functions
	Accessor ()
	Constructs an empty accessor. More...
virtual bool	performRead (const std::set< std::string > *wantedStructures, const std::set< std::string > *wantedAssociations, std::string &errors)=0
	Invoked by read() to access the current file. More...

Member Typedef Documentation

typedef std::map< std::string, Associations > AssociationsMap

Associations are kept in a map that forbids duplicated names.

The actual file format defines the semantic for the Associations names. For example, for certain formats, an empty-name may mean file-level associations rather than per-object associations.

Constructor & Destructor Documentation

~Accessor ( )

virtual

Releases any Structure and Associations objects currently held.

If the object gets destroyed before any call to write() is made, the changes will be dropped without any change done to the file.

Accessor ( )

protected

Constructs an empty accessor.

Upon construction, the accessor is not bound to any file. Calls to read() will load the Structure/Associations object from a given file, provided they are of the format supported by this instance.

Member Function Documentation

bool read	(	const std::string &	fileName,
		std::string &	errors
	)

Reads all the structures and associations from the specified file.

Structures and associations are read into the current accessor instance and can then be read and changed through other methods in this API prior to rewriting them in the file, if needed, through write().

Previous data will be cleared and will not be written to the previous file. Unseccessful read will cause the structures and associations to be emptied, but the new file name will stay.

Parameters

[in]	fileName	Name of the file to open and read the structures/associations from.
[out]	errors	Errors that happened during reading, if any.

Returns

true if the read was sucessful.

bool read	(	const std::string &	fileName,
		const std::set< std::string > *	wantedStructures,
		const std::set< std::string > *	wantedAssociations,
		std::string &	errors
	)

Reads the structures and specified associations from the file.

The specified structures and associations are read into the current accessor instance and can then be read and changed through other methods in this API prior to rewriting them in the file, if needed, through write().

Passing in null pointers for the set of structure or association names will cause all of them to be read, respectively.

Writing a filtered set of associations back to the file will cause the ones that were not read to be removed from the file.

Previous data will be cleared and will not be written to the previous file. Unseccessful read will cause the structures and associations to be emptied, but the new file name will stay.

Parameters

[in]	fileName	Name of the file to open and read the structures/associations from.
[in]	wantedStructures	Name of the structures to be read. If null, all structures must be read.
[in]	wantedAssociations	Name of the associations to be read. If null, all asociations must be read. Associations for which one or more Structures were not read due to wantedStructures will not be read.
[out]	errors	Errors that happened during reading, if any.

Returns

true if the read was sucessful.

bool write ( std::string &  errors ) const

virtual

Rewrites the file with the edited structures and associations.

The file is changed in place, so if the caller requires any type of versioning, a copy of the original file must first be taken prior to this call as this does not do it. However, concrete implementations may choose to do so.

The default implementation does nothing and returns false.

Parameters

[out]

errors

Errors that happened during writing, if any.

Returns

false if there was an error while writing into the file.

bool isFileSupported ( const std::string &  fileName ) const

virtual

Returns whether the file passed in is supported by this accessor.

Accessors handle files based on their extension. However, some files having the expected extension may still be unsupported (e.g.: earlier version).

The default implementation returns true.

Parameters

[in]

fileName

File to inspect.

Returns

true if the file is supported by this accessor.

const std::string & fileName

(

)

const

Returns the file name passed to the last invocation of read().

Returns

The file name currently used. The reference stays valid until the next call to read().

const Accessor::StructureSet & structures

(

)

const

Get the adsk::Data::Structures currently held by this instance.

These are the structures found on the last call to read(), or that were set through setStructures.

Returns

A reference to the internal structures container. The container cannot be edited in place because structures are ref-counted by this class. The reference stays valid until the Accessor instance is destroyed.

void setStructures

(

const StructureSet &

structures

)

Changes the adsk::Data::Structures currently held by this class.

These are the Structures that will be written to the file when it will be written via write(). It is the caller's responsibility to make sure all structures used by the Associations found in this instance's Associations map are present in this set.

Previous adsk::Data::Structures will be unref()'ed, and the new structures will be ref()'ed.

Parameters

[in]

structures

The new structures.

const Accessor::AssociationsMap & associations

(

)

const

Get the adsk::Data::Associations currently held by this instance.

Returns

A reference to the internal associations container. The container cannot be edited through this reference, but any changes made through the non-const version of this accessor will be visible through the reference.

Examples:

Accessor::AssociationsMap & associations

(

)

Get the adsk::Data::Associations currently held by this instance.

Returns

A reference to the internal associations container. The container can be edited in place.

void clear

(

)

Clears the structures and associations present in the instance.

The file name stays unchanged.

std::set< std::string > supportedExtensions ( )

static

Returns the supported filename extensions.

For debugging or informational purposes. The extensions are converted to lowercase.

Returns

The supported filename extensions, in lowercase.

std::auto_ptr< Accessor > accessorByExtension ( const std::string &  extension )

static

Creates and returns an accessor to handle the specified extension.

Finds the factory whose extension matches the one passed in. For convenience, the string passed in will be treated as a filename and only the part following the '.', if any, will be kept.

If a match is found, a new Accessor is created with the factory's create() method. Otherwise, a null pointer is returned.

Parameters

[in]

extension

Extension to be handled by the returned accessor. Can be a filename.

Returns

Pointer to a new accessor if a matching extension was found. Returns a null pointer if no accessor could be found for this type.

std::auto_ptr< Accessor > readFile ( const std::string &  fileName, std::string &  errors  )

static

Creates and returns an accessor that can handle the specified file.

Finds the factory whose file name extension matches that of the file name passed in, if any, and creates a new Accessor with the factory's create() method. On success it calls read() on the Accessor and only returns the newly created Accessor if the read has succeeded.

Parameters

[in]	fileName	Name of the file to open and read.
[out]	errors	Errors that occured during file read, if any.

Returns

On success, returns an accesor with the file's data already read. Returns a null pointer if no accessor could be found for this type or reading the file fails.

bool performRead ( const std::set< std::string > *  wantedStructures, const std::set< std::string > *  wantedAssociations, std::string &  errors  )

protectedpure virtual

Invoked by read() to access the current file.

The current file's name is obtained with fileName(). Concrete implementations must read the specified structures/associations, if any, or all of them, otherwise. Upon success, the structures are read from adsk::Data::Structure::allStructures() and kept in this instance. The associations, on the other hand, must be set by the derived class by editing the associations map returned from associations().

The caller (the read() method) deals with saving/restoring the content of adsk::Data::Structure::allStructures() before/after the call, and clearing the existing structures/associations present in the instance before calling performRead().

Parameters

[in]	wantedStructures	Name of the structures to be read. If null, all structures must be read.
[in]	wantedAssociations	Name of the associations to be read. If null, all asociations must be read. Associations for which one or more Structures were not read due to wantedStructures will not be read.
[out]	errors	Errors that happended during reading, if any.

Returns

True upon success.

---

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

• adskDataAccessor.h
• adskDataAccessor.cpp