Component ball_recordattributes [Package ball]

Provide a container for a fixed set of fields suitable for logging. More...

Namespaces
namespace	ball

---

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Usage
    • Example 1: Syntax
    • Example 2: Streaming Data Into a Message Attribute

Purpose:

Provide a container for a fixed set of fields suitable for logging.

Classes:

ball::RecordAttributes

container for a fixed set of log fields

See also:

Component ball_record

Description:

This component defines a container for aggregating a fixed set of fields intrinsically appropriate for logging. Using ball::RecordAttributes, a logger can transmit log message text together with relevant auxiliary information (e.g., timestamp, filename, line number, etc.) as a single instance, rather than passing around individual attributes separately.

The attributes held by ball::RecordAttributes are given in the following table:

     Attribute        Type               Description               Default
     ----------   -------------   ------------------------------   --------
     timestamp    bdlt::Datetime  creation date and time           (*Note*)
     processID    int             process id of creator            0
     threadID     Uint64          thread id of creator             0
     fileName     string          file where created  (__FILE__)   ""
     lineNumber   int             line number in file (__LINE__)   0
     category     string          category of logged record        ""
     severity     int             severity of logged record        0
     message      string          log message text                 ""

Note: The default value given to the timestamp attribute is implementation defined. (See the bdlt_datetime component-level documentation for more information.)

For each attribute, there is a method to access its value and a method to change its value. E.g., for the timestamp attribute, there is the timestamp accessor and the setTimestamp manipulator. Note, that for the message attribute, there is message accessor which is deprecated, use the messageRef accessor instead. The class also provides the ability to stream an object (whose class must support the operator<<) into the message attribute using messageStreamBuf method (see the usage example-2). The default values listed in the table above are the values given to the respective attributes by the default constructor of ball::RecordAttributes.

Usage:

This section illustrates intended use of this component.

Example 1: Syntax:

The ball::RecordAttributes class holds sufficient information on which to base a rudimentary logging, tracing, or reporting facility. The following code fragments illustrate the essentials of working with these attributes.

Assume that our example is part of a financial application using categories and message severities as follows:

      const char *Category[] = { "Bonds", "Equities", "Futures" };
      enum { INFO, WARN, BUY, SELL };

First define a ball::RecordAttributes object with each attribute initialized to its default value:

      ball::RecordAttributes attributes;

Next set each of the attributes to some meaningful value:

      bdlt::Datetime now;
      bdlt::EpochUtil::convertFromTimeT(&now, time(0));
      attributes.setTimestamp(now);                // current time
      attributes.setProcessID(getpid());
      attributes.setThreadID((bsls::Types::Uint64) pthread_self());
      attributes.setFileName(__FILE__);
      attributes.setLineNumber(__LINE__);
      attributes.setCategory(Category[2]);         // "Futures"
      attributes.setSeverity(WARN);
      attributes.setMessage("sugar up (locust infestations on the rise)");

The message in this example briefly informs that something interesting may be happening with respect to sugar futures. In general, the message attribute can contain an arbitrary amount of information.

Now that the sample ball::RecordAttributes object has been populated with the desired information, it can be passed to a function, stored in a database, cached in a container of ball::RecordAttributes objects, etc. For the purposes of this illustration, we'll simply format and stream selected attributes to a specified ostream using the following function:

      void printMessage(ostream&                      stream,
                        const ball::RecordAttributes& attributes)
      {
          using namespace std;
          stream << "\tTimestamp: " << attributes.timestamp()  << endl;
          stream << "\tCategory:  " << attributes.category()   << endl;
          stream << "\tMessage:   " << attributes.messageRef() << endl;
          stream << endl;
      }

The following call:

      printMessage(bsl::cout, attributes);

prints these attributes to stdout:

              Timestamp: 19JAN2004_23:07:38.000
              Category:  Futures
              Message:   sugar up (locust infestations on the rise)

Example 2: Streaming Data Into a Message Attribute:

Following example demonstrates how an object of a class supporting ostream operation (operator<<) can be streamed into the message attribute. Suppose we want to stream objects of the following class.

    class Information
    {
      private:
        bsl::string d_heading;
        bsl::string d_contents;

      public:
        Information(const char *heading, const char *contents);
        const bsl::string& heading() const;
        const bsl::string& contents() const;
    };

The component containing the Information must provide operator<<. Here is a possible implementation.

    bsl::ostream& operator<<(bsl::ostream&      stream,
                             const Information& information)
    {
        stream << information.heading() << endl;
        stream << '\t';
        stream << information.contents() << endl;
        return stream;
    }

The following function streams an Information object into the message attribute of a ball::RecordAttributes object.

    void streamInformationIntoMessageAttribute(
                                         ball::RecordAttributes& attributes,
                                         const Information&      information)
    {
        // First clear the message attributes.
        attributes.clearMessage();

        // Create an 'ostream' from message stream buffer.
        bsl::ostream os(&attributes.messageStreamBuf());

        // Now stream the information object into the created ostream.
        // This will set the message attribute of 'attributes' to the
        // streamed contents.
        os << information;
    }