Phx::Description Class Reference

A base class for descriptions that are used as generic shared values describing all or part of an entity. More...

#include <PhxDescription.h>

Inheritance diagram for Phx::Description:

List of all members.

Public Types
typedef ValueType< TypeClass, uint32_t >	Type
	Each Description subclass is assigned a type constant which is used to identify the complete type at runtime.
Public Member Functions
virtual BitVector	serializedData (void) const =0
	Constructs and returns the serialized form of this Description.
virtual void	serializedData (const BitVector &serializedData)=0
	Given a serialized form of a description of this type, set this Description's attributes to match the serialized version.
Type	type () const
	Returns the Type constant for the subclass that this Description is an instance of.
Static Public Attributes
static const Type	INVALID_TYPE
	A sentinel Type constant used to indicate an invalid type.
Friends
class	Manager
Classes
class	Manager
	A manager accessory type to Description that keeps track of Description types and creates new instances. More...

---

Detailed Description

A base class for descriptions that are used as generic shared values describing all or part of an entity.

A Description is a piece of data that describes an entity. This data may come from either binary or XML serialized data (which itself may be acquired from disk, network, or elsewhere), or may simply be created and configured programatically. Descriptions are supplied to entities when they are constructed to specify what characteristics they should take on. In general, Descriptions may also specify only part of an entity. An entity would then use the Description to change only a subset of its attributes as appropriate.

Warning:

A VERY important characteristic of Descriptions is that they are shared values. They are not like entities; they are values, which, in order to facilitate sharing, are referenced by pointer. As such, they are not required to be thread safe. (Implementors: see below for one exception). However, Descriptions must also be mutable so that clients can construct and configure a description before using it. As a result, it is possible for one to modify a Description even when it is being used by (potentially many) other clients concurrently. This is expressly forbidden -- you must be absolutely certain that no other clients are using the Description when it is modified. Typically, one will construct a description via newDescription() and then modify its attributes as appropriate. At this point, no other object can reference the description, since it is new and the only pointer is held by the creating client. Once it is configured, you should immediately and irrevocably convert it to a const pointer to avoid accidental modifications later:

 class MyClass {
    void foo(void);
    Ptr<const Description>  mAircraftDescription;
 };
 
 
 void MyClass::foo(void) {

 // create mutable description
 Ptr<AircraftDescription> descriptionPtr = 
    descriptionMgr->newDescription(AircraftDescription::DESCRIPTION_TYPE).dynamicCast<AircraftDescription>();

 // set up attributes as necessary;  safe since we're the only client.
 descriptionPtr->xmlData(aircraftXmlData);
 ...

 // store the description in our Ptr<const Description> member,
 // thus giving up the ability to modify it through mAircraftDescription.
 mAircraftDescription = descriptionPtr;
 
 // descriptionPtr is destructed here -- now there are
 // no non-const pointers to the description in the system.
 // You could later use mAircraftDescription to construct an Aircraft
 // and the compiler will prevent calls to non-const methods on the 
 // AircraftDescription that would create issues with sharing.
 }

Note:

An important note for implementors: the above precaution does not prevent const methods in a Description from making internal modifications by casting away the constness. This may be necessary for various implementation reasons, and is always allowed. However, in this case, such internal code must be thread safe -- that is, multiple concurrent calls to const methods must be safe so that internal modifications due to caching, etc. do not create problems for clients that believe they are only reading and that this operation is thread safe.

---

Member Function Documentation

virtual void Phx::Description::serializedData (  const BitVector &  serializedData  )  [pure virtual]

Given a serialized form of a description of this type, set this Description's attributes to match the serialized version. In short, this method deserializes the BitVector and loads the data into the fields of the Description subclass. Viewed as an attribute, this is just a write accessor that sets all of the subclass's attributes to those contained in the serialized representation. Parameters: serializedData  A BitVector that contains the serialized form of the attributes for this description. Exceptions: InternalException  PermissionException  should be thrown by subclasses to indicate that there was a problem deserializing the data.

virtual BitVector Phx::Description::serializedData (  void   )  const [pure virtual]

Constructs and returns the serialized form of this Description. The serializedData() attribute is the serialized representation of the attributes of this description. Reading the attribute just retrieves the serialized data. Returns: A serialized bit vector of this Description.

Type Phx::Description::type (   )  const [inline]

Returns the Type constant for the subclass that this Description is an instance of. Note: During construction, this is INVALID_TYPE. Returns: The type constant for this Description's subclass.

---

Member Data Documentation

const Type Phx::Description::INVALID_TYPE [static]

A sentinel Type constant used to indicate an invalid type. This will be the value of the type() attribute when the Description is constructed. The correct value is set by the Manager class after the Description is created.

---

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

• PhxDescription.h

---