Gyoto::FactoryMessenger Class Reference

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

#include <GyotoFactoryMessenger.h>

List of all members.

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::Genericmetric ()
 Build and get the Metric described in this XML file.
SmartPointer< Screenscreen ()
 Build and get the Screen described in this XML file.
SmartPointer< PhotongetPhoton ()
 Build and get the Photon described in this XML file.
SmartPointer< Astrobj::Genericastrobj ()
 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_.
FactoryMessengergetChild () 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().
FactoryMessengermakeChild (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::Factoryemployer_
 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;
 }

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

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

Set the Astrobj.

Same as metric(), but for the Astrobj.

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.

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.
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
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.

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>

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

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.
SmartPointer<Photon> Gyoto::FactoryMessenger::getPhoton (  ) 

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 getPhoton() to find and interpret the Photon section.

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
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;

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

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_);

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.

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.

static 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>.

static 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.

static 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>.

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

Set the Screen.

Same as metric(), but for the Screen.

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.

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()).

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.
void Gyoto::FactoryMessenger::setParameter ( std::string  name,
std::string  value 
)

Output parameter.

Create an XML child element of the form

 <name>value</name>
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>
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>
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>
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>
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>
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.

void Gyoto::FactoryMessenger::setSelfAttribute ( std::string  attrname,
double  value 
)
void Gyoto::FactoryMessenger::setSelfAttribute ( std::string  attrname,
unsigned int  value 
)
void Gyoto::FactoryMessenger::setSelfAttribute ( std::string  attrname,
unsigned long  value 
)
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"/>

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

Generated on 22 Jul 2017 for Gyoto by  doxygen 1.6.1