1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
|
#
# Courier::Filter::Logger abstract base class
#
# (C) 2003-2008 Julian Mehnle <julian@mehnle.net>
# $Id: Logger.pm 210 2008-03-21 19:30:31Z julian $
#
###############################################################################
=head1 NAME
Courier::Filter::Logger - Abstract base class for loggers used by the
Courier::Filter framework
=cut
package Courier::Filter::Logger;
use warnings;
use strict;
use Error ':try';
use Courier::Error;
use constant TRUE => (0 == 0);
use constant FALSE => not TRUE;
=head1 SYNOPSIS
=head2 Courier::Filter logging
use Courier::Filter::Logger::My; # Need to use a non-abstract sub-class.
my $logger = Courier::Filter::Logger::My->new(%options);
# For use in an individual filter module:
my $module = Courier::Filter::Module::My->new(
...
logger => $logger,
...
);
# For use as a global Courier::Filter logger object:
my $filter = Courier::Filter->new(
...
logger => $logger,
...
);
=head2 Deriving new logger classes
package Courier::Filter::Logger::My;
use base qw(Courier::Filter::Logger);
=head1 DESCRIPTION
Sub-classes of B<Courier::Filter::Logger> are used by the B<Courier::Filter>
mail filtering framework and its filter modules for the logging of errors and
message rejections to arbitrary targets, like file handles or databases.
When overriding a method in a derived class, do not forget calling the
inherited method from your overridden method.
=cut
# Implementation:
###############################################################################
=head2 Constructor
The following constructor is provided and may be overridden:
=over
=item B<new(%options)>: returns I<Courier::Filter::Logger>
Creates a new logger using the %options given as a list of key/value pairs.
Initializes the logger, by creating/opening I/O handles, connecting to
databases, etc..
C<Courier::Filter::Logger::new()> creates a hash-ref as an object of the
invoked class, and stores the %options in it, but does nothing else.
=cut
sub new {
my ($class, %options) = @_;
$class ne __PACKAGE__
or throw Courier::Error('Unable to instantiate abstract ' . __PACKAGE__ . ' class');
my $self = { %options };
return bless($self, $class);
}
=back
=head2 Destructor
The following destructor is provided and may be overridden:
=over
=item B<destroy>
Uninitializes the logger, by closing I/O handles, disconnecting from databases,
etc..
C<Courier::Filter::Logger::destroy()> does nothing. Sub-classes may override
this method and define clean-up behavior.
=cut
sub destroy {
my ($self) = @_;
return;
}
=back
=head2 Instance methods
The following instance methods are provided and may be overridden:
=over
=item B<log_error($text)>
Logs the error message given as $text (a string which may contain newlines).
C<Courier::Filter::Logger::log_error()> does nothing and should be overridden.
=cut
sub log_error {
my ($self, $text) = @_;
return;
}
=item B<log_rejected_message($message, $reason)>
Logs the B<Courier::Message> given as $message as having been rejected due to
$reason (a string which may contain newlines).
C<Courier::Filter::Logger::log_rejected_message()> does nothing and should be
overridden.
=cut
sub log_rejected_message {
my ($self, $message, $reason) = @_;
return;
}
=back
=cut
BEGIN {
no warnings 'once';
*DESTROY = \&destroy;
}
=head1 SEE ALSO
L<Courier::Filter>, L<Courier::Filter::Module>.
For a list of prepared loggers that come with Courier::Filter, see
L<Courier::Filter::Overview/"Bundled Courier::Filter loggers">.
For AVAILABILITY, SUPPORT, and LICENSE information, see
L<Courier::Filter::Overview>.
=head1 AUTHOR
Julian Mehnle <julian@mehnle.net>
=cut
TRUE;
|
