Gyoto::FactoryMessenger Class Reference

Factory / SmartPointee::Subcontractor_t interface. More...

`#include <GyotoFactoryMessenger.h>`

## Public Member Functions

| FactoryMessenger (Gyoto::Factory *, xercesc::DOMElement *)
| Constructor called before subcontracting.
| FactoryMessenger (const FactoryMessenger &parent, std::string)
| Constructor called before fillElement.
void | reset ()
| Get back to first parameter.
SmartPointer< Metric::Generic > | metric ()
| Build and get the Metric described in this XML file.
SmartPointer< Screen > | screen ()
| Build and get the Screen described in this XML file.
SmartPointer< Photon > | photon ()
| Build and get the Photon described in this XML file.
SmartPointer< Astrobj::Generic > | astrobj ()
| Build and get the Astrobj described in this XML file.
int | getNextParameter (std::string *name, std::string *content, std::string *unit=NULL)
| Get name and value of next parameter.
std::string | getSelfAttribute (std::string attrname) const
| Get attribute of FactoryMessenger::element_.
std::string | getAttribute (std::string attrname) const
| Get attribute of a last retrieved parameter.
std::string | getFullContent () const
| Get full content of element_.
FactoryMessenger * | getChild () const
| Get another FactoryMessenger instance initialized to current child.
std::string | fullPath (std::string relpath)
| Transform path into full path specification.
void | metric (SmartPointer< Metric::Generic >)
| Set the Metric.
void | astrobj (SmartPointer< Astrobj::Generic >)
| Set the Astrobj.
void | screen (SmartPointer< Screen >)
| Set the Screen.
void | setParameter (std::string name)
| Output parameter.
void | setParameter (std::string name, double value)
| Output parameter.
void | setParameter (std::string name, long int value)
| Output parameter.
void | setParameter (std::string name, unsigned int value)
| Output parameter.
void | setParameter (std::string name, unsigned long value)
| Output parameter.
void | setParameter (std::string name, int value)
| Output parameter.
void | setParameter (std::string name, std::string value)
| Output parameter.
void | setParameter (std::string name, double val[], size_t n, FactoryMessenger **child=NULL)
| Output an array of parameters.
void | setParameter (std::string name, std::vector< double > const &val, FactoryMessenger **child=NULL)
void | setParameter (std::string name, std::vector< unsigned long > const &val, FactoryMessenger **child=NULL)
| Output a vector of parameters.
void | setSelfAttribute (std::string attrname, std::string value)
| Set attribute in FactoryMessenger::element_.
void | setSelfAttribute (std::string attrname, unsigned long value)
| Set attribute in FactoryMessenger::element_.
void | setSelfAttribute (std::string attrname, unsigned int value)
| Set attribute in FactoryMessenger::element_.
void | setSelfAttribute (std::string attrname, double value)
| Set attribute in FactoryMessenger::element_.
void | setFullContent (std::string value)
| Low level, prefer setParameter().
FactoryMessenger * | makeChild (std::string name)
| Create child FactoryMessenger.

## Static Public Member Functions

static size_t | parseArray (std::string src, double dst[], size_t max_tokens)
| Parse string into array.
static std::vector< double > | parseArray (std::string src)
| Parse string into array.
static std::vector< unsigned long > | parseArrayULong (std::string src)
| Parse string into array.

## Private Attributes

Gyoto::Factory * | employer_
| The Factory that sent this messenger.
xercesc::DOMElement * | element_
| The XML element concerned by this transaction.
xercesc::DOMNodeList * | children_
| The children of the XML element concerned by this transaction.
XMLSize_t | nodeCount_
| The number of children of the XML element concerned by this transaction.
XMLSize_t | curNodeIndex_
| Current child.

## Detailed Description

Factory / SmartPointee::Subcontractor_t interface.

A FactoryMessenger instance is like an employee passing messages between its employer (the Factory) and a subcontractor (a function of the SmartPointee::Subcontractor_t type).

The FactoryMessenger also communicate with the fillElement method of some classes (Astrobj::Generic::fillElement(), Metric::Generic::fillElement(), Spectrum::Generic::fillElement()).

A subcontractor function typically loops calling getNextParameter() to read all the parameters provided for it in an XML file. If BASE is one of Astrobj, Metric or Spectrum, and MyClass is an implementation of BASE::Generic, the subcontractor static member function often looks like this:

SmartPointer<Gyoto::BASE::Generic> MyClass::Subcontractor(Gyoto::FactoryMessenger *messenger) {
SmartPointer<Gyoto::BASE::MyClass> deliverable = new MyClass();
while (messenger->getNextParameter(name, content) {
if (name=="SomeProperty") deliverable -> setSomeProperty(content);
else if (name=="AnotherProperty") deliverable -> setAnotherProperty(content);
}
return deliverable;
}
Gyoto::FactoryMessenger
Factory / SmartPointee::Subcontractor_t interface.
Definition GyotoFactoryMessenger.h:92
Gyoto::FactoryMessenger::getNextParameter
int getNextParameter(std::string *name, std::string *content, std::string *unit=NULL)
Get name and value of next parameter.
Gyoto::SmartPointer
Pointers performing reference counting.
Definition GyotoSmartPointer.h:135

Other get* methods are provided to cope with more complex syntax (e.g. when XML attributes are used, as in <ParameterName attribute="attrvalue">ParameterValue</ParameterName>

Conversely, the Factory asks certain Gyoto classes through their fillElement() method how they should be printed or saved to an XML file. Those fillElement() methods use the FactoryMessenger::set*() methods (in particular setParameter()) as well as, occasionally, makeChild() to describe themselves to the Factory.

## Member Function Documentation

## astrobj() [1/2]

SmartPointer< Astrobj::Generic > Gyoto::FactoryMessenger::astrobj | ( |  | ) |

Build and get the Astrobj described in this XML file.

An Gyoto XML file may contain at most a single Astrobj section and it may be present about anywhere in the XML tree. Individual subcontractors should not try to interpret this section directly, but should call astrobj() to find and interpret the Astrobj section.

## astrobj() [2/2]

void Gyoto::FactoryMessenger::astrobj | ( | SmartPointer< Astrobj::Generic > |  | ) |

Set the Astrobj.

Same as metric(), but for the Astrobj.

## fullPath()

std::string Gyoto::FactoryMessenger::fullPath | ( | std::string | relpath | ) |

Transform path into full path specification.

This function takes a relative path (e.g. ../foo/bar.data) and transforms it into a full path (starting with "/"). It is not guaranteed to be portable (we assume that the path separator is "/" and that absolute paths start with "/").

Parameters

  relpath | path relative to the directory where the XML file on which the Factory works is located.

Returns
  fullpath at full path specification to the same point pon the file-system.

## getAttribute()

std::string Gyoto::FactoryMessenger::getAttribute | ( | std::string | attrname | ) | const

Get attribute of a last retrieved parameter.

For instance

<ParameterName attrname="attrvalue">ParameterContent</ParameterName>

Parameters

  attrname | name of the attribute

Returns
  attrvalue

## getChild()

FactoryMessenger * Gyoto::FactoryMessenger::getChild | ( |  | ) | const

Get another FactoryMessenger instance initialized to current child.

If one of the FactoryMessenger::children_ is complex (for instance the complete description of a Gyoto::Spectrum), it is possible to initialize a new FactoryMessenger and call the correct subcontractor:

SmartPointer<Spectrum::Generic> spectrum = NULL;
while (messenger->getNextParameter(name, content) {
if (name=="Spectrum") {
content = messenger->getAttribute("kind");
FactoryMessenger* child = messenger->getChild();
deliverable->spectrum( (*Spectrum::getSubcontractor(content))(child) );
delete child;
}
}

The child is allocated with new and must be deleted after use.

## getFullContent()

std::string Gyoto::FactoryMessenger::getFullContent | ( |  | ) | const

Get full content of element_.

In exceptional circumstances, it may be necessary to get the entire text content of the topmost element FactoryMessenger::element_ instead or getting only the individual FactoryMessenger::children_ .

For instance a Spectrometer description looks like this:

<Spectrometer kind="wave" nsamples="10"> 2.0e-6 2.4e-6</Astrobj>
Gyoto::Astrobj
Access to astronomical objects.
Definition GyotoAstrobj.h:49
Gyoto::Spectrometer
Access to spectrometers.
Definition GyotoComplexSpectrometer.h:34

and the Spectrometer builder uses getFullContent() to retrieve the spectral boundaries (2.0e-6 and 2.4e-6 here).

## getNextParameter()

int Gyoto::FactoryMessenger::getNextParameter | ( | std::string * | name,
|  | std::string * | content,
|  | std::string * | unit = NULL )

Get name and value of next parameter.

On each call, return a pair name-content of one of the children_. Usually, "name" is the name of a parameter and "content" is the string representation of the corresponding value. For instance:

<Name>Content</Name>

Parameters

  name | upon output, name of the child
  content | of the child
  unit= | propertty of the child

Returns
  1 if there remains parameters to retrieve, 0 otherwise.

## getSelfAttribute()

std::string Gyoto::FactoryMessenger::getSelfAttribute | ( | std::string | attrname | ) | const

Get attribute of FactoryMessenger::element_.

For instance a Spectrometer description looks like this

<Spectrometer kind="wave" nsamples="10"> 2.0e-6 2.4e-6</Astrobj>

and the Spectrometer builder uses getSelfAttribute() to retrieve the attributes "kind" and "nsamples".

Parameters

  attrname | name of the attribute

Returns
  attrvalue

## makeChild()

FactoryMessenger * Gyoto::FactoryMessenger::makeChild | ( | std::string | name | ) |

Create child FactoryMessenger.

To be used from fillElement() methods. For instance, the Star::fillElement() method calls makeChild() to save the Star's Spectrum and Opacity members somewhat like this:

FactoryMessenger * child;
child = messenger-> makeChild("Spectrum");
spectrum_ -> fillElement(child);
delete child;
child = messenger-> makeChild("Opacity");
opacity_ -> fillElement(child);
delete child;
child=NULL;
Gyoto::FactoryMessenger::FactoryMessenger
FactoryMessenger(Gyoto::Factory *, xercesc::DOMElement *)
Constructor called before subcontracting.
Gyoto::FactoryMessenger::makeChild
FactoryMessenger * makeChild(std::string name)
Create child FactoryMessenger.

The child messenger is allocated with new, you need to delete it after use.

## metric() [1/2]

SmartPointer< Metric::Generic > Gyoto::FactoryMessenger::metric | ( |  | ) |

Build and get the Metric described in this XML file.

An Gyoto XML file may contain at most a single Metric section and it may be present about anywhere in the XML tree. Individual subcontractors should not try to interpret this section directly, but should call metric() to find and interpret the Metric section.

## metric() [2/2]

void Gyoto::FactoryMessenger::metric | ( | SmartPointer< Metric::Generic > |  | ) |

Set the Metric.

At most one Metric section may be present in a give Gyoto XML file.

When an object's fillElement() method is called, if this object is connected to a Metric, it should call metric() with this Metric. Very often, the Metric will already have been set previously. The Factory will check that all the objects in the hierarchy are attached to the same Metric instance, and save this instance only once. Trying to set the Metric to something else than the already set Metric instance is an error condition.

To make things clearer: Assume "scenery" is a fully filled Scenery. scenery->fillElement(messenger) will call:

messenger->metric(Scenery::gg_)
messenger->screen(Scenery::screen_)
messenger->astrobj(Scenery::obj_);
Gyoto::Scenery::screen_
SmartPointer< Screen > screen_
Definition GyotoScenery.h:176

The Factory will then call screen_->fillElement(child_messenger) and obj_->fillElement(child_messenger), each of which will also call metric(). If the same Metric is connected to the Astrobj, to the Screen and to the Scenery, all is well. Else, you have a bug to fix.

## parseArray() [1/2]

std::vector< double > Gyoto::FactoryMessenger::parseArray | ( | std::string | src | ) |

static

Parse string into array.

Parse tokens from string src, returns them into a std::vector<double>.

## parseArray() [2/2]

size_t Gyoto::FactoryMessenger::parseArray | ( | std::string | src,
|  | double | dst[],
|  | size_t | max_tokens )

static

Parse string into array.

Parse at most max_tokens tokens from string src into pre-allocated array dst. Returns the number of tokens actually found (interpreted using atof). dst must be at least of size max_tokens.

## parseArrayULong()

std::vector< unsigned long > Gyoto::FactoryMessenger::parseArrayULong | ( | std::string | src | ) |

static

Parse string into array.

Parse tokens from string src, returns them into a std::vector<unsigned long>.

## photon()

SmartPointer< Photon > Gyoto::FactoryMessenger::photon | ( |  | ) |

Build and get the Photon described in this XML file.

An Gyoto XML file may contain at most a single Photon section and it may be present about anywhere in the XML tree. Individual subcontractors should not try to interpret this section directly, but should call photon() to find and interpret the Photon section.

## screen() [1/2]

SmartPointer< Screen > Gyoto::FactoryMessenger::screen | ( |  | ) |

Build and get the Screen described in this XML file.

An Gyoto XML file may contain at most a single Screen section and it may be present about anywhere in the XML tree. Individual subcontractors should not try to interpret this section directly, but should call screen() to find and interpret the Screen section.

## screen() [2/2]

void Gyoto::FactoryMessenger::screen | ( | SmartPointer< Screen > |  | ) |

Set the Screen.

Same as metric(), but for the Screen.

## setFullContent()

void Gyoto::FactoryMessenger::setFullContent | ( | std::string | value | ) |

Low level, prefer setParameter().

Exceptionnaly, a class instance may be best described by setting the entire content of the corresponding element than by setting a bunch of "parameters". This is the case of the spectrometer, which sets a couple of attributes and reserves the full content for the spectral boundaries (see Spectrometer::fillElement()).

## setParameter() [1/8]

void Gyoto::FactoryMessenger::setParameter | ( | std::string | name | ) |

Output parameter.

Create child XML element of the form

<name/>

for instance when "name" is boolean (present or absent), or only takes attributes (see FactoryMessenger::setAttribute()). As an example, Astrobj::Generic::fillElement() uses setParameter() to set either Opticallythin or OpticallyThick.

## setParameter() [2/8]

void Gyoto::FactoryMessenger::setParameter | ( | std::string | name,
|  | double | val[],
|  | size_t | n,
|  | FactoryMessenger ** | child = NULL )

Output an array of parameters.

For instance:

double val[4] = {1., 2., 3., 4.};
messenger->setParameter("MyArray", val, 4);

will result in something like this:

<MyArray>1.000000 2.000000 3.000000 4.000000</MyArray>

The exact format is unspecified, determined at compile time, and by default, unlike in the example above, outputs a large number of digits for each double (about 20).

Parameters

  name | the name of the parameter
  val[] | an array of doubles
  n | number of cells in val[]
  child | (optional) if not NULL, a new FactoryMessenger is created to access the new parameter element e.g. to set attributes in it (using setSelfAttribute()). You then need to delete the child.

## setParameter() [3/8]

void Gyoto::FactoryMessenger::setParameter | ( | std::string | name,
|  | double | value )

Output parameter.

Convert value to striing "svalue" and create an XML child element of the form

<name>svalue</name>

## setParameter() [4/8]

void Gyoto::FactoryMessenger::setParameter | ( | std::string | name,
|  | int | value )

Output parameter.

Convert value to string "svalue" and create an XML child element of the form

<name>svalue</name>

## setParameter() [5/8]

void Gyoto::FactoryMessenger::setParameter | ( | std::string | name,
|  | long int | value )

Output parameter.

Convert value to striing "svalue" and create an XML child element of the form

<name>svalue</name>

## setParameter() [6/8]

void Gyoto::FactoryMessenger::setParameter | ( | std::string | name,
|  | std::string | value )

Output parameter.

Create an XML child element of the form

<name>value</name>

## setParameter() [7/8]

void Gyoto::FactoryMessenger::setParameter | ( | std::string | name,
|  | unsigned int | value )

Output parameter.

Convert value to striing "svalue" and create an XML child element of the form

<name>svalue</name>

## setParameter() [8/8]

void Gyoto::FactoryMessenger::setParameter | ( | std::string | name,
|  | unsigned long | value )

Output parameter.

Convert value to striing "svalue" and create an XML child element of the form

<name>svalue</name>

## setSelfAttribute() [1/4]

void Gyoto::FactoryMessenger::setSelfAttribute | ( | std::string | attrname,
|  | double | value )

Set attribute in FactoryMessenger::element_.

See setSelfAttribute(std::string attrname, std::string value)

## setSelfAttribute() [2/4]

void Gyoto::FactoryMessenger::setSelfAttribute | ( | std::string | attrname,
|  | std::string | value )

Set attribute in FactoryMessenger::element_.

For instance Spectrometer::fillElement() sets its "kind" attribute somewhat like this:

messenger->setSelfAttribute("kind", "wave");

to produce something like this:

<Spectrometer kind="wave"/>

## setSelfAttribute() [3/4]

void Gyoto::FactoryMessenger::setSelfAttribute | ( | std::string | attrname,
|  | unsigned int | value )

Set attribute in FactoryMessenger::element_.

See setSelfAttribute(std::string attrname, std::string value)

## setSelfAttribute() [4/4]

void Gyoto::FactoryMessenger::setSelfAttribute | ( | std::string | attrname,
|  | unsigned long | value )

Set attribute in FactoryMessenger::element_.

See setSelfAttribute(std::string attrname, std::string value)

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

- GyotoFactoryMessenger.h