# ECLogging

## Abstract

Class used for logging.

## Discussion

The logging mechanism behind is based on the following concepts:

- Logging Levels: Logging is categorized through logging levels. DEBUG, TRACE, INFO, WARN, ERROR, CRITICAL, FATAL are the supported levels.
- Logging Writers: The logging data can be written on various channels. At present a file writer as well as a NSLog writer are supported.
- Logging formatters: Logging formatters are used to format the the output before it is being sent to the writer...
- context: A context is used to select a certain logger.

All the objects behind can be configured and/or enhanced. They are bundled through a so-called logging configuration (instances of ECLoggingConfiguration). A logging configuration defines which format and which writer a certain level may use. Afterwards this configuration is registered under a certain so-called context. Objects use this context in order to get access to the corresponding logger.

Example of the definition of a logger: *

      ECLoggingConfiguration *loggingConfiguration;
      ECDefaultLoggingFormatter *loggingFormatter

      loggingWriter = [[[ECFileLoggingWriter alloc] init] autorelease];
      [loggingWriter setBaseFilename: @"sample.log"];

      loggingConfiguration = [[[ECLoggingConfiguration alloc] init] autorelease];

      [loggingConfiguration setLoggingLevel: @"DEBUG ];
      [loggingConfiguration setLoggingWriter: loggingWriter];
      [loggingConfiguration
        setLoggingFormatter:
          [[[ECDefaultLoggingFormatter alloc] init] autorelease]];

      [[ECLogging instance] addLoggingConfiguration: loggingConfiguration
          forContext: @"sample.context"];

The previous code registered a particular logging configuration using the context name "sample.context". Implementations may now use this configuration/logger by referring to this context:

      ECLogger *logger = [ECLogging loggerForContext: @"sample.context"];

      if( [logger isDebugEnabled] ) {
        [logger debug: @"This is a logging message of level DEBUG!"];
      }

      if( [logger isTraceEnabled] ) {
        [logger trace: @"Trace is given hereby..."];
      }

      if( [logger isInfoEnabled] ) {
        [logger info: @"This is a logging message of level INFO!"];
      }

      [logger error: @"Logging with error code=%u and msg=%@", 112,
        @"Error Message" ];

Contexts are hierarchically organized, where the dot "." separates a super-context from its sub-contexts. The selection of a logger therefor functions as follows: a configuration for a given context is valid for all the sub-contexts except for those child contexts defining their own configuration.

Say you have defined logging configurations for the following contexts:

- C1 defined for context: sample.context
- C2 defined for context: sample.context.A
- C2 defined for context: sample.context.A.B

For given contexts the following logging configurations will be used:

- sample.context.x chooses C1
- sample.context.A.a chooses C2
- sample.context.A.B.a.b chooses C3

If no logger could be found (e.g. "sample" wrt. example) then the root logger will be chosen, if defined.

The logging formatter as well as the logging writer can be configured in diverse ways. Additionally it should be easy to integrate own formatter or writers.

## Methods

`-addLoggingConfiguration:`
  adds a logging configuration for the given context.
`-addLoggingConfiguration:forContext:`
  adds a logging configuration for the given context.
`-addRootLoggingConfiguration:`
  defines the logger which is used in case a logger could not be found for a particular context
`-createAllSupercontextsOf:`
  creates all super contexts of a given context string.
`+forContext`
  Return a logging instance suitable for the given context.
`-init`
  initializes this object using the default logging formatter `` and ECNSLogLoggingWriter as the default logging writer
`+instance`
`-loggerForContext:((NSString *))`
  determines the logger for the given context
`+loggerForContext:((NSString *), (ECLoggingConfiguration *), (ECLoggingConfiguration *), (NSString *), (NSString *), (NSString *))`
  Return a logging instance suitable for the given context.

### addLoggingConfiguration:

adds a logging configuration for the given context.

See Also:

> addLoggingConfiguration:forContext:

>     - addLoggingConfiguration: (ECLoggingConfiguration *) aConfiguration forContext: (NSString *) aContext;

##### Parameter Descriptions

> `aConfiguration`
>   configuration to register
> `aContext`
>   context to register the configuration under

method result
  self

### addLoggingConfiguration:forContext:

adds a logging configuration for the given context.

See Also:

> addLoggingConfiguration:

>     - addLoggingConfiguration: (ECLoggingConfiguration *) aConfiguration forContext: (NSString *) aContext;

##### Parameter Descriptions

> `aConfiguration`
>   configuration to register
> `aContext`
>   context to register the configuration under

### addRootLoggingConfiguration:

defines the logger which is used in case a logger could not be found for a particular context

>     - addRootLoggingConfiguration: (ECLoggingConfiguration *) aConfiguration;

##### Parameter Descriptions

> `aConfiguration`
>   configuration of the logger

method result
  self

### createAllSupercontextsOf:

creates all super contexts of a given context string.

>     - (NSArray *) createAllSupercontextsOf: (NSString *) aContextStr;

method result
  array of super contexts where the first entry is the overall root context. The array may be empty if there exists no super context. The result does not contain the specified context strin g aContextStr itself.

##### Discussion

The set of super contexts of e.g. "com.company.context" is {"com.company", "com"}.

### forContext

Return a logging instance suitable for the given context.

See Also:

> loggerForContext:

>     + (ECLogger *) loggerForContext: (NSString *) aContext;

##### Parameter Descriptions

> `aContext`
>   implicitly specifies the output channel to be used

method result
  returns a logging instance suitable for the given context.

### init

initializes this object using the default logging formatter `` and ECNSLogLoggingWriter as the default logging writer

>     - init;

method result
  self

### instance

>     + (ECLogging *) instance;

method result
  the one and only logging instance

### loggerForContext:((NSString *))

determines the logger for the given context

>     - (ECLogger *) loggerForContext: (NSString *) aContext;

method result
  returns the logger which is suitable for the given context

### loggerForContext:((NSString *), (ECLoggingConfiguration *), (ECLoggingConfiguration *), (NSString *), (NSString *), (NSString *))

Return a logging instance suitable for the given context.

See Also:

> forContext

>     + (ECLogger *) loggerForContext: (NSString *) aContext;

##### Parameter Descriptions

> `aContext`
>   implicitly specifies the output channel to be used

(Last Updated August 27, 2006)