dynamicgraph::FactoryStorage Class Reference

Provides a way to create Entity objects from their class name. More...

#include <dynamic-graph/factory.h>

Inheritance diagram for dynamicgraph::FactoryStorage:

Collaboration diagram for dynamicgraph::FactoryStorage:

Public Types
typedef Entity *(*	EntityConstructor_ptr) (const std::string &)
	Function pointer providing an entity instance from its name. More...

Public Member Functions
	~FactoryStorage ()
void	registerEntity (const std::string &entname, EntityConstructor_ptr ent)
	Add a new entity to the factory. More...
void	deregisterEntity (const std::string &entname)
	Delete an entity from the factory. More...
Entity *	newEntity (const std::string &classname, const std::string &objname) const
	Instantiate (and allocate) an entity. More...
bool	existEntity (const std::string &name) const
	Check if an Entity associated with a particular name has already been registered. More...
void	listEntities (std::vector< std::string > &list) const
	List the available entities. More...

Static Public Member Functions
static FactoryStorage *	getInstance ()
	Get pointer to unique object of the class. More...
static void	destroy ()
	Destroy the unique instance of the class. More...

Detailed Description

Provides a way to create Entity objects from their class name.

The dynamic graph frameworks relies on entities (see Entity) which defines atomic processing units. This class provides a robust way to enumerate and instantiate these entities. Each entity has a name (its type name) and can be instantiated. Each instance also has a name.

For instance one can define a C++ class called MyEntity which inherits from dynamicgraph::Entity. This type can be registered into the factory to teach the framework that:

• this entity exists
• this entity can be instantiated (and how to instantiate it).

To achieve this, one must pass an entity name and a function pointer.

The entity name will identify the class at run-time (be careful: this may not be equivalent to the C++ class name even if it is recommended to do so).

The function pointer must point on a function taking a string as input and returning an instance of the Entity (the concrete subclass, not directly the upper Entity class).

The instances returned by this function must be dynamically allocated and the caller must get the ownership of the instance (i.e. it will free it when required).

To finish, please note that the instance name indicates to the entity how the instance itself is called at run-time. This name does not need to be unique and no check is done on it. It is the caller responsibility to make sure that the instance name is appropriate and to check for uniqueness if required.

This class is a singleton. The rationale is that each unique name must identify a unique Entity. The use of a single instance of this class enforces this behavior, instantiating one yourself would break this property.

Member Typedef Documentation

typedef Entity*(* dynamicgraph::FactoryStorage::EntityConstructor_ptr) (const std::string &)

Function pointer providing an entity instance from its name.

Constructor & Destructor Documentation

dynamicgraph::FactoryStorage::~FactoryStorage

(

)

Member Function Documentation

void dynamicgraph::FactoryStorage::deregisterEntity

(

const std::string &

entname

)

Delete an entity from the factory.

If the provided entity name does not exist in the factory, an ExceptionFactory exception will be raised with the code OBJECT_CONFLICT.

Parameters

entname

the entity name (as passed to registerEntity before)

static void dynamicgraph::FactoryStorage::destroy ( )

static

Destroy the unique instance of the class.

bool dynamicgraph::FactoryStorage::existEntity

(

const std::string &

name

)

const

Check if an Entity associated with a particular name has already been registered.

Parameters

name	entity name

Returns

Do the entity exist?

static FactoryStorage* dynamicgraph::FactoryStorage::getInstance ( )

static

Get pointer to unique object of the class.

void dynamicgraph::FactoryStorage::listEntities

(

std::vector< std::string > &

list

)

const

List the available entities.

Available entities are appended to the method argument.

Parameters

list	Available entities will be appended to list.

Entity* dynamicgraph::FactoryStorage::newEntity	(	const std::string &	classname,
		const std::string &	objname
	)		const

Instantiate (and allocate) an entity.

An instance called objname of the entity which type is classname will be allocated by this method.

It is the caller responsibility to free the returned object.

If the class name does not exist, an ExceptionFactory exception will be raised with the code UNREFERED_OBJECT.

The instance name (objname) is passed to the Entity constructor and it is the caller responsibility to avoid instance name conflicts if necessary.

Parameters

classname	the name of the Entity type
objname	the instance name

Returns

Dynamically allocated instance of classname.

void dynamicgraph::FactoryStorage::registerEntity	(	const std::string &	entname,
		EntityConstructor_ptr	ent
	)

Add a new entity to the factory.

It is not allowed to have several entities using the same name. If this is the case, an ExceptionFactory exception will be raised with the code OBJECT_CONFLICT.

If the function pointer is null, an ExceptionFactory exception will be raised with the code OBJECT_CONFLICT.

Parameters

entname	the name used to subscribe the entity.
ent	pointer to a function allocating an entity from an instance name.