ball_defaultattributecontainer

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

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());