Teuchos Package Browser (Single Doxygen Collection)  Version of the Day
Teuchos_ObjectBuilder.hpp
Go to the documentation of this file.
1 // @HEADER
2 // ***********************************************************************
3 //
4 // Teuchos: Common Tools Package
5 // Copyright (2004) Sandia Corporation
6 //
7 // Under terms of Contract DE-AC04-94AL85000, there is a non-exclusive
8 // license for use of this work by or on behalf of the U.S. Government.
9 //
10 // Redistribution and use in source and binary forms, with or without
11 // modification, are permitted provided that the following conditions are
12 // met:
13 //
14 // 1. Redistributions of source code must retain the above copyright
15 // notice, this list of conditions and the following disclaimer.
16 //
17 // 2. Redistributions in binary form must reproduce the above copyright
18 // notice, this list of conditions and the following disclaimer in the
19 // documentation and/or other materials provided with the distribution.
20 //
21 // 3. Neither the name of the Corporation nor the names of the
22 // contributors may be used to endorse or promote products derived from
23 // this software without specific prior written permission.
24 //
25 // THIS SOFTWARE IS PROVIDED BY SANDIA CORPORATION "AS IS" AND ANY
26 // EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
27 // IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
28 // PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SANDIA CORPORATION OR THE
29 // CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
30 // EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
31 // PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
32 // PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
33 // LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
34 // NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
35 // SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
36 //
37 // Questions? Contact Michael A. Heroux (maherou@sandia.gov)
38 //
39 // ***********************************************************************
40 // @HEADER
41 
42 #ifndef Teuchos_OBJECT_BUILDER_H
43 #define Teuchos_OBJECT_BUILDER_H
44 
49 
50 
51 namespace Teuchos {
52 
53 
88 template<class ObjectType>
89 class ObjectBuilder : virtual public ParameterListAcceptor
90 {
91 public:
92 
94  ObjectBuilder();
95 
98 
100  void setObjectName(
101  const std::string &objectName
102  );
103 
105  void setObjectTypeName(
106  const std::string &objectTypeName
107  );
108 
110  void setObjectFactory(
111  const RCP<const AbstractFactory<ObjectType> > &objectFactory,
112  const std::string &objectFactoryName
113  );
114 
118  std::string getObjectName() const;
119 
124  void setDefaultObject( const std::string &defaultObject_name );
125 
128  const std::string &objectName = ""
129  ) const;
130 
133 
135  void setParameterList(const RCP<ParameterList> & paramList);
136 
139 
142 
145 
148 
150 
151 private:
152 
153  // //////////////////////////////////////
154  // Private types
155 
157 
158  // //////////////////////////////////////
159  // Private data members
160 
164 
165  std::string object_name_;
166  std::string objectType_name_;
167 
170  std::string defaultObject_name_;
171 
172  // //////////////////////////////////////
173  // Private member functions
174 
175  void initializeDefaults_();
176 
177 };
178 
179 
180 // Nonmember constructors
181 
182 
183 template<class ObjectType>
185 {
187  return ob;
188 }
189 
190 
191 template<class ObjectType>
192 RCP<ObjectBuilder<ObjectType> >
193 objectBuilder(const std::string& objectName, const std::string& objectTypeName)
194 {
196  ob->setObjectName(objectName);
197  ob->setObjectTypeName(objectTypeName);
198  return ob;
199 }
200 
201 
202 //
203 // Implementation
204 //
205 
206 
207 template<class ObjectType>
209 {
210  this->initializeDefaults_();
211 }
212 
213 
214 template<class ObjectType>
216 {
217 #ifdef TEUCHOS_DEBUG
218  // Validate that we read the parameters correctly!
219  if(!is_null(paramList_)) {
220  paramList_->validateParameters(*this->getValidParameters());
221  }
222 #endif
223 }
224 
225 
226 template<class ObjectType>
228  const RCP<const AbstractFactory<ObjectType > > &objectFactory,
229  const std::string &objectName
230  )
231 {
232  TEUCHOS_TEST_FOR_EXCEPT( objectName.length() == 0 );
233  validObjectNames_.push_back(objectName);
234  objectArray_.push_back(objectFactory);
235  defaultObject_name_ = objectName;
236  validParamList_ = null;
237 #ifdef TEUCHOS_DEBUG
238  this->getValidParameters();
239 #endif // TEUCHOS_DEBUG
240 }
241 
242 
243 template<class ObjectType>
244 std::string
246 {
247  if(is_null(validParamList_)) {
248  this->getValidParameters();
249  }
250  // If the user has not specified a ParameterList, then use the ValidParameterList.
252  if (!is_null(paramList_)) {
253  pl = paramList_;
254  } else {
255  pl = parameterList();
256  pl->setParameters(*this->getValidParameters());
257  }
258  return objectValidator_->getStringValue(*pl, objectType_name_, defaultObject_name_);
259 }
260 
261 
262 template<class ObjectType>
264  RCP<ParameterList> const& paramList
265  )
266 {
267  if (!is_null(paramList)) {
268  paramList->validateParameters(*this->getValidParameters());
269  paramList_ = paramList;
270  }
271 }
272 
273 
274 template<class ObjectType>
277 {
278  return paramList_;
279 }
280 
281 
282 template<class ObjectType>
285 {
286 #ifdef TEUCHOS_DEBUG
287  // Validate that we read the parameters correctly!
288  if(!is_null(paramList_))
289  paramList_->validateParameters(*this->getValidParameters());
290 #endif
291  RCP<ParameterList> _paramList = paramList_;
292  paramList_ = null;
293  return _paramList;
294 }
295 
296 
297 template<class ObjectType>
300 {
301  return paramList_;
302 }
303 
304 
305 template<class ObjectType>
308 {
309  if(!validParamList_.get()) {
310  RCP<ParameterList> validParamList = parameterList();
311  // Object Types
312  objectValidator_ = rcp(
314  validObjectNames_, objectType_name_
315  )
316  );
317  objectValidator_->validateString(defaultObject_name_,objectType_name_);
318  validParamList->set(
319  objectType_name_, defaultObject_name_,
320  (std::string("Determines the type of " + object_name_ + " object that will be built.\n")
321  + "The parameters for each " + objectType_name_ + " are specified in this sublist"
322  ).c_str(),
323  objectValidator_
324  );
325  for( int i = 0; i < static_cast<int>(objectArray_.size()); ++i ) {
326  const std::string
327  &sname = validObjectNames_[i+1];
328  const RCP<ObjectType >
329  object = objectArray_[i]->create();
330  validParamList->sublist(sname).setParameters(
331  *object->getValidParameters()).disableRecursiveValidation();
332  }
333  validParamList_ = validParamList;
334  }
335  return validParamList_;
336 }
337 
338 template<class ObjectType>
340  const std::string &defaultObject_name
341  )
342 {
343 #ifdef TEUCHOS_DEBUG
344  if (is_null(validParamList_)) { // We need the objectValidator_
345  this->getValidParameters();
346  }
347  objectValidator_->validateString(defaultObject_name,objectType_name_);
348 #endif // TEUCHOS_DEBUG
349  defaultObject_name_ = defaultObject_name;
350  // This is necessary to change the default in the valid parameter list
351  validParamList_ = null;
352 }
353 
354 template<class ObjectType>
357  const std::string &objectName
358  ) const
359 {
360  if (is_null(validParamList_)) { // We need the objectValidator_
361  this->getValidParameters();
362  }
363  const std::string
364  sname = ( objectName.length()
365  ? objectName
366  : this->getObjectName() );
367  RCP<ObjectType> object = null;
368  // Get the index of this object factory (this will validate!)
369  const int
370  s_idx = objectValidator_->getIntegralValue(sname, objectType_name_);
371  if (s_idx != 0) {
372  // Create the uninitialized object
373  object = objectArray_[s_idx-1]->create();
374  TEUCHOS_TEST_FOR_EXCEPTION( is_null(object), std::logic_error,
375  (std::string("Error! ObjectBuilder attempted to create an object of type ")
376  + validObjectNames_[s_idx] + " and it came back as a null RCP!").c_str()
377  );
378  // Allow the user to not set a parameterlist (this requires copying the
379  // parameters in the valid parameter list into a new parameter list:
381  if (is_null(paramList_)) {
382  pl = parameterList();
383  pl->setParameters(this->getValidParameters()->sublist(sname));
384  } else {
385 #ifdef TEUCHOS_DEBUG
386  // We're validating the parameter list here again because we're storing a
387  // pointer to it and the user could have changed it.
388  paramList_->validateParameters(*this->getValidParameters());
389 #endif // TEUCHOS_DEBUG
390  pl = sublist(paramList_,sname);
391  }
392  // Now set the parameters for the object
393  object->setParameterList(pl);
394  }
395  return object;
396 }
397 
398 
399 template<class ObjectType>
401  const std::string &objectName
402  )
403 {
404  TEUCHOS_TEST_FOR_EXCEPT(objectName.length() == 0);
405  object_name_ = objectName;
406  validParamList_ = null;
407 }
408 
409 
410 template<class ObjectType>
412  const std::string &objectTypeName
413  )
414 {
415  TEUCHOS_TEST_FOR_EXCEPT(objectTypeName.length() == 0);
416  objectType_name_ = objectTypeName;
417  validParamList_ = null;
418 }
419 
420 
421 template<class ObjectType>
423 {
424 
425  object_name_ = "Object";
426  objectType_name_ = "Object Type";
427 
428  defaultObject_name_ = "None";
429  validObjectNames_.resize(0);
430  validObjectNames_.push_back(defaultObject_name_);
431 
432 }
433 
434 
435 } // namespace Teuchos
436 
437 
438 #endif //Teuchos_OBJECT_BUILDER_H
RCP< const ParameterList > validParamList_
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()
Array< object_fcty_t > objectArray_
ParameterList & set(std::string const &name, T const &value, std::string const &docString="", RCP< const ParameterEntryValidator > const &validator=null)
Set a parameter whose value has type T.
Generic parameterlist driven bulider class.
bool is_null(const std::shared_ptr< T > &p)
Returns true if p.get()==NULL.
#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. "Object".
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. "Object Type".
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.
TEUCHOS_DEPRECATED RCP< T > rcp(T *p, Dealloc_T dealloc, bool owns_mem)
Deprecated.
Templated Parameter List class.
RCP< ObjectType > create(const std::string &objectName="") const
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)
ParameterList & setParameters(const ParameterList &source)
Interface for objects that can accept a ParameterList.
RCP< const StringToIntegralParameterEntryValidator< int > > objectValidator_
Array< std::string > validObjectNames_
RCP< ParameterList > paramList_
RCP< const ParameterList > getParameterList() const
RCP< ObjectBuilder< ObjectType > > objectBuilder()
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.
RCP< const ParameterList > getValidParameters() const
Simple, universal "Abstract Factory" interface for the dynamic creation of objects.
RCP< const AbstractFactory< ObjectType > > object_fcty_t
std::string getObjectName() const
Get the name of the Object that will be created on the next call to this->create().
#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...