3_log4cpp的Category类
1 log4cpp
log4cpp种最重要的概念有
Category(种类）、Appender(附加器)、layout(布局)、Priority(优先级)、NDC(嵌套的诊断上下文)。
其中,Category、Appender与Layout三者的关系如下图所示：
2 Category类
log4cpp有且只有一个根类rootCategory，可以有多个子Category组成树结构。
2.1 Name 属性
2.1.1 定义
/** The name of this category. */
const std::string _name;
2.1.2 getName方法
/**
* Return the category name.
* @returns The category name.
*/
virtual const std::string& getName() const throw();
2.2 Priority属性
日志优先级，
- 对于根
Category，必须指定Priority， - 对于非根
Category，可以不指定Priority，此时优先级继承自父Category - 对于非根
Category，当指定Priority，此时优先级覆盖自父Category
2.2.1 定义
详细信息查阅Priority类
/**
* The assigned priority of this category.
**/
volatile Priority::Value _priority;
2.2.2 setPriority方法
设置当前Category的优先级
/**
* Set the priority of this Category.
* @param priority The priority to set. Use Priority::NOTSET to let
* the category use its parents priority as effective priority.
* @exception std::invalid_argument if the caller tries to set
* Priority::NOTSET on the Root Category.
**/
virtual void setPriority(Priority::Value priority);
2.2.3 getPriority方法
获取当前对象的优先级
/**
* Returns the assigned Priority, if any, for this Category.
* @return Priority - the assigned Priority, can be Priority::NOTSET
**/
virtual Priority::Value getPriority() const throw();
2.2.4 setRootPriority方法
设置RootCategory的优先级
/**
* Set the priority of the root Category.
* @param priority The new priority for the root Category
**/
static void setRootPriority(Priority::Value priority);
2.2.5 getRootPriority方法
获取root Category的优先级
/**
* Get the priority of the <code>root</code> Category.
* @returns the priority of the root category
**/
static Priority::Value getRootPriority() throw();
2.2.6 getChainedPriority方法
获取当前category继承表中的优先级，如果当前的优先值没有设置的话，则找他的父亲，如果父亲没有找到的话，他会继续向上找，因为root Category的优先值默认为Priority::INFO，所以肯定是能够找到的
/**
* Starting from this Category, search the category hierarchy for a
* set priority and return it. Otherwise, return the priority
* of the root category.
*
* <p>The Category class is designed so that this method executes as
* quickly as possible.
**/
virtual Priority::Value getChainedPriority() const throw();
2.2.7 isPriorityEnabled方法
返回当前拥有priority优先级
/**
* Returns true if the chained priority of the Category is equal to
* or higher than given priority.
* @param priority The priority to compare with.
* @returns whether logging is enable for this priority.
**/
virtual bool isPriorityEnabled(Priority::Value priority) const throw();
2.3 additivity属性
每一个Category都有一个additivity属性，该属性值默认为true。
- 如果该值为
true，则该Category的Appender包含父Category的Appender。 - 如果该值为
false，则该Category的Appender取代父Category的Appender。
2.3.1 定义
/**
* Additivity is set to true by default, i.e. a child inherits its
* ancestor's appenders by default.
*/
volatile bool _isAdditive;
2.3.2 setAdditivity方法
设置Category的Additivity属性值。
/**
* Set the additivity flag for this Category instance.
**/
virtual void setAdditivity(bool additivity);
2.3.3 getAdditivity方法
获取Category的Additivity属性值。
/**
* Returns the additivity flag for this Category instance.
**/
virtual bool getAdditivity() const throw();
2.4 parent属性
上级Category，根Category的parent为空。
2.4.1 定义
/**
* The parent of this category. All categories have al least one
* ancestor which is the root category.
**/
Category* _parent;
2.4.2 getParent方法
如果父category存在，返回父category的指针，否则返回NULL
/**
* Returns the parent category of this category, or NULL
* if the category is the root category.
* @return the parent category.
**/
virtual Category* getParent() throw();
/**
* Returns the parent category of this category, or NULL
* if the category is the root category.
* @return the parent category.
**/
virtual const Category* getParent() const throw();
2.5 Appender
在一个Category中，Appender是以set的行驶存储的，其定义如下：
typedef std::set<Appender *> AppenderSet;
AppenderSet _appender;
2.5.1 addAppender(Appender* appender);
添加一个Appender到Category中，并将Appender的所有权交给Category进行管理
/**
* Adds an Appender to this Category.
* This method passes ownership from the caller to the Category.
* @since 0.2.7
* @param appender The Appender to wich this category has to log.
* @exception std::invalid_argument if the appender is NULL.
**/
virtual void addAppender(Appender* appender);
2.5.2 addAppender(Appender& appender)
添加一个Appender到Category中。 但是该方法并不把Appender的所有权交给Category管理
/**
* Adds an Appender for this Category.
* This method does not pass ownership from the caller to the Category.
* @since 0.2.7
* @param appender The Appender this category has to log to.
**/
virtual void addAppender(Appender& appender);
2.5.3 getAppender()
返回Category中的第一个Appender的指针，如果为空就返回NULL
/**
* Returns the first Appender for this Category, or NULL if no
* Appender has been set.
* @deprecated use getAppender(const std::string&)
* @returns The Appender.
**/
virtual Appender* getAppender() const;
2.5.4 getAppender(const std::string& name)
返回名字为name的Appender的指针
/**
* Returns the specified Appender for this Category, or NULL if
* the Appender is not attached to this Category.
* @since 0.2.7
* @returns The Appender.
**/
virtual Appender* getAppender(const std::string& name) const;
2.5.5 getAllAppenders()
获取所有的Appender
/**
* Returns the set of Appenders currently attached to this Catogory.
* @since 0.3.1
* @returns The set of attached Appenders.
**/
virtual AppenderSet getAllAppenders() const;
2.5.6 removeAllAppenders()
删除所有的Appender
/**
* Removes all appenders for this Category.
**/
virtual void removeAllAppenders();
2.5.7 removeAppender(Appender* appender)
删除指定的Appender。
/**
* Removes specified appender for this Category.
* @since 0.2.7
**/
virtual void removeAppender(Appender* appender);
2.5.8 ownsAppender
判断指定的Appender是否被当前的Category拥有所有权
/**
* Returns true if the Category owns the Appender. In that case the
* Category destructor will delete the Appender.
* @since 0.2.7
**/
virtual bool ownsAppender(Appender* appender) const throw();
2.6 log
2.6.1 log(Priority::Value priority, const char* stringFormat,…)
指定日志优先级记录日志，采用格式化生成字符串
/**
* Log a message with the specified priority.
* @param priority The priority of this log message.
* @param stringFormat Format specifier for the string to write
* in the log file.
* @param ... The arguments for stringFormat
**/
virtual void log(Priority::Value priority, const char* stringFormat,...) throw();
2.6.2 log(Priority::Value priority, const std::string& message)
指定日志优先级记录日志。
/**
* Log a message with the specified priority.
* @param priority The priority of this log message.
* @param message string to write in the log file
**/
virtual void log(Priority::Value priority, const std::string& message) throw();
2.7 静态方法
2.7.1 getRoot
取得根Category。
/**
* Return the root of the Category hierarchy.
*
* <p>The root category is always instantiated and available. It's
* name is the empty string.
* <p>Unlike in log4j, calling <code>Category.getInstance("")</code>
* <em>does</em> retrieve the root category
* and not a category just under root named "".
* @returns The root category
**/
static Category& getRoot();
2.7.2 getInstance
取得指定名称（参数name）的Category，如果不存在，则自动创建一个以name命名，parent为rootCategory，Priority为INFO的Category。
/**
* Instantiate a Category with name <code>name</code>. This
* method does not set priority of the category which is by
* default <code>Priority::NOTSET</code>.
*
* @param name The name of the category to retrieve.
**/
static Category& getInstance(const std::string& name);
2.7.3 exists
判断指定名称的Category是否存在，如果存在，则返回相应的Category，否则返回空指针。
/**
* If the named category exists (in the default hierarchy) then it
* returns a reference to the category, otherwise it returns NULL.
* @since 0.2.7
**/
static Category* exists(const std::string& name);
2.7.4 shutdown
从所有的Category中清除所有的Appender
/**
* This method will remove all Appenders from Categories.XXX
**/
static void shutdown();
2.7.5 shutdownForced
shutdownForced将从所有的Category中清除所有的Appender，并删除所有的Appender。
/**
* This method will remove all Appenders from Categories.XXX and delete all appenders.
* Releases more memory than shutdown() by deleting appenders.
**/
static void shutdownForced();
3 Layout类
Layout类控制输出日志的显示样式，
3.1 BasicLayout
继承自类Layout，输出格式为时间戳、权限、种类、ndc、日志信息。
/**
* Formats the LoggingEvent in BasicLayout style:<br>
* "timeStamp priority category ndc: message"
**/
virtual std::string format(const LoggingEvent& event);
3.2 PassThroughLayout
支持自定义的布局，可以继承他实现自定义的日志格式。
public:
virtual std::string format(const LoggingEvent& event) { return event.message; }
3.3 PatternLayout
log4cpp支持用户配置日志格式.
%% - 转义字符'%'
%c - Category
%d - 日期；日期可以进一步设置格式，用花括号包围，例如%d{%H:%M:%S,%l}。日期的格式符号与ANSI C函数strftime中的一致。但增加了一个格式符号%l，表示毫秒，占三个十进制位。
%m - 消息
%n - 换行符；会根据平台的不同而不同，但对用户透明。
%p - 优先级
%r - 自从layout被创建后的毫秒数
%R - 从1970年1月1日开始到目前为止的秒数
%u - 进程开始到目前为止的时钟周期数
%x - NDC
%t - 线程id
3.4 SimpleLayout
比BasicLayout还简单的日志格式输出。
/**
* Formats the LoggingEvent in SimpleLayout style:<br>
* "priority - message"
**/
virtual std::string format(const LoggingEvent& event);
4 Priority类
4.1 日志等级分类
log4cpp内置了10个日志等级，取值越小，优先级越高。
typedef enum { EMERG = 0,
FATAL = 0,
ALERT = 100,
CRIT = 200,
ERROR = 300,
WARN = 400,
NOTICE = 500,
INFO = 600,
DEBUG = 700,
NOTSET = 800
} PriorityLevel;
5 NDC
NDC是Nested Diagnostic Contexts，译为：嵌套诊断上下文，可以使用NDC更好的跟踪程序运行轨迹。
NDC是以线程为基础的，每个线程有且只有一个NDC。
5.1 NDC常用方法
5.1.1 pop()
客户端应该在离开诊断上下文之前调用此方法。
/**
Clients should call this method before leaving a diagnostic
context.
<p>The returned value is the value that was pushed last. If no
context is available, then the empty string "" is returned.
@return String The innermost diagnostic context.
**/
static std::string pop();
5.1.2 push(const std::string& message)
为当前线程推送新的诊断上下文信息。
/**
Push new diagnostic context information for the current thread.
<p>The contents of the <code>message</code> parameter is
determined solely by the client.
@param message The new diagnostic context information.
**/
static void push(const std::string& message);
5.1.3 get()
获取当前诊断上下文字符串
/**
Get the current diagnostic context string.
@return the context string.
**/
static const std::string& get();
5.1.4 clear()
如果有任何嵌套的不可知信息就进行清除。当同一线程可能在不同的不相关上下文中反复使用时，这种方法非常有用。
/**
Clear any nested disgnostic information if any. This method is
useful in cases where the same thread can be potentially used
over and over in different unrelated contexts.
<p>This method is equivalent to calling the <code>setMaxDepth</code>
method with a zero <code>maxDepth</code> argument.
**/
static void clear();
