Component ball_loggercategoryutil [Package ball]

Provide a suite of utility functions for category management. More...

Namespaces
namespace	ball

---

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Deprecation Notice
  • Usage
    • Example 1: Managing Categories

Purpose:

Provide a suite of utility functions for category management.

Classes:

ball::LoggerCategoryUtil

namespace for category management utilities

See also:

Component ball_loggermanager, Component ball_categorymanager

Description:

This component defines a struct, ball::LoggerCategoryUtil, that provides a set of utility functions for managing the categories contained in a ball::LoggerManager based on the notion of hierarchy. In particular, the setThresholdLevelsHierarchically function modifies the threshold levels of each category in ball::LoggerManager whose name has the specified string as a prefix. The addCategoryHierarchically function creates a new category that inherits threshold levels from the exiting category whose name is the longest prefix match, if such a category exists.

Deprecation Notice:

The setThresholdLevels function is deprecated in favor of setThresholdLevelsHierarchically. The former is data-sensitive in the sense that the * located at the end of the specified category name will be treated as a special flag to turn on the prefix name matching, thus causing trouble for categories whose name ends with *.

Usage:

This section illustrates intended use of this component.

Example 1: Managing Categories:

The following code fragments illustrate basic usage of this component's setThresholdLevelsHierarchically and addCategoryHierarchically methods.

First, we create two auxiliary functions that serve to print out the names and threshold level values of all the categories currently in the logger manager singleton:

  void printCategory(const ball::Category *category)
  {
      bsl::cout << "\t[ " << category->categoryName()
                << ", "   << category->recordLevel()
                << ", "   << category->passLevel()
                << ", "   << category->triggerLevel()
                << ", "   << category->triggerAllLevel()
                << " ]"   << bsl::endl;
  }

  void printAllCategories()
  {
       ball::LoggerManager& lm = ball::LoggerManager::singleton();
       using namespace bdlf::PlaceHolders;
       lm.visitCategories(bdlf::BindUtil::bind(printCategory, _1));
  }

Now, we set the default threshold levels of the logger manager object to [191, 95, 63, 31] (for brevity, the initialization of the logger manager singleton is elided):

      ball::LoggerManager& lm = ball::LoggerManager::singleton();
      lm.setDefaultThresholdLevels(191, 95, 63, 31);

Then, we create two new categories, "EQ" and "EQ.MARKET", by calling the addCategory method of the logger manager class, with their threshold levels explicitly set to different values (which are also different from the default threshold levels):

     lm.addCategory("EQ", 192, 96, 64, 32);
     lm.addCategory("EQ.MARKET", 193, 97, 65, 33);
     printAllCategories();

The following is printed out by printAllCategories:

     [ EQ, 192, 96, 64, 32 ]
     [ EQ.MARKET, 193, 97, 65, 33 ]

Next, we add a new category using addCategoryHierarchically:

     ball::LoggerCategoryUtil::addCategoryHierarchically(&lm,
                                                         "EQ.MARKET.NYSE");
     printAllCategories();

The new category with name "EQ.MARKET.NYSE" inherits its threshold levels from the category "EQ.MARKET" rather than having the default threshold levels or inheriting them from "EQ" because of the longest prefix matching rule:

     [ EQ, 192, 96, 64, 32 ]
     [ EQ.MARKET, 193, 97, 65, 33 ]
     [ EQ.MARKET.NYSE, 193, 97, 65, 33 ]

Then, we adjust the threshold levels for all categories whose name starts with "EQ.MARKET" using setThresholdLevelsHierarchically:

     ball::LoggerCategoryUtil::setThresholdLevelsHierarchically(&lm,
                                                                "EQ.MARKET",
                                                                194,
                                                                98,
                                                                66,
                                                                34);
     printAllCategories();

We will notice that the threshold levels of "EQ.MARKET" and "EQ.MARKET.NYSE" have been changed to the new values, while those of "EQ" remain unchanged:

     [ EQ, 192, 96, 64, 32 ]
     [ EQ.MARKET, 194, 98, 66, 34 ]
     [ EQ.MARKET.NYSE, 194, 98, 66, 34 ]