Component ball_defaultattributecontainer [Package ball]

Provide a default container for storing attribute name/value pairs. More...

Namespaces
namespace	ball

---

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Thread Safety
  • Usage
    • Example 1: Basic Usage of ball::DefaultAttributeContainer

Purpose:

Provide a default container for storing attribute name/value pairs.

Classes:

ball::DefaultAttributeContainer

a collection of unique attributes

See also:

Component ball_attributecontainer

Description:

This component provides a default implementation of the ball::AttributeContainer protocol, ball::DefaultAttributeContainer providing an unordered_set-based container of ball::Attribute values. Each attribute within the default attribute container holds a (case-sensitive) name and a value, which may be an int, a 64-bit integer, or a bsl::string.

This component participates in the implementation of "Rule-Based Logging". For more information on how to use that feature, please see the package level documentation and usage examples for "Rule-Based Logging".

Thread Safety:

ball::DefaultAttributeContainer is const thread-safe, meaning that accessors may be invoked concurrently from different threads, but it is not safe to access or modify a ball::DefaultAttributeContainer in one thread while another thread modifies the same object.

Usage:

This section illustrates the intended use of this component.

Example 1: Basic Usage of ball::DefaultAttributeContainer:

A ball::DefaultAttributeContainer initially has no attributes when created by the default constructor:

    ball::DefaultAttributeContainer attributeContainer;

Let's now create some attributes and add them to the attribute map:

    ball::Attribute a1("uuid", 1111);
    ball::Attribute a2("sid", "111-1");
    assert(true == attributeContainer.addAttribute(a1));
    assert(true == attributeContainer.addAttribute(a2));

New attributes with a name that already exists in the map can be added, as long as they have a different value:

    ball::Attribute a3("uuid", 2222);
    ball::Attribute a4("sid", "222-2");
    assert(true == attributeContainer.addAttribute(a3));
    assert(true == attributeContainer.addAttribute(a4));

But attributes having the same name and value cannot be added:

    ball::Attribute a5("uuid", 1111);                 // same as 'a1'
    assert(false == attributeContainer.addAttribute(a5));

Note that the attribute name is case-sensitive:

    ball::Attribute a6("UUID", 1111);
    assert(true == attributeContainer.addAttribute(a6));

Existing attributes can be looked up by the hasValue method:

    assert(true == attributeContainer.hasValue(a1));
    assert(true == attributeContainer.hasValue(a2));
    assert(true == attributeContainer.hasValue(a3));
    assert(true == attributeContainer.hasValue(a4));
    assert(true == attributeContainer.hasValue(a5));
    assert(true == attributeContainer.hasValue(a6));

Or removed by the removeAttribute method:

    defaultattributecontainer.removeAttribute(a1);
    assert(false == attributeContainer.hasValue(a1));

Also, the ball::DefaultAttributeContainer class provides an iterator:

    ball::DefaultAttributeContainer::const_iterator iter =
                                                  attributeContainer.begin();
    for ( ; iter != attributeContainer.end(); ++iter ) {
        bsl::cout << *iter << bsl::endl;
    }

Finally, we can provide a visitor functor and visit all attributes in the container. Note that this usage example uses lambdas and requires C++11. Lambdas can be replaced with named functions for C++03.

    bsl::vector<ball::Attribute> result;
    attributeContainer.visitAttributes(
        [&result](const ball::Attribute& attribute)
          {
              result.push_back(attribute);
          });
    assert(4 == result.size());