Teuchos - Trilinos Tools Package  Version of the Day
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Public Member Functions | List of all members
Teuchos::ParameterListAcceptor Class Referenceabstract

Interface for objects that can accept a ParameterList. More...

#include <Teuchos_ParameterListAcceptor.hpp>

Inheritance diagram for Teuchos::ParameterListAcceptor:
Teuchos::ObjectBuilder< ObjectType > Teuchos::ParameterListAcceptorDefaultBase Teuchos::ParameterListNonAcceptor

Public Member Functions

virtual ~ParameterListAcceptor ()
 Destructor. More...
 
Pure virtual functions that must be overridden in subclasses
virtual void setParameterList (const RCP< ParameterList > &paramList)=0
 Set parameters from a parameter list and return with default values. More...
 
virtual RCP< ParameterListgetNonconstParameterList ()=0
 Get a nonconst version of the parameter list that was set using setParameterList(). More...
 
virtual RCP< ParameterListunsetParameterList ()=0
 Unset the parameter list that was set using setParameterList(). More...
 
Virtual functions with default implementation
virtual RCP< const ParameterListgetParameterList () const
 Get const version of the parameter list that was set using setParameterList(). More...
 
virtual RCP< const ParameterListgetValidParameters () const
 Return a ParameterList containing all of the valid parameters that this->setParameterList(...) will accept, along with any validators. More...
 
virtual RCP< const
DependencySheet
getDependencies () const
 Rreturn a const DependencySheet of all the dependencies that should be applied to the ParameterList returned by this->getValidParameters(). More...
 

Detailed Description

Interface for objects that can accept a ParameterList.

Summary for users

Most users only need to know about two methods:

setParameterList() lets users set this object's parameters. getValidParameters() returns a default list of parameters, including any documentation and/or validators that the subclass may provide. If you call setParameterList(), implementations will fill in any missing parameters with their default values, and do validation. That's all you really need to know! If you want more details about semantics, though, please read on.

Semantics

Complete state or delta?

This interface does not define the semantics of calling setParametersList() twice with different lists. For example, suppose that the class SomeClass takes two parameters:

  1. An int parameter "Integer parameter"
  2. A bool parameter "Boolean parameter"

The default value of the first is 0, and the default value of the second is false. In the following code sample, what is the final state of x's parameters?

SomeClass x;
RCP<ParameterList> pl1 = parameterList ();
pl1->set ("Integer parameter", 42);
// set parameters the first time
x.setParameterList (pl1);
RCP<ParameterList> pl2 = parameterList ();
pl2->set ("Boolean parameter", true);
// set parameters the second time
x.setParameterList (pl2);

The answer is that we can't tell without knowing more about SomeClass. There are at least two possibilities:

"Integer parameter" is 0, and "Boolean parameter" is true "Integer parameter" is 42, and "Boolean parameter" is true

The first possibility says that the input ParameterList expresses the complete state of the object. Any missing parameters in subsequent calls get filled in with their default values. The second possibility says that the input ParameterList expresses a "delta," a difference from its current state. You must read the subclass' documentation to determine which of these it implements.

Notes for developers

Developers who would like a simpler interface from which to inherit may prefer the subclass ParameterListAcceptorDefaultBase. That class provides default implementations of all but two of this class' methods.

It's tempting to begin setParameterList() as follows:

paramList->validateParametersAndSetDefaults (*getValidParameters ());

That's correct, but be aware that this can only be used to implement "complete state" semantics, not "delta" semantics. This is because validateParametersAndSetDefaults() fills in default values, as its name suggests.

Before ParameterList had the validation feature, many implementations of setParameterList() would use the two-argument version of ParameterList::get(), and supply the current value of the parameter as the default if that parameter didn't exist in the input list. This implemented delta semantics. It is unclear whether implementers knew what semantics they were implementing, but that was the effect of their code.

If you want to implement delta semantics, and also want to exploit the validation feature, you have at least two options. First, you could use the validation method that does not set defaults:

paramList->validateParameters (*getValidParameters ());

and then use the two-argument version of ParameterList::get() in the way discussed above, so that existing parameter values don't get replaced with defaults.

The second option is to keep a copy of the ParameterList from the previous call to setParameterList(). This must be a deep copy, because users might have changed parameters since then. (It is likely that they have just one ParameterList, which they change as necessary.) You may then use that list – not the result of getValidParameters() – as the input argument of validateParametersAndSetDefaults().

Definition at line 120 of file Teuchos_ParameterListAcceptor.hpp.

Constructor & Destructor Documentation

Teuchos::ParameterListAcceptor::~ParameterListAcceptor ( )
virtual

Destructor.

Definition at line 19 of file Teuchos_ParameterListAcceptor.cpp.

Member Function Documentation

virtual void Teuchos::ParameterListAcceptor::setParameterList ( const RCP< ParameterList > &  paramList)
pure virtual

Set parameters from a parameter list and return with default values.

Parameters
paramList[in/out] On input: contains the parameters set by the client. On output: the same list, possibly filled with default values, depending on the implementation.

Implementations of this method generally read parameters out of paramList, and use them to modify the state or behavior of this object. Implementations may validate input parameters, and throw an exception or set an error state if any of them are invalid. "Validation

Precondition
! paramList.is_null ()
Postcondition
this->getParameterList().get() == paramList.get()

This object "remembers" paramList until it is "unset" using unsetParameterList(). When the input ParameterList is passed in, we assume that the client has finished setting parameters in the ParameterList. If the client changes paramList after calling this method, this object's behavior is undefined. This is because the object may read the options from paramList at any time. It may either do so in this method, or it may wait to read them at some later time. Users should not expect that if they change a parameter, that this object will automatically recognize the change. To change even one parameter, this method must be called again.

Implemented in Teuchos::ObjectBuilder< ObjectType >, and Teuchos::ParameterListNonAcceptor.

virtual RCP<ParameterList> Teuchos::ParameterListAcceptor::getNonconstParameterList ( )
pure virtual

Get a nonconst version of the parameter list that was set using setParameterList().

The returned ParameterList should be the same object (pointer equality) as the object given to setParameterList(). If setParameterList() has not yet been called on this object, the returned RCP may be null, but need not necessarily be. If unsetParameterList()

Implemented in Teuchos::ObjectBuilder< ObjectType >, and Teuchos::ParameterListAcceptorDefaultBase.

virtual RCP<ParameterList> Teuchos::ParameterListAcceptor::unsetParameterList ( )
pure virtual

Unset the parameter list that was set using setParameterList().

This does not undo the effect of setting the parameters via a call to setParameterList(). It merely "forgets" the RCP, so that getParameterList() and getNonconstParameterList() both return null.

Postcondition
this->getParameter().is_null ()
this->getNonconstParameter().is_null ()

Implemented in Teuchos::ObjectBuilder< ObjectType >, and Teuchos::ParameterListAcceptorDefaultBase.

Teuchos::RCP< const Teuchos::ParameterList > Teuchos::ParameterListAcceptor::getParameterList ( ) const
virtual

Get const version of the parameter list that was set using setParameterList().

The default implementation returns:

return const_cast<ParameterListAcceptor*>(this)->getParameterList();

Reimplemented in Teuchos::ObjectBuilder< ObjectType >, and Teuchos::ParameterListAcceptorDefaultBase.

Definition at line 24 of file Teuchos_ParameterListAcceptor.cpp.

Teuchos::RCP< const Teuchos::ParameterList > Teuchos::ParameterListAcceptor::getValidParameters ( ) const
virtual

Return a ParameterList containing all of the valid parameters that this->setParameterList(...) will accept, along with any validators.

Implementations of setParameterList() may use the list returned by getValidParameters() to validate the input ParameterList.

The default implementation returns null.

Reimplemented in Teuchos::ObjectBuilder< ObjectType >, and Teuchos::ParameterListNonAcceptor.

Definition at line 31 of file Teuchos_ParameterListAcceptor.cpp.

RCP< const DependencySheet > Teuchos::ParameterListAcceptor::getDependencies ( ) const
virtual

Rreturn a const DependencySheet of all the dependencies that should be applied to the ParameterList returned by this->getValidParameters().

The default implementation returns Teuchos::null.

Definition at line 37 of file Teuchos_ParameterListAcceptor.cpp.


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