Object
The Appender class is provides methods for appending log events to a logging destination. The log events are formatted into strings using a Layout.
All other Appenders inherit from this class which provides stub methods. Each subclass should provide a write method that will write log messages to the logging destination.
A private sync method is provided for use by subclasses. It is used to synchronize writes to the logging destination, and can be used by subclasses to synchronize the closing or flushing of the logging destination.
Creates a new appender using the given name. If no Layout is specified, then a Basic layout will be used. Any logging header supplied by the layout will be written to the logging destination when the Appender is created.
Options:
:layout => the layout to use when formatting log events :level => the level at which to log
# File lib/logging/appender.rb, line 35 35: def initialize( name, opts = {} ) 36: ::Logging.init unless ::Logging.initialized? 37: 38: @name = name.to_s 39: @closed = false 40: 41: self.layout = opts.getopt(:layout, ::Logging::Layouts::Basic.new) 42: self.level = opts.getopt(:level) 43: 44: @mutex = ReentrantMutex.new 45: 46: if opts.getopt(:header, true) 47: header = @layout.header 48: 49: unless header.nil? || header.empty? 50: begin 51: write(header) 52: rescue StandardError => err 53: ::Logging.log_internal(2) {err} 54: end 55: end 56: end 57: 58: ::Logging::Appenders[@name] = self 59: end
Write the given string to the logging destination “as is” — no layout formatting will be performed.
# File lib/logging/appender.rb, line 92 92: def <<( str ) 93: if @closed 94: raise RuntimeError, 95: "appender '<#{self.class.name}: #{@name}>' is closed" 96: end 97: 98: unless @level >= ::Logging::LEVELS.length 99: begin 100: write(str) 101: rescue StandardError => err 102: ::Logging.log_internal(2) {err} 103: end 104: end 105: self 106: end
Write the given event to the logging destination. The log event will be processed through the Layout associated with the Appender.
# File lib/logging/appender.rb, line 67 67: def append( event ) 68: if @closed 69: raise RuntimeError, 70: "appender '<#{self.class.name}: #{@name}>' is closed" 71: end 72: 73: # only append if the event level is less than or equal to the configured 74: # appender level 75: unless @level > event.level 76: begin 77: write(event) 78: rescue StandardError => err 79: ::Logging.log_internal(2) {err} 80: end 81: end 82: 83: self 84: end
Close the appender and writes the layout footer to the logging destination if the footer flag is set to true. Log events will no longer be written to the logging destination after the appender is closed.
# File lib/logging/appender.rb, line 171 171: def close( footer = true ) 172: return self if @closed 173: ::Logging::Appenders.remove(@name) 174: @closed = true 175: 176: flush 177: 178: if footer 179: footer = @layout.footer 180: unless footer.nil? || footer.empty? 181: begin 182: write(footer) 183: rescue StandardError => err 184: ::Logging.log_internal(2) {err} 185: end 186: end 187: end 188: self 189: end
Returns true if the appender has been closed; returns false otherwise. When an appender is closed, no more log events can be written to the logging destination.
# File lib/logging/appender.rb, line 198 198: def closed? 199: @closed 200: end
Call flush to force an appender to write out any buffered log events. Similar to IO#flush, so use in a similar fashion.
# File lib/logging/appender.rb, line 217 217: def flush 218: self 219: end
Returns a string representation of the appender.
# File lib/logging/appender.rb, line 226 226: def inspect 227: "<%s:0x%x name=\"%s\">" % [ 228: self.class.name.sub(/^Logging::/, ''), 229: self.object_id, 230: self.name 231: ] 232: end
call-seq
appender.layout = Logging::Layouts::Basic.new
Sets the layout to be used by this appender.
# File lib/logging/appender.rb, line 155 155: def layout=( layout ) 156: unless layout.kind_of? ::Logging::Layout 157: raise TypeError, 158: "#{layout.inspect} is not a kind of 'Logging::Layout'" 159: end 160: @layout = layout 161: end
Set the level for this appender; log events below this level will be ignored by this appender. The level can be either a String, a Symbol, or a Fixnum. An ArgumentError is raised if this is not the case.
There are two special levels — “all” and “off”. The former will enable recording of all log events. The latter will disable the recording of all events.
Example:
appender.level = :debug appender.level = "INFO" appender.level = 4 appender.level = 'off' appender.level = :all
These produce an ArgumentError
appender.level = Object appender.level = -1 appender.level = 1_000_000_000_000
# File lib/logging/appender.rb, line 134 134: def level=( level ) 135: lvl = case level 136: when String, Symbol; ::Logging::level_num(level) 137: when Fixnum; level 138: when nil; 0 139: else 140: raise ArgumentError, 141: "level must be a String, Symbol, or Integer" 142: end 143: if lvl.nil? or lvl < 0 or lvl > ::Logging::LEVELS.length 144: raise ArgumentError, "unknown level was given '#{level}'" 145: end 146: 147: @level = lvl 148: end
Reopen the connection to the underlying logging destination. If the connection is currently closed then it will be opened. If the connection is currently open then it will be closed and immediately opened.
# File lib/logging/appender.rb, line 206 206: def reopen 207: @closed = false 208: self 209: end
Obtains an exclusive lock, runs the block, and releases the lock when the block completes. This method is re-entrant so that a single thread can call sync multiple times without hanging the thread.
# File lib/logging/appender.rb, line 256 256: def sync( &block ) 257: @mutex.synchronize(&block) 258: end
Writes the given event to the logging destination. Subclasses should provide an implementation of this method. The event can be either a LogEvent or a String. If a LogEvent, then it will be formatted using the layout given to the appender when it was created.
# File lib/logging/appender.rb, line 245 245: def write( event ) 246: nil 247: end
Disabled; run with --debug to generate this.
Generated with the Darkfish Rdoc Generator 1.1.6.