From: znek Date: Wed, 17 Nov 2004 18:29:39 +0000 (+0000) Subject: improved API and documentation X-Git-Url: https://err.no/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=61879b49f7cbc5be91e5c46018ed0fb2b37067f3;p=sope improved API and documentation git-svn-id: http://svn.opengroupware.org/SOPE/trunk@389 e4a50df8-12e2-0310-a44c-efbce7f8a7e3 --- diff --git a/sope-core/NGExtensions/ChangeLog b/sope-core/NGExtensions/ChangeLog index 29e08c57..6679ca3e 100644 --- a/sope-core/NGExtensions/ChangeLog +++ b/sope-core/NGExtensions/ChangeLog @@ -1,5 +1,7 @@ 2004-11-17 Marcus Mueller + * NGLogging: updated (v4.5.132) + * NGLogging: updated (v4.5.131) 2004-11-17 Matthew Joyce diff --git a/sope-core/NGExtensions/NGExtensions/NGLogAppender.h b/sope-core/NGExtensions/NGExtensions/NGLogAppender.h index 3de602ac..713413dc 100644 --- a/sope-core/NGExtensions/NGExtensions/NGLogAppender.h +++ b/sope-core/NGExtensions/NGExtensions/NGLogAppender.h @@ -23,6 +23,8 @@ #define __NGExtensions_NGLogAppender_H_ /* + NGLogAppender + Abstract superclass for all log appenders. */ diff --git a/sope-core/NGExtensions/NGExtensions/NGLogConsoleAppender.h b/sope-core/NGExtensions/NGExtensions/NGLogConsoleAppender.h index ec8c8b74..2fca9c9c 100644 --- a/sope-core/NGExtensions/NGExtensions/NGLogConsoleAppender.h +++ b/sope-core/NGExtensions/NGExtensions/NGLogConsoleAppender.h @@ -22,6 +22,15 @@ #ifndef __NGExtensions_NGLogConsoleAppender_H_ #define __NGExtensions_NGLogConsoleAppender_H_ +/* + NGLogConsoleAppender + + A very simple console appender. The current implementation logs the + formatted event via NSLog(). Please note that doing so discards the timestamp + saved in the event, so the logged time isn't really exact, but will probably + only differ marginally. +*/ + #include @interface NGLogConsoleAppender : NGLogAppender diff --git a/sope-core/NGExtensions/NGExtensions/NGLogEvent.h b/sope-core/NGExtensions/NGExtensions/NGLogEvent.h index b507c96f..8b2f8b42 100644 --- a/sope-core/NGExtensions/NGExtensions/NGLogEvent.h +++ b/sope-core/NGExtensions/NGExtensions/NGLogEvent.h @@ -22,6 +22,14 @@ #ifndef __NGExtensions_NGLogEvent_H_ #define __NGExtensions_NGLogEvent_H_ +/* + NGLogEvent + + Instances of this class encapsulate log events, retaining all vital + information associated with it. Log events are generally passed on to + log appenders for further treatment. +*/ + #import #import diff --git a/sope-core/NGExtensions/NGExtensions/NGLogSyslogAppender.h b/sope-core/NGExtensions/NGExtensions/NGLogSyslogAppender.h index 2539e7b6..17bec5a8 100644 --- a/sope-core/NGExtensions/NGExtensions/NGLogSyslogAppender.h +++ b/sope-core/NGExtensions/NGExtensions/NGLogSyslogAppender.h @@ -22,14 +22,31 @@ #ifndef __NGExtensions_NGLogSyslogAppender_H_ #define __NGExtensions_NGLogSyslogAppender_H_ -#include - /* NGLogSyslogAppender - An appender which writes to the systems syslog facility. + An appender which writes to the system's syslog facility. + + Use the user default key "NGLogSyslogIdentifier" to set the syslog + identifier. The syslog identifier is a string that will be prepended to every + message. See your operating system's manpage on syslog for details. + + Note: syslog doesn't support user provided timestamps, thus this information + provided by NGLogEvent is silently discarded. + + The following scheme is used to map NGLogLevels to syslog's levels: + + NGLogLevel syslog + -------------------------- + NGLogLevelDebug LOG_DEBUG + NGLogLevelInfo LOG_INFO + NGLogLevelWarn LOG_WARNING + NGLogLevelError LOG_ERR + NGLogLevelFatal LOG_ALERT */ +#include + @class NSString; @interface NGLogSyslogAppender : NGLogAppender diff --git a/sope-core/NGExtensions/NGExtensions/NGLogger.h b/sope-core/NGExtensions/NGExtensions/NGLogger.h index d5dbda1a..72c86ef8 100644 --- a/sope-core/NGExtensions/NGExtensions/NGLogger.h +++ b/sope-core/NGExtensions/NGExtensions/NGLogger.h @@ -25,9 +25,18 @@ /* NGLogger - A logger class, modeled closely after Log4J. - - TODO: explain more. + NGLogger has a minimum log level and passes messages to its appenders + only if this minimum log level is satisfied - otherwise it silently drops + these messages. + + Note: Except in rare circumstances, do not allocate loggers yourself. Always + try to use the appropriate API of NGLoggerManager if possible. + + Note: Currently the NGLogger implementation lacks an API for configuring + appenders. Until this has been done appropriately, use the + "NGLogDefaultAppenderClass" user default to select an appropriate + default appender. If this default isn't set, "NGLogConsoleAppender" + is used. */ #import diff --git a/sope-core/NGExtensions/NGExtensions/NGLoggerManager.h b/sope-core/NGExtensions/NGExtensions/NGLoggerManager.h index b83c1398..f1e74ecf 100644 --- a/sope-core/NGExtensions/NGExtensions/NGLoggerManager.h +++ b/sope-core/NGExtensions/NGExtensions/NGLoggerManager.h @@ -22,6 +22,19 @@ #ifndef __NGExtensions_NGLoggerManager_H_ #define __NGExtensions_NGLoggerManager_H_ +/* + NGLoggerManager + + Manages a set of loggers by associating logger instances with names. Thus + clients will be given the same instances if accessing the manager with the + same name/key. Also, NGLoggerManager offers conditional creation of loggers + based on user default keys (and special values associated with these keys). + + It's planned that NGLoggerManager will be provided with a configuration of + some sort at a later stage, so configuration of log levels and appenders for + loggers can reach a similar dynamism as is currently achieved in Log4J. +*/ + #import @class NSString, NSMutableDictionary; @@ -34,10 +47,20 @@ + (id)defaultLoggerManager; -/* operations */ - +/* Retrieves a logger conditional to the existence of the given default key. + In order to stay backwards compatible to existing applications, a boolean + value auf YES associated with this key sets the default log level of this + logger to NGLogLevelDebug. Other possible values for this key include + "DEBUG, "INFO", "WARN", "ERROR" and "FATAL". Everything else will be mapped + to NGLogLevelAll. If the requested default key is not set, *nil* is + returned. +*/ - (NGLogger *)loggerForDefaultKey:(NSString *)_defaultKey; +/* Retrieves a "named" logger with NGLogLevelAll. */ +- (NGLogger *)loggerForFacilityNamed:(NSString *)_name; +- (NGLogger *)loggerForClass:(Class)_clazz; + @end #endif /* __NGExtensions_NGLoggerManager_H_ */ diff --git a/sope-core/NGExtensions/NGExtensions/NGLogging.h b/sope-core/NGExtensions/NGExtensions/NGLogging.h index b4d0b4b8..efb4aac6 100644 --- a/sope-core/NGExtensions/NGExtensions/NGLogging.h +++ b/sope-core/NGExtensions/NGExtensions/NGLogging.h @@ -23,8 +23,10 @@ #define __NGExtensions_NGLogging_H_ /* - NGLogging is a somewhat more sophisticated logging framework, modeled - apparently similar to log4j - without some of its bloat. + NGLogging is a new logging framework, modeled in a similar fashion as Log4J + - without some of its bloat. + + Documentation is currently provided in the headers only. */ #include diff --git a/sope-core/NGExtensions/NGExtensions/NSObject+ExtendedLogging.h b/sope-core/NGExtensions/NGExtensions/NSObject+ExtendedLogging.h index afdf3dea..8fc860f2 100644 --- a/sope-core/NGExtensions/NGExtensions/NSObject+ExtendedLogging.h +++ b/sope-core/NGExtensions/NGExtensions/NSObject+ExtendedLogging.h @@ -22,6 +22,17 @@ #ifndef __NSObject_ExtendedLogging_H_ #define __NSObject_ExtendedLogging_H_ +/* + Logging convenience for the new NGLogger based API. + + The default implementation uses the "NGDefaultLogLevel" user default key to + retrieve a logger from the NGLoggerManager. If this default isn't set, + a default logger with log level NGLogLevelInfo will be instantiated. + + Consult the header of NGLoggerManager for further details on setting the + "NGDefaultLogLevel" user default. +*/ + #import typedef enum { @@ -36,6 +47,7 @@ typedef enum { @interface NSObject(NGExtendedLogging) ++ (id)logger; - (id)logger; /* convenience methods */ diff --git a/sope-core/NGExtensions/NGLogging.subproj/ChangeLog b/sope-core/NGExtensions/NGLogging.subproj/ChangeLog index dfb9ca4e..6626a0cc 100644 --- a/sope-core/NGExtensions/NGLogging.subproj/ChangeLog +++ b/sope-core/NGExtensions/NGLogging.subproj/ChangeLog @@ -1,5 +1,10 @@ 2004-11-17 Marcus Mueller + * *.h: provided some documentation + + * NGLoggerManager.[hm]: new method -loggerForFacilityNamed: for + sharing/referencing instances based on names. + * NSObject+NGExtendedLogging.h: fixed some serious misordering in log levels (thanks to Helge Hess for reporting this! ;-) diff --git a/sope-core/NGExtensions/NGLogging.subproj/NGLoggerManager.m b/sope-core/NGExtensions/NGLogging.subproj/NGLoggerManager.m index d598e8b0..4d442a69 100644 --- a/sope-core/NGExtensions/NGLogging.subproj/NGLoggerManager.m +++ b/sope-core/NGExtensions/NGLogging.subproj/NGLoggerManager.m @@ -92,6 +92,26 @@ static NSNull *sharedNull; return (logger != sharedNull) ? logger : nil; } +- (NGLogger *)loggerForFacilityNamed:(NSString *)_name { + id logger; + + logger = [self->loggerMap objectForKey:_name]; + if (!logger) { + logger = [[NGLogger alloc] init]; + [self->loggerMap setObject:logger forKey:_name]; + [logger release]; + } + return logger; +} + +- (NGLogger *)loggerForClass:(Class)_clazz { + NSString *name; + + name = NSStringFromClass(_clazz); + return [self loggerForFacilityNamed:name]; +} + + /* Private */ - (NGLogLevel)_logLevelForString:(NSString *)_defaultValue { diff --git a/sope-core/NGExtensions/NGLogging.subproj/NSObject+ExtendedLogging.m b/sope-core/NGExtensions/NGLogging.subproj/NSObject+ExtendedLogging.m index 4551c7e8..dba4b6fa 100644 --- a/sope-core/NGExtensions/NGLogging.subproj/NSObject+ExtendedLogging.m +++ b/sope-core/NGExtensions/NGLogging.subproj/NSObject+ExtendedLogging.m @@ -26,21 +26,26 @@ @implementation NSObject(NGExtendedLogging) -- (id)logger { - static id sharedLogger = nil; - static BOOL shouldLog = YES; ++ (id)logger { + static id sharedLogger = nil; - if (sharedLogger == nil && shouldLog) { + if (sharedLogger == nil) { NGLoggerManager *lm; - + lm = [NGLoggerManager defaultLoggerManager]; sharedLogger = [lm loggerForDefaultKey:@"NGDefaultLogLevel"]; - if (!sharedLogger) - shouldLog = NO; + if (!sharedLogger) { + sharedLogger = [lm loggerForFacilityNamed:@"root"]; + [sharedLogger setLogLevel:NGLogLevelInfo]; + } } return sharedLogger; } +- (id)logger { + return [[self class] logger]; +} + /* log methods */ - (void)logDebugWithFormat:(NSString *)_fmt, ... { @@ -49,7 +54,7 @@ va_list va; logger = [self logger]; - if(![logger isLogDebugEnabled]) + if (![logger isLogDebugEnabled]) return; va_start(va, _fmt); @@ -65,7 +70,7 @@ va_list va; logger = [self logger]; - if(![logger isLogInfoEnabled]) + if (![logger isLogInfoEnabled]) return; va_start(va, _fmt); @@ -81,7 +86,7 @@ va_list va; logger = [self logger]; - if(![logger isLogWarnEnabled]) + if (![logger isLogWarnEnabled]) return; va_start(va, _fmt); @@ -97,7 +102,7 @@ va_list va; logger = [self logger]; - if(![logger isLogErrorEnabled]) + if (![logger isLogErrorEnabled]) return; va_start(va, _fmt); @@ -113,7 +118,7 @@ va_list va; logger = [self logger]; - if(![logger isLogFatalEnabled]) + if (![logger isLogFatalEnabled]) return; va_start(va, _fmt); diff --git a/sope-core/NGExtensions/Version b/sope-core/NGExtensions/Version index d4cea4ee..52895010 100644 --- a/sope-core/NGExtensions/Version +++ b/sope-core/NGExtensions/Version @@ -1,6 +1,6 @@ # version -SUBMINOR_VERSION:=131 +SUBMINOR_VERSION:=132 # v4.3.115 requires libFoundation v1.0.59 # v4.2.72 requires libEOControl v4.2.39