.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "DlfConverter 3pm"
.TH DlfConverter 3pm "2020-07-07" "Lire 2.1.1" "LogReport's Lire Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Lire::DlfConverter \- Base interface of all DLF converters.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use base qw/ Lire::DlfConverter /;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This package defines the interface that must be implemented by all
\&\s-1DLF\s0 Converters. All the methods defined in this package will throw a
\&'method not implemented' exception if they are called.
.SH "META INFORMATION METHODS"
.IX Header "META INFORMATION METHODS"
These methods provides information to the Lire framework about the \s-1DLF\s0
converter.
.SS "\fBname()\fP"
.IX Subsection "name()"
Returns the name of the \s-1DLF\s0 converter, i.e. the service's (aka log
format) name.
.PP
E.g. \f(CW\*(C`combined\*(C'\fR
.SS "\fBtitle()\fP"
.IX Subsection "title()"
Returns a more human friendly name for the \s-1DLF\s0 Converter.
.PP
E.g. \f(CW\*(C`Combined Log Format DLF Converter\*(C'\fR
.SS "\fBdescription()\fP"
.IX Subsection "description()"
Returns a DocBook \s-1XML\s0 based documentation of the \s-1DLF\s0 Converter.
.PP
E.g. <para>This \s-1DLF\s0 converter can be used to process log file in the
Combined Log Format to the www \s-1DLF\s0 schema.</para>
.SS "\fBschemas()\fP"
.IX Subsection "schemas()"
Returns a list of \s-1DLF\s0 schemas for which \s-1DLF\s0 records can be written
from the data contained in the log file.
.PP
E.g. For the combined \s-1DLF\s0 converters, that would be 'www'.
.PP
For the 'nms' converter that could be \f(CW\*(C`qw/daemon email/\*(C'\fR which means
that the \s-1DLF\s0 converter writes \s-1DLF\s0 records in the hypothetical \f(CW\*(C`daemon\*(C'\fR
schema (server start, stops, restarts, etc.) and the email schema.
.PP
This should only contains 'base' (aka superservice) schemas. No
extended or derived schema's name should appear in that list. (Those
are reserved for the analyzers).
.SS "\fBhandle_log_lines()\fP"
.IX Subsection "handle_log_lines()"
This method should returns true if the DlfConverter processes
line-oriented log file. This is the default. If this method returns
false, only the \fBprocess_log_file()\fR method will be called, otherwise
the \fBprocess_log_line()\fR method is used for every input lines.
.SH "Implementation methods"
.IX Header "Implementation methods"
These are the methods where the \s-1DLF\s0 converter work is done. The
\&\fBinit_dlf_converter()\fR method will be called once before any processing
occurs. Afterwards, \fBprocess_log_line()\fR will be called once for every line
that was marked for log continuation and for every line contained in
the log file. The \fBfinish_conversion()\fR method will be called once all
lines are processed. Any exceptions (uncaught die) that occur during
any of the methods will abort the conversion process.
.ie n .SS "init_dlf_converter( $process, [$config] )"
.el .SS "init_dlf_converter( \f(CW$process\fP, [$config] )"
.IX Subsection "init_dlf_converter( $process, [$config] )"
This method will be called by the framework before processing the log
file. This method should be used by the converter to initialize its
state.
.PP
The \f(CW$process\fR parameter contains the Lire::DlfConverterProcess object
which is controlling the conversion process.
.PP
The \f(CW$config\fR parameter contains configuration data that was specified
in the ImportJob for that converter. To register configuration
specification for you DlfConverter, you just need to define a
configuraiton specification under the name
\&\fIconverter_name\fR_properties. This should be either a RecordSpec or
ObjectSpec.
.ie n .SS "process_log_file( $process, $fd )"
.el .SS "process_log_file( \f(CW$process\fP, \f(CW$fd\fP )"
.IX Subsection "process_log_file( $process, $fd )"
This method is called so that the converter can convert the data
contained in the \f(CW$fd\fR file handle to \s-1DLF.\s0 This method is only used when
the \fBhandle_log_lines()\fR method returned false.
.PP
\&\f(CW$process\fR contains a reference to the Lire::DlfConverterProcess object
which controls the conversion process and defines the \s-1API\s0 to write \s-1DLF\s0
and report errors.
.ie n .SS "process_log_line( $process, $line )"
.el .SS "process_log_line( \f(CW$process\fP, \f(CW$line\fP )"
.IX Subsection "process_log_line( $process, $line )"
This method is called by the framework once for each log line present
in the log file. This method is only called if the \fBhandles_log_lines()\fR
method returnes true.
.PP
\&\f(CW$process\fR is a reference to the Lire::DlfConverterProcess object. This
object defines a method to report errors, save lines for continuation
purposes and writes \s-1DLF\s0 records.
.PP
\&\f(CW$line\fR contains the log line which should be processed with the end of
line removed.
.ie n .SS "finish_conversion( $dlf_store )"
.el .SS "finish_conversion( \f(CW$dlf_store\fP )"
.IX Subsection "finish_conversion( $dlf_store )"
This method is called once by the framework once all log lines were
processed. It can be use by the converter to write any \s-1DLF\s0 records
that could be remaining because of a stateful analysis.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBLire::DlfConverterProcess\fR\|(3pm), \fBLire::DlfStore\fR\|(3pm), \fBLire::ImportJob\fR\|(3pm),
\&\fBLire::PluginManager\fR\|(3pm)
.SH "AUTHOR"
.IX Header "AUTHOR"
.Vb 1
\&  Francis J. Lacoste <flacoste@logreport.org>
.Ve
.SH "VERSION"
.IX Header "VERSION"
\&\f(CW$Id:\fR DlfConverter.pm,v 1.12 2006/07/23 13:16:28 vanbaal Exp $
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2002, 2003, 2004 Stichting LogReport Foundation LogReport@LogReport.org
.PP
This file is part of Lire.
.PP
Lire is free software; you can redistribute it and/or modify
it under the terms of the \s-1GNU\s0 General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
.PP
This program is distributed in the hope that it will be useful,
but \s-1WITHOUT ANY WARRANTY\s0; without even the implied warranty of
\&\s-1MERCHANTABILITY\s0 or \s-1FITNESS FOR A PARTICULAR PURPOSE.\s0  See the
\&\s-1GNU\s0 General Public License for more details.
.PP
You should have received a copy of the \s-1GNU\s0 General Public License
along with this program (see \s-1COPYING\s0); if not, check with
http://www.gnu.org/copyleft/gpl.html.