MongoDB  2.7.0
Public Member Functions | Protected Attributes | List of all members
mongo::optionenvironment::Environment Class Reference

An Environment is a map of values that can be validated according to a set of registered constraints. More...

#include <environment.h>

Public Member Functions

Status addKeyConstraint (KeyConstraint *keyConstraint)
 These functions are to add Constraints and KeyConstraints which will be run against this environment in the following situations: More...
 
Status addConstraint (Constraint *constraint)
 
Status set (const Key &key, const Value &value)
 Add the Value to this Environment with the given Key. More...
 
Status remove (const Key &key)
 Remove the Value from this Environment with the given Key. More...
 
Status setDefault (const Key &key, const Value &value)
 Add a default Value to this Environment with the given Key. More...
 
Status get (const Key &key, Value *value) const
 Populate the given Value with the Value stored for the given Key. More...
 
template<typename T >
Status get (const Key &key, T *value_contents) const
 Same as the above get interface, but supports directly getting C++ types without the intermediate Value and has the added failure case of the value being the wrong type.
 
Status validate (bool setValid=true)
 Runs all registered Constraints and returns the result. More...
 
Status setAll (const Environment &other)
 Sets all variables in the given Environment in this Environment. More...
 
bool count (const Key &key) const
 The functions below are the legacy interface to be consistent with boost::program_options::variables_map during the transition period. More...
 
Value operator[] (const Key &key) const
 
BSONObj toBSON () const
 Gets the BSON representation of this Environment. More...
 
void dump () const
 

Protected Attributes

std::vector< Constraint * > constraints
 
std::vector< KeyConstraint * > keyConstraints
 
std::map< Key, Valuevalues
 
std::map< Key, Valuedefault_values
 
bool valid
 

Detailed Description

An Environment is a map of values that can be validated according to a set of registered constraints.

Usage overview:

  1. Create an empty Environment
  2. Add Constraints
  3. Set Key/Value pairs (will not cause constraints to be triggered)
  4. Validate (will run all constraints)
  5. Access
  6. Set/Modify Key/Value pairs (will run all constraints and reject invalid modifications)
  7. Access

Since the constraints are run whenever we try to set or modify Key/Value pairs after we validate, we have the invariant that the Environment is always valid according to its Constraints after validation. Adding new constraints is disallowed after validation.

Usage example:

// Create an empty Environment Environment environment;

// Initialize our first Key and Value Key key1("key1"); Value value1(1);

// Add a Constraint on "key1" Status ret = environment.addConstraint(new ImmutableKeyConstraint("key1")); if (!ret.isOK()) { return ret; }

// Set our first Key and Value to the Environment ret = environment.set(key1, value1); if (!ret.isOK()) { return ret; }

// Attempt to mutate should be successful, since validate has not been called ret = environment.set(key1, Value(2)); if (!ret.isOK()) { return ret; }

// Validate our Environment ret = environment.validate(); if (!ret.isOK()) { return ret; }

// Access our Environment int intvalue1; ret = environment.get(key1, &intvalue1); if (!ret.isOK()) { return ret; }

// Attempt to mutate should fail, since validate has been called ret = environment.set(key1, Value(3)); if (!ret.isOK()) { return ret; }

Member Function Documentation

Status mongo::optionenvironment::Environment::addKeyConstraint ( KeyConstraint keyConstraint)

These functions are to add Constraints and KeyConstraints which will be run against this environment in the following situations:

  1. in the "validate" function
  2. in the "set" function after validate has been called successfully

It is an error to call these functions after "validate" has been called

NOTE: These DO NOT take ownership of the pointer passed in

bool mongo::optionenvironment::Environment::count ( const Key &  key) const

The functions below are the legacy interface to be consistent with boost::program_options::variables_map during the transition period.

Implementation of legacy interface to be consistent with boost::program_options::variables_map during the transition period.

Returns
1 if the given Key has a Value set in this Environment and 0 if not

boost::program_options::variables_map inherits the count function from std::map, which returns 1 if the value is set, and 0 if it is not set

Status mongo::optionenvironment::Environment::get ( const Key &  get_key,
Value get_value 
) const

Populate the given Value with the Value stored for the given Key.

Get the value at Key.

Return a success status if the value was found, or an error status if the value was not found. Leaves the Value unchanged on error.

Note that we should not be able to add empty values to the environment, so we don't check for that here

Value mongo::optionenvironment::Environment::operator[] ( const Key &  key) const
Returns
the Value for the given Key in this Environment. Returns an empty Value if Key is not set.
Status mongo::optionenvironment::Environment::remove ( const Key &  key)

Remove the Value from this Environment with the given Key.

Removes a Value from our Environment.

If "validate" has already been called on this Environment, runs all Constraints on the new Environment. If any of the Constraints fail, reverts to the old Environment and returns an error

Status mongo::optionenvironment::Environment::set ( const Key &  add_key,
const Value add_value 
)

Add the Value to this Environment with the given Key.

Set the Value in our Environment.

If "validate" has already been called on this Environment, runs all Constraints on the new Environment. If any of the Constraints fail, reverts to the old Environment and returns an error

Always disallow empty values

Status mongo::optionenvironment::Environment::setAll ( const Environment add_environment)

Sets all variables in the given Environment in this Environment.

Set all the Values from the source Environment in our Environment.

Does not add Constraints

Does not check for empty values as the source Environment should not have been allowed to have any

Status mongo::optionenvironment::Environment::setDefault ( const Key &  add_key,
const Value add_value 
)

Add a default Value to this Environment with the given Key.

Set the default Value for the given Key in our Environment.

Fails if validate has already been called on our environment. The get functions will return the default if one exists and the value has not been explicitly set.

Always disallow empty values

BSONObj mongo::optionenvironment::Environment::toBSON ( ) const

Gets the BSON representation of this Environment.

This will collapse dotted fields into sub objects.

Example:

The following Environment values map: "a.b.c" -> true "a.b.d" -> false "a.e.f" -> 0 "a.e.g" -> 1 "a.h" -> "foo"

Has a BSON represation of (shown as JSON): { "a" : { "b" : { "c" : true, "d" : false }, "e" : { "f" : 0, "g" : 1 }, "h" : "foo" } }

Note that the BSON representation only includes fields that were explicitly set using setAll or set, and not defaults that were specified using setDefault.

Status mongo::optionenvironment::Environment::validate ( bool  setValid = true)

Runs all registered Constraints and returns the result.

Validate the Environment by iterating over all our constraints and calling them on our Environment.

If "setValid" is true and validation succeeds, marks this as a valid Environment so that any modifications will re run all Constraints


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