#
# Courier::Filter::Logger::File class
#
# (C) 2003-2008 Julian Mehnle <julian@mehnle.net>
# $Id: File.pm 210 2008-03-21 19:30:31Z julian $
#
###############################################################################
=head1 NAME
Courier::Filter::Logger::File - File logger for the Courier::Filter framework
=cut
package Courier::Filter::Logger::File;
=head1 SYNOPSIS
use Courier::Filter::Logger::File;
my $logger = Courier::Filter::Logger::File->new(
file_name => $file_name
);
# 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,
...
);
=cut
use warnings;
use strict;
use base 'Courier::Filter::Logger::IOHandle';
use Error ':try';
use Courier::Error;
use IO::File;
use constant TRUE => (0 == 0);
use constant FALSE => not TRUE;
=head1 DESCRIPTION
This class is a file logger class for use with Courier::Filter and its filter
modules. It is derived from B<Courier::Filter::Logger::IOHandle>.
=cut
# Implementation:
###############################################################################
=head2 Constructor
The following constructor is provided:
=over
=item B<new(%options)>: returns I<Courier::Filter::Logger::File>; throws
I<Courier::Error>
Creates a new logger that logs messages as lines to a file. Opens the file for
writing, creating it if necessary.
%options is a list of key/value pairs representing any of the following
options:
=over
=item B<file_name>
I<Required>. The name of the file to which log messages should be written.
=item B<timestamp>
A boolean value controlling whether every log message line should be prefixed
with a timestamp (in local time, in ISO format). Defaults to B<false>.
=back
=cut
sub new {
my ($class, %options) = @_;
my $handle = IO::File->new($options{file_name}, '>>')
or throw Courier::Error("Unable to open log file '$options{file_name}' for writing");
return $class->SUPER::new(
%options,
handle => $handle
);
}
=back
=head2 Instance methods
The following instance methods are provided, as inherited from
B<Courier::Filter::Logger::IOHandle>:
=over
=item B<log_error($text)>: throws Perl exceptions
Logs the error message given as C<$text> (a string which may contain newlines).
Prefixes each line with a timestamp if the C<timestamp> option has been set
through the constructor.
=item B<log_rejected_message($message, $reason)>: throws Perl exceptions
Logs the B<Courier::Message> given as C<$message> as having been rejected due
to C<$reason> (a string which may contain newlines).
=back
=head1 SEE ALSO
L<Courier::Filter::Logger::IOHandle>, L<Courier::Filter::Logger>,
L<Courier::Filter::Overview>.
For AVAILABILITY, SUPPORT, and LICENSE information, see
L<Courier::Filter::Overview>.
=head1 AUTHOR
Julian Mehnle <julian@mehnle.net>
=cut
TRUE;