Parent

Logging::Appender

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.

Attributes

name[R]
layout[R]
level[R]

Public Class Methods

new( name, :layout => layout ) click to toggle source

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

Public Instance Methods

appender << string click to toggle source

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
append( event ) click to toggle source

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( footer = true ) click to toggle source

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
closed? click to toggle source

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
flush click to toggle source

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
inspect => string click to toggle source

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
layout=( layout ) click to toggle source

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
level = :all click to toggle source

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() click to toggle source

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

Private Instance Methods

sync { block } click to toggle source

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
write( event ) click to toggle source

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.

[Validate]

Generated with the Darkfish Rdoc Generator 1.1.6.