1
Copyright & License#region Copyright & License
2
//
3// Copyright 2001-2005 The Apache Software Foundation
4//
5// Licensed under the Apache License, Version 2.0 (the "License");
6// you may not use this file except in compliance with the License.
7// You may obtain a copy of the License at
8//
9// http://www.apache.org/licenses/LICENSE-2.0
10//
11// Unless required by applicable law or agreed to in writing, software
12// distributed under the License is distributed on an "AS IS" BASIS,
13// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14// See the License for the specific language governing permissions and
15// limitations under the License.
16//
17
#endregion
18
19using System;
20using System.Collections;
21
22using log4net.Util;
23using log4net.Core;
24
25namespace log4net.Appender
26...{
27
/**//// <summary>
28 /// Abstract base class implementation of <see cref="IAppender"/> that
29 /// buffers events in a fixed size buffer.
30 /// </summary>
31 /// <remarks>
32 /// <para>
33 /// This base class should be used by appenders that need to buffer a
34 /// number of events before logging them. For example the <see cref="AdoNetAppender"/>
35 /// buffers events and then submits the entire contents of the buffer to
36 /// the underlying database in one go.
37 /// </para>
38 /// <para>
39 /// Subclasses should override the <see cref="SendBuffer(LoggingEvent[])"/>
40 /// method to deliver the buffered events.
41 /// </para>
42 /// <para>The BufferingAppenderSkeleton maintains a fixed size cyclic
43 /// buffer of events. The size of the buffer is set using
44 /// the <see cref="BufferSize"/> property.
45 /// </para>
46 /// <para>A <see cref="ITriggeringEventEvaluator"/> is used to inspect
47 /// each event as it arrives in the appender. If the <see cref="Evaluator"/>
48 /// triggers, then the current buffer is sent immediately
49 /// (see <see cref="SendBuffer(LoggingEvent[])"/>). Otherwise the event
50 /// is stored in the buffer. For example, an evaluator can be used to
51 /// deliver the events immediately when an ERROR event arrives.
52 /// </para>
53 /// <para>
54 /// The buffering appender can be configured in a <see cref="Lossy"/> mode.
55 /// By default the appender is NOT lossy. When the buffer is full all
56 /// the buffered events are sent with <see cref="SendBuffer(LoggingEvent[])"/>.
57 /// If the <see cref="Lossy"/> property is set to <c>true</c> then the
58 /// buffer will not be sent when it is full, and new events arriving
59 /// in the appender will overwrite the oldest event in the buffer.
60 /// In lossy mode the buffer will only be sent when the <see cref="Evaluator"/>
61 /// triggers. This can be useful behavior when you need to know about
62 /// ERROR events but not about events with a lower level, configure an
63 /// evaluator that will trigger when an ERROR event arrives, the whole
64 /// buffer will be sent which gives a history of events leading up to
65 /// the ERROR event.
66 /// </para>
67 /// </remarks>
68 /// <author>Nicko Cadell</author>
69
/// <author>Gert Driesen</author>
70 public abstract class BufferingAppenderSkeleton : AppenderSkeleton
71 ...{
72 Protected Instance Constructors#region Protected Instance Constructors
73
74 /**//// <summary>
75 /// Initializes a new instance of the <see cref="BufferingAppenderSkeleton" /> class.
76 /// </summary>
77 /// <remarks>
78 /// <para>
79 /// Protected default constructor to allow subclassing.
80 /// </para>
81 /// </remarks>
82 protected BufferingAppenderSkeleton() : this(true)
83 ...{
84 }
85
86 /**//// <summary>
87 /// Initializes a new instance of the <see cref="BufferingAppenderSkeleton" /> class.
88 /// </summary>
89 /// <param name="eventMustBeFixed">the events passed through this appender must be
90 /// fixed by the time that they arrive in the derived class' <c>SendBuffer</c> method.</param>
91 /// <remarks>
92 /// <para>
93 /// Protected constructor to allow subclassing.
94 /// </para>
95 /// <para>
96 /// The <paramref name="eventMustBeFixed"/> should be set if the subclass
97 /// expects the events delivered to be fixed even if the
98 /// <see cref="BufferSize"/> is set to zero, i.e. when no buffering occurs.
99 /// </para>
100 /// </remarks>
101 protected BufferingAppenderSkeleton(bool eventMustBeFixed) : base()
102 ...{
103 m_eventMustBeFixed = eventMustBeFixed;
104 }
105
106 #endregion Protected Instance Constructors
107
108 Public Instance Properties#region Public Instance Properties
109
110 /**//// <summary>
111 /// Gets or sets a value that indicates whether the appender is lossy.
112 /// </summary>
113 /// <value>
114 /// <c>true</c> if the appender is lossy, otherwise <c>false</c>. The default is <c>false</c>.
115 /// </value>
116 /// <remarks>
117 /// <para>
118 /// This appender uses a buffer to store logging events before
119 /// delivering them. A triggering event causes the whole buffer
120 /// to be send to the remote sink. If the buffer overruns before
121 /// a triggering event then logging events could be lost. Set
122 /// <see cref="Lossy"/> to <c>false</c> to prevent logging events
123 /// from being lost.
124 /// </para>
125 /// <para>If <see cref="Lossy"/> is set to <c>true</c> then an
126 /// <see cref="Evaluator"/> must be specified.</para>
127 /// </remarks>
128 public bool Lossy
129 ...{
130 get ...{ return m_lossy; }
131 set ...{ m_lossy = value; }
132 }
133
134 /**//// <summary>
135 /// Gets or sets the size of the cyclic buffer used to hold the
136 /// logging events.
137 /// </summary>
138 /// <value>
139 /// The size of the cyclic buffer used to hold the logging events.
140 /// </value>
141 /// <remarks>
142 /// <para>
143 /// The <see cref="BufferSize"/> option takes a positive integer
144 /// representing the maximum number of logging events to collect in
145 /// a cyclic buffer. When the <see cref="BufferSize"/> is reached,
146 /// oldest events are deleted as new events are added to the
147 /// buffer. By default the size of the cyclic buffer is 512 events.
148 /// </para>
149 /// <para>
150 /// If the <see cref="BufferSize"/> is set to a value less than
151 /// or equal to 1 then no buffering will occur. The logging event
152 /// will be delivered synchronously (depending on the <see cref="Lossy"/>
153 /// and <see cref="Evaluator"/> properties). Otherwise the event will
154 /// be buffered.
155 /// </para>
156 /// </remarks>
157 public int BufferSize
158 ...{
159 get ...{ return m_bufferSize; }
160 set ...{ m_bufferSize = value; }
161 }
162
163 /**//// <summary>
164 /// Gets or sets the <see cref="ITriggeringEventEvaluator"/> that causes the
165 /// buffer to be sent immediately.
166 /// </summary>
167 /// <value>
168 /// The <see cref="ITriggeringEventEvaluator"/> that causes the buffer to be
169 /// sent immediately.
170 /// </value>
171 /// <remarks>
172 /// <para>
173 /// The evaluator will be called for each event that is appended to this
174 /// appender. If the evaluator triggers then the current buffer will
175 /// immediately be sent (see <see cref="SendBuffer(LoggingEvent[])"/>).
176 /// </para>
177 /// <para>If <see cref="Lossy"/> is set to <c>true</c> then an
178 /// <see cref="Evaluator"/> must be specified.</para>
179 /// </remarks>
180 public ITriggeringEventEvaluator Evaluator
181 ...{
182 get ...{ return m_evaluator; }
183 set ...{ m_evaluator = value; }
184 }
185
186 /**//// <summary>
187 /// Gets or sets the value of the <see cref="ITriggeringEventEvaluator"/> to use.
188 /// </summary>
189 /// <value>
190 /// The value of the <see cref="ITriggeringEventEvaluator"/> to use.
191 /// </value>
192 /// <remarks>
193 /// <para>
194 /// The evaluator will be called for each event that is discarded from this
195 /// appender. If the evaluator triggers then the current buffer will immediately
196 /// be sent (see <see cref="SendBuffer(LoggingEvent[])"/>).
197 /// </para>
198 /// </remarks>
199 public ITriggeringEventEvaluator LossyEvaluator
200 ...{
201 get ...{ return m_lossyEvaluator; }
202 set ...{ m_lossyEvaluator = value; }
203 }
204
205 /**//// <summary>
206 /// Gets or sets a value indicating if only part of the logging event data
207 /// should be fixed.
208 /// </summary>
209 /// <value>
210 /// <c>true</c> if the appender should only fix part of the logging event
211 /// data, otherwise <c>false</c>. The default is <c>false</c>.
212 /// </value>
213 /// <remarks>
214 /// <para>
215 /// Setting this property to <c>true</c> will cause only part of the
216 /// event data to be fixed and serialized. This will improve performance.
217 /// </para>
218 /// <para>
219 /// See <see cref="LoggingEvent.FixVolatileData(FixFlags)"/> for more information.
220 /// </para>
221 /// </remarks>
222 [Obsolete("Use Fix property")]
223 virtual public bool OnlyFixPartialEventData
224 ...{
225 get ...{ return (Fix == FixFlags.Partial); }
226 set
227 ...{
228 if (value)
229 ...{
230 Fix = FixFlags.Partial;
231 }
232 else
233 ...{
234 Fix = FixFlags.All;
235 }
236 }
237 }
238
239 /**//// <summary>
240 /// Gets or sets a the fields that will be fixed in the event
241 /// </summary>
242 /// <value>
243 /// The event fields that will be fixed before the event is buffered
244 /// </value>
245 /// <remarks>
246 /// <para>
247 /// The logging event needs to have certain thread specific values
248 /// captured before it can be buffered. See <see cref="LoggingEvent.Fix"/>
249 /// for details.
250 /// </para>
251 /// </remarks>
252 /// <seealso cref="LoggingEvent.Fix"/>
253 virtual public FixFlags Fix
254 ...{
255 get ...{ return m_fixFlags; }
256 set ...{ m_fixFlags = value; }
257 }
258
259 #endregion Public Instance Properties
260
261 Public Methods#region Public Methods
262
263 /**//// <summary>
264 /// Flush the currently buffered events
265 /// </summary>
266 /// <remarks>
267 /// <para>
268 /// Flushes any events that have been buffered.
269 /// </para>
270 /// <para>
271 /// If the appender is buffering in <see cref="Lossy"/> mode then the contents
272 /// of the buffer will NOT be flushed to the appender.
273 /// </para>
274 /// </remarks>
275 public virtual void Flush()
276 ...{
277 Flush(false);
278 }
279
280 /**//// <summary>
281 /// Flush the currently buffered events
282 /// </summary>
283 /// <param name="flushLossyBuffer">set to <c>true</c> to flush the buffer of lossy events</param>
284 /// <remarks>
285 /// <para>
286 /// Flushes events that have been buffered. If <paramref name="flushLossyBuffer" /> is
287 /// <c>false</c> then events will only be flushed if this buffer is non-lossy mode.
288 /// </para>
289 /// <para>
290 /// If the appender is buffering in <see cref="Lossy"/> mode then the contents
291 /// of the buffer will only be flushed if <paramref name="flushLossyBuffer" /> is <c>true</c>.
292 /// In this case the contents of the buffer will be tested against the
293 /// <see cref="LossyEvaluator"/> and if triggering will be output. All other buffered
294 /// events will be discarded.
295 /// </para>
296 /// <para>
297 /// If <paramref name="flushLossyBuffer" /> is <c>true</c> then the buffer will always
298 /// be emptied by calling this method.
299 /// </para>
300 /// </remarks>
301 public virtual void Flush(bool flushLossyBuffer)
302 ...{
303 // This method will be called outside of the AppenderSkeleton DoAppend() method
304 // therefore it needs to be protected by its own lock. This will block any
305 // Appends while the buffer is flushed.
306 lock(this)
307 ...{
308 if (m_cb != null && m_cb.Length > 0)
309 ...{
310 if (m_lossy)
311 ...{
312 // If we are allowed to eagerly flush from the lossy buffer
313 if (flushLossyBuffer)
314 ...{
315 if (m_lossyEvaluator != null)
316 ...{
317 // Test the contents of the buffer against the lossy evaluator
318 LoggingEvent[] bufferedEvents = m_cb.PopAll();
319 ArrayList filteredEvents = new ArrayList(bufferedEvents.Length);
320
321 foreach(LoggingEvent loggingEvent in bufferedEvents)
322 ...{
323 if (m_lossyEvaluator.IsTriggeringEvent(loggingEvent))
324 ...{
325 filteredEvents.Add(loggingEvent);
326 }
327 }
328
329 // Send the events that meet the lossy evaluator criteria
330 if (filteredEvents.Count > 0)
331 ...{
332 SendBuffer((LoggingEvent[])filteredEvents.ToArray(typeof(LoggingEvent)));
333 }
334 }
335 else
336 ...{
337 // No lossy evaluator, all buffered events are discarded
338 m_cb.Clear();
339 }
340 }
341 }
342 else
343 ...{
344 // Not lossy, send whole buffer
345 SendFromBuffer(null, m_cb);
346 }
347 }
348 }
349 }
350
351 #endregion Public Methods
352
353 Implementation of IOptionHandler#region Implementation of IOptionHandler
354
355 /**//// <summary>
356 /// Initialize the appender based on the options set
357 /// </summary>
358 /// <remarks>
359 /// <para>
360 /// This is part of the <see cref="IOptionHandler"/> delayed object
361 /// activation scheme. The <see cref="ActivateOptions"/> method must
362 /// be called on this object after the configuration properties have
363 /// been set. Until <see cref="ActivateOptions"/> is called this
364 /// object is in an undefined state and must not be used.
365 /// </para>
366 /// <para>
367 /// If any of the configuration properties are modified then
368 /// <see cref="ActivateOptions"/> must be called again.
369 /// </para>
370 /// </remarks>
371 override public void ActivateOptions()
372 ...{
373 base.ActivateOptions();
374
375 // If the appender is in Lossy mode then we will
376 // only send the buffer when the Evaluator triggers
377 // therefore check we have an evaluator.
378 if (m_lossy && m_evaluator == null)
379 ...{
380 ErrorHandler.Error("Appender ["+Name+"] is Lossy but has no Evaluator. The buffer will never be sent!");
381 }
382
383 if (m_bufferSize > 1)
384 ...{
385 m_cb = new CyclicBuffer(m_bufferSize);
386 }
387 else
388 ...{
389 m_cb = null;
390 }
391 }
392
393 #endregion Implementation of IOptionHandler
394
395 Override implementation of AppenderSkeleton#region Override implementation of AppenderSkeleton
396
397 /**//// <summary>
398 /// Close this appender instance.
399 /// </summary>
400 /// <remarks>
401 /// <para>
402 /// Close this appender instance. If this appender is marked
403 /// as not <see cref="Lossy"/> then the remaining events in
404 /// the buffer must be sent when the appender is closed.
405 /// </para>
406 /// </remarks>
407 override protected void OnClose()
408 ...{
409 // Flush the buffer on close
410 Flush(true);
411 }
412
413 /**//// <summary>
414 /// This method is called by the <see cref="AppenderSkeleton.DoAppend(LoggingEvent)"/> method.
415 /// </summary>
416 /// <param name="loggingEvent">the event to log</param>
417 /// <remarks>
418 /// <para>
419 /// Stores the <paramref name="loggingEvent"/> in the cyclic buffer.
420 /// </para>
421 /// <para>
422 /// The buffer will be sent (i.e. passed to the <see cref="SendBuffer"/>
423 /// method) if one of the following conditions is met:
424 /// </para>
425 /// <list type="bullet">
426 /// <item>
427 /// <description>The cyclic buffer is full and this appender is
428 /// marked as not lossy (see <see cref="Lossy"/>)</description>
429 /// </item>
430 /// <item>
431 /// <description>An <see cref="Evaluator"/> is set and
432 /// it is triggered for the <paramref name="loggingEvent"/>
433 /// specified.</description>
434 /// </item>
435 /// </list>
436 /// <para>
437 /// Before the event is stored in the buffer it is fixed
438 /// (see <see cref="LoggingEvent.FixVolatileData(FixFlags)"/>) to ensure that
439 /// any data referenced by the event will be valid when the buffer
440 /// is processed.
441 /// </para>
442 /// </remarks>
443 override protected void Append(LoggingEvent loggingEvent)
444 ...{
445 // If the buffer size is set to 1 or less then the buffer will be
446 // sent immediately because there is not enough space in the buffer
447 // to buffer up more than 1 event. Therefore as a special case
448 // we don't use the buffer at all.
449 if (m_cb == null || m_bufferSize <= 1)
450 ...{
451 // Only send the event if we are in non lossy mode or the event is a triggering event
452 if ((!m_lossy) ||
453 (m_evaluator != null && m_evaluator.IsTriggeringEvent(loggingEvent)) ||
454 (m_lossyEvaluator != null && m_lossyEvaluator.IsTriggeringEvent(loggingEvent)))
455 ...{
456 if (m_eventMustBeFixed)
457 ...{
458 // Derive class expects fixed events
459 loggingEvent.Fix = this.Fix;
460 }
461
462 // Not buffering events, send immediately
463 SendBuffer(new LoggingEvent[] ...{ loggingEvent } );
464 }
465 }
466 else
467 ...{
468 // Because we are caching the LoggingEvent beyond the
469 // lifetime of the Append() method we must fix any
470 // volatile data in the event.
471 loggingEvent.Fix = this.Fix;
472
473 // Add to the buffer, returns the event discarded from the buffer if there is no space remaining after the append
474 LoggingEvent discardedLoggingEvent = m_cb.Append(loggingEvent);
475
476 if (discardedLoggingEvent != null)
477 ...{
478 // Buffer is full and has had to discard an event
479 if (!m_lossy)
480 ...{
481 // Not lossy, must send all events
482 SendFromBuffer(discardedLoggingEvent, m_cb);
483 }
484 else
485 ...{
486 // Check if the discarded event should not be logged
487 if (m_lossyEvaluator == null || !m_lossyEvaluator.IsTriggeringEvent(discardedLoggingEvent))
488 ...{
489 // Clear the discarded event as we should not forward it
490 discardedLoggingEvent = null;
491 }
492
493 // Check if the event should trigger the whole buffer to be sent
494 if (m_evaluator != null && m_evaluator.IsTriggeringEvent(loggingEvent))
495 ...{
496 SendFromBuffer(discardedLoggingEvent, m_cb);
497 }
498 else if (discardedLoggingEvent != null)
499 ...{
500 // Just send the discarded event
501 SendBuffer(new LoggingEvent[] ...{ discardedLoggingEvent } );
502 }
503 }
504 }
505 else
506 ...{
507 // Buffer is not yet full
508
509 // Check if the event should trigger the whole buffer to be sent
510 if (m_evaluator != null && m_evaluator.IsTriggeringEvent(loggingEvent))
511 ...{
512 SendFromBuffer(null, m_cb);
513 }
514 }
515 }
516 }
517
518 #endregion Override implementation of AppenderSkeleton
519
520 Protected Instance Methods#region Protected Instance Methods
521
522 /**//// <summary>
523 /// Sends the contents of the buffer.
524 /// </summary>
525 /// <param name="firstLoggingEvent">The first logging event.</param>
526 /// <param name="buffer">The buffer containing the events that need to be send.</param>
527 /// <remarks>
528 /// <para>
529 /// The subclass must override <see cref="SendBuffer(LoggingEvent[])"/>.
530 /// </para>
531 /// </remarks>
532 virtual protected void SendFromBuffer(LoggingEvent firstLoggingEvent, CyclicBuffer buffer)
533 ...{
534 LoggingEvent[] bufferEvents = buffer.PopAll();
535
536 if (firstLoggingEvent == null)
537 ...{
538 SendBuffer(bufferEvents);
539 }
540 else if (bufferEvents.Length == 0)
541 ...{
542 SendBuffer(new LoggingEvent[] ...{ firstLoggingEvent } );
543 }
544 else
545 ...{
546 // Create new array with the firstLoggingEvent at the head
547 LoggingEvent[] events = new LoggingEvent[bufferEvents.Length + 1];
548 Array.Copy(bufferEvents, 0, events, 1, bufferEvents.Length);
549 events[0] = firstLoggingEvent;
550
551 SendBuffer(events);
552 }
553 }
554
555 #endregion Protected Instance Methods
556
557 /**//// <summary>
558 /// Sends the events.
559 /// </summary>
560 /// <param name="events">The events that need to be send.</param>
561 /// <remarks>
562 /// <para>
563 /// The subclass must override this method to process the buffered events.
564 /// </para>
565 /// </remarks>
566 abstract protected void SendBuffer(LoggingEvent[] events);
567
568 Private Static Fields#region Private Static Fields
569
570 /**//// <summary>
571 /// The default buffer size.
572 /// </summary>
573 /// <remarks>
574 /// The default size of the cyclic buffer used to store events.
575 /// This is set to 512 by default.
576 /// </remarks>
577 private const int DEFAULT_BUFFER_SIZE = 512;
578
579 #endregion Private Static Fields
580
581 Private Instance Fields#region Private Instance Fields
582
583 /**//// <summary>
584 /// The size of the cyclic buffer used to hold the logging events.
585 /// </summary>
586 /// <remarks>
587 /// Set to <see cref="DEFAULT_BUFFER_SIZE"/> by default.
588 /// </remarks>
589 private int m_bufferSize = DEFAULT_BUFFER_SIZE;
590
591 /**//// <summary>
592 /// The cyclic buffer used to store the logging events.
593 /// </summary>
594 private CyclicBuffer m_cb;
595
596 /**//// <summary>
597 /// The triggering event evaluator that causes the buffer to be sent immediately.
598 /// </summary>
599 /// <remarks>
600 /// The object that is used to determine if an event causes the entire
601 /// buffer to be sent immediately. This field can be <c>null</c>, which
602 /// indicates that event triggering is not to be done. The evaluator
603 /// can be set using the <see cref="Evaluator"/> property. If this appender
604 /// has the <see cref="m_lossy"/> (<see cref="Lossy"/> property) set to
605 /// <c>true</c> then an <see cref="Evaluator"/> must be set.
606 /// </remarks>
607 private ITriggeringEventEvaluator m_evaluator;
608
609 /**//// <summary>
610 /// Indicates if the appender should overwrite events in the cyclic buffer
611 /// when it becomes full, or if the buffer should be flushed when the
612 /// buffer is full.
613 /// </summary>
614 /// <remarks>
615 /// If this field is set to <c>true</c> then an <see cref="Evaluator"/> must
616 /// be set.
617 /// </remarks>
618 private bool m_lossy = false;
619
620 /**//// <summary>
621 /// The triggering event evaluator filters discarded events.
622 /// </summary>
623 /// <remarks>
624 /// The object that is used to determine if an event that is discarded should
625 /// really be discarded or if it should be sent to the appenders.
626 /// This field can be <c>null</c>, which indicates that all discarded events will
627 /// be discarded.
628 /// </remarks>
629 private ITriggeringEventEvaluator m_lossyEvaluator;
630
631 /**//// <summary>
632 /// Value indicating which fields in the event should be fixed
633 /// </summary>
634 /// <remarks>
635 /// By default all fields are fixed
636 /// </remarks>
637 private FixFlags m_fixFlags = FixFlags.All;
638
639 /**//// <summary>
640 /// The events delivered to the subclass must be fixed.
641 /// </summary>
642 private readonly bool m_eventMustBeFixed;
643
644 #endregion Private Instance Fields
645 }
646}
647
51Job/log4net/Appender/BufferingAppenderSkeleton.cs[21K，2009-6-12 11:31:08]，打开代码结构图
打包下载该项目完整源码：无忧之源招聘系统及Log4Net源码