Teuchos - Trilinos Tools Package  Version of the Day
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Teuchos_ObjectBuilder.hpp
1 // @HEADER
2 // *****************************************************************************
3 // Teuchos: Common Tools Package
4 //
5 // Copyright 2004 NTESS and the Teuchos contributors.
6 // SPDX-License-Identifier: BSD-3-Clause
7 // *****************************************************************************
8 // @HEADER
9 
10 #ifndef Teuchos_OBJECT_BUILDER_H
11 #define Teuchos_OBJECT_BUILDER_H
12 
14 #include "Teuchos_ParameterListAcceptor.hpp"
15 #include "Teuchos_AbstractFactoryStd.hpp"
16 #include "Teuchos_StandardParameterEntryValidators.hpp"
17 
18 
19 namespace Teuchos {
20 
21 
56 template<class ObjectType>
57 class ObjectBuilder : virtual public ParameterListAcceptor
58 {
59 public:
60 
62  ObjectBuilder();
63 
66 
68  void setObjectName(
69  const std::string &objectName
70  );
71 
73  void setObjectTypeName(
74  const std::string &objectTypeName
75  );
76 
78  void setObjectFactory(
79  const RCP<const AbstractFactory<ObjectType> > &objectFactory,
80  const std::string &objectFactoryName
81  );
82 
86  std::string getObjectName() const;
87 
92  void setDefaultObject( const std::string &defaultObject_name );
93 
96  const std::string &objectName = ""
97  ) const;
98 
101 
103  void setParameterList(const RCP<ParameterList> & paramList);
104 
107 
110 
113 
116 
118 
119 private:
120 
121  // //////////////////////////////////////
122  // Private types
123 
125 
126  // //////////////////////////////////////
127  // Private data members
128 
129  RCP<ParameterList> paramList_;
130  mutable RCP<const ParameterList> validParamList_;
132 
133  std::string object_name_;
134  std::string objectType_name_;
135 
136  Array<std::string> validObjectNames_;
137  Array<object_fcty_t> objectArray_;
138  std::string defaultObject_name_;
139 
140  // //////////////////////////////////////
141  // Private member functions
142 
143  void initializeDefaults_();
144 
145 };
146 
147 
148 // Nonmember constructors
149 
150 
151 template<class ObjectType>
152 RCP<ObjectBuilder<ObjectType> > objectBuilder()
153 {
155  return ob;
156 }
157 
158 
159 template<class ObjectType>
160 RCP<ObjectBuilder<ObjectType> >
161 objectBuilder(const std::string& objectName, const std::string& objectTypeName)
162 {
163  RCP<ObjectBuilder<ObjectType> > ob = rcp(new ObjectBuilder<ObjectType>() );
164  ob->setObjectName(objectName);
165  ob->setObjectTypeName(objectTypeName);
166  return ob;
167 }
168 
169 
170 //
171 // Implementation
172 //
173 
174 
175 template<class ObjectType>
177 {
178  this->initializeDefaults_();
179 }
180 
181 
182 template<class ObjectType>
184 {
185 }
186 
187 
188 template<class ObjectType>
190  const RCP<const AbstractFactory<ObjectType > > &objectFactory,
191  const std::string &objectName
192  )
193 {
194  TEUCHOS_TEST_FOR_EXCEPT( objectName.length() == 0 );
195  validObjectNames_.push_back(objectName);
196  objectArray_.push_back(objectFactory);
197  defaultObject_name_ = objectName;
198  validParamList_ = null;
199 #ifdef TEUCHOS_DEBUG
200  this->getValidParameters();
201 #endif // TEUCHOS_DEBUG
202 }
203 
204 
205 template<class ObjectType>
206 std::string
208 {
209  if(is_null(validParamList_)) {
210  this->getValidParameters();
211  }
212  // If the user has not specified a ParameterList, then use the ValidParameterList.
213  RCP<ParameterList> pl = null;
214  if (!is_null(paramList_)) {
215  pl = paramList_;
216  } else {
217  pl = parameterList();
218  pl->setParameters(*this->getValidParameters());
219  }
220  return objectValidator_->getStringValue(*pl, objectType_name_, defaultObject_name_);
221 }
222 
223 
224 template<class ObjectType>
226  RCP<ParameterList> const& paramList
227  )
228 {
229  if (!is_null(paramList)) {
230  paramList->validateParameters(*this->getValidParameters());
231  paramList_ = paramList;
232  }
233 }
234 
235 
236 template<class ObjectType>
239 {
240  return paramList_;
241 }
242 
243 
244 template<class ObjectType>
247 {
248 #ifdef TEUCHOS_DEBUG
249  // Validate that we read the parameters correctly!
250  if(!is_null(paramList_))
251  paramList_->validateParameters(*this->getValidParameters());
252 #endif
253  RCP<ParameterList> _paramList = paramList_;
254  paramList_ = null;
255  return _paramList;
256 }
257 
258 
259 template<class ObjectType>
262 {
263  return paramList_;
264 }
265 
266 
267 template<class ObjectType>
270 {
271  if(!validParamList_.get()) {
272  RCP<ParameterList> validParamList = parameterList();
273  // Object Types
274  objectValidator_ = rcp(
276  validObjectNames_, objectType_name_
277  )
278  );
279  objectValidator_->validateString(defaultObject_name_,objectType_name_);
280  validParamList->set(
281  objectType_name_, defaultObject_name_,
282  (std::string("Determines the type of " + object_name_ + " object that will be built.\n")
283  + "The parameters for each " + objectType_name_ + " are specified in this sublist"
284  ).c_str(),
285  objectValidator_
286  );
287  for( int i = 0; i < static_cast<int>(objectArray_.size()); ++i ) {
288  const std::string
289  &sname = validObjectNames_[i+1];
290  const RCP<ObjectType >
291  object = objectArray_[i]->create();
292  validParamList->sublist(sname).setParameters(
293  *object->getValidParameters()).disableRecursiveValidation();
294  }
295  validParamList_ = validParamList;
296  }
297  return validParamList_;
298 }
299 
300 template<class ObjectType>
302  const std::string &defaultObject_name
303  )
304 {
305 #ifdef TEUCHOS_DEBUG
306  if (is_null(validParamList_)) { // We need the objectValidator_
307  this->getValidParameters();
308  }
309  objectValidator_->validateString(defaultObject_name,objectType_name_);
310 #endif // TEUCHOS_DEBUG
311  defaultObject_name_ = defaultObject_name;
312  // This is necessary to change the default in the valid parameter list
313  validParamList_ = null;
314 }
315 
316 template<class ObjectType>
319  const std::string &objectName
320  ) const
321 {
322  if (is_null(validParamList_)) { // We need the objectValidator_
323  this->getValidParameters();
324  }
325  const std::string
326  sname = ( objectName.length()
327  ? objectName
328  : this->getObjectName() );
329  RCP<ObjectType> object = null;
330  // Get the index of this object factory (this will validate!)
331  const int
332  s_idx = objectValidator_->getIntegralValue(sname, objectType_name_);
333  if (s_idx != 0) {
334  // Create the uninitialized object
335  object = objectArray_[s_idx-1]->create();
336  TEUCHOS_TEST_FOR_EXCEPTION( is_null(object), std::logic_error,
337  (std::string("Error! ObjectBuilder attempted to create an object of type ")
338  + validObjectNames_[s_idx] + " and it came back as a null RCP!").c_str()
339  );
340  // Allow the user to not set a parameterlist (this requires copying the
341  // parameters in the valid parameter list into a new parameter list:
342  RCP<ParameterList> pl = null;
343  if (is_null(paramList_)) {
344  pl = parameterList();
345  pl->setParameters(this->getValidParameters()->sublist(sname));
346  } else {
347 #ifdef TEUCHOS_DEBUG
348  // We're validating the parameter list here again because we're storing a
349  // pointer to it and the user could have changed it.
350  paramList_->validateParameters(*this->getValidParameters());
351 #endif // TEUCHOS_DEBUG
352  pl = sublist(paramList_,sname);
353  }
354  // Now set the parameters for the object
355  object->setParameterList(pl);
356  }
357  return object;
358 }
359 
360 
361 template<class ObjectType>
363  const std::string &objectName
364  )
365 {
366  TEUCHOS_TEST_FOR_EXCEPT(objectName.length() == 0);
367  object_name_ = objectName;
368  validParamList_ = null;
369 }
370 
371 
372 template<class ObjectType>
374  const std::string &objectTypeName
375  )
376 {
377  TEUCHOS_TEST_FOR_EXCEPT(objectTypeName.length() == 0);
378  objectType_name_ = objectTypeName;
379  validParamList_ = null;
380 }
381 
382 
383 template<class ObjectType>
385 {
386 
387  object_name_ = "Object";
388  objectType_name_ = "Object Type";
389 
390  defaultObject_name_ = "None";
391  validObjectNames_.resize(0);
392  validObjectNames_.push_back(defaultObject_name_);
393 
394 }
395 
396 
397 } // namespace Teuchos
398 
399 
400 #endif //Teuchos_OBJECT_BUILDER_H
void setDefaultObject(const std::string &defaultObject_name)
Set the name of the desired object to be created when the parameter list does not specify which objec...
RCP< ParameterList > getNonconstParameterList()
Generic parameterlist driven bulider class.
bool is_null(const std::shared_ptr< T > &p)
Returns true if p.get()==NULL.
RCP< const ParameterList > getValidParameters() const
#define TEUCHOS_TEST_FOR_EXCEPTION(throw_exception_test, Exception, msg)
Macro for throwing an exception with breakpointing to ease debugging.
RCP< ParameterList > unsetParameterList()
void setObjectName(const std::string &objectName)
Set the name of the object this will be a builder for, e.g. &quot;Object&quot;.
ParameterList & set(std::string const &name, T &&value, std::string const &docString="", RCP< const ParameterEntryValidator > const &validator=null)
Templated set method.
RCP< ObjectType > create(const std::string &objectName="") const
void setObjectFactory(const RCP< const AbstractFactory< ObjectType > > &objectFactory, const std::string &objectFactoryName)
Set a new Object factory object.
void setObjectTypeName(const std::string &objectTypeName)
Set the name of the parameterlist selector, e.g. &quot;Object Type&quot;.
TEUCHOS_DEPRECATED RCP< T > rcp(T *p, Dealloc_T dealloc, bool owns_mem)
Deprecated.
Templated Parameter List class.
std::string getStringValue(ParameterList const &paramList, std::string const &paramName)
Get a std::string value for a parameter that is assumed to already be set.
void setParameterList(const RCP< ParameterList > &paramList)
void validateParameters(ParameterList const &validParamList, int const depth=1000, EValidateUsed const validateUsed=VALIDATE_USED_ENABLED, EValidateDefaults const validateDefaults=VALIDATE_DEFAULTS_ENABLED) const
Validate the parameters in this list given valid selections in the input list.
ParameterList & setParameters(const ParameterList &source)
std::string getObjectName() const
Get the name of the Object that will be created on the next call to this-&gt;create().
Interface for objects that can accept a ParameterList.
ParameterList & sublist(const std::string &name, bool mustAlreadyExist=false, const std::string &docString="")
Creates an empty sublist and returns a reference to the sublist name. If the list already exists...
Smart reference counting pointer class for automatic garbage collection.
Simple, universal &quot;Abstract Factory&quot; interface for the dynamic creation of objects.
RCP< const ParameterList > getParameterList() const
#define TEUCHOS_TEST_FOR_EXCEPT(throw_exception_test)
This macro is designed to be a short version of TEUCHOS_TEST_FOR_EXCEPTION() that is easier to call...