.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.14)
.\"
.\" 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" ''
'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 turned on, 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.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" 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 "DlfStore 3pm"
.TH DlfStore 3pm "2011-12-31" "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::DlfStore \- Interface to a DLF store
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Lire::DlfStore;
\&
\&  my $store = Lire::DlfStore\->open( "mystore", 1 );
\&  my $avail_streams = $store\->dlf_streams;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
.ie n .SS "open( $store_path, [ $create ] );"
.el .SS "open( \f(CW$store_path\fP, [ \f(CW$create\fP ] );"
.IX Subsection "open( $store_path, [ $create ] );"
Opens a Lire::DlfStore residing in the directory pointed by
\&\f(CW$store_path\fR and returns a Lire::DlfStore instance that can be used to
access its content.
.PP
If the store \f(CW$store_path\fR wasn't created, the method will die unless
the \f(CW$create\fR parameter was set to true.
.PP
If the store is locked by another process, the method will also die.
.PP
Trying to open the same store twice from the same process will fail.
.SS "\fIclose()\fP"
.IX Subsection "close()"
Calls this method to release the lock held by the current process on
the store. If you don't call it, it will be called automatically when
the store reference goes out of scope, but you better not rely on this
to close your stores.
.SS "\fIis_closed()\fP"
.IX Subsection "is_closed()"
Returns true if this DlfStore was closed and cannot be used anymore.
.SS "path"
.IX Subsection "path"
Returns the path to the store. This is the argument used to create the
store.
.SS "config"
.IX Subsection "config"
Returns the configuration of the store instantiated as a
Lire::Config::ConfigFile.
.SS "\fIimport_jobs()\fP"
.IX Subsection "import_jobs()"
Returns as an array ref the list of ImportJob currently configured
in the DlfStore
.SS "\fIreport_jobs()\fP"
.IX Subsection "report_jobs()"
Returns as an array ref the list of ReportJob currently configured
in the DlfStore
.ie n .SS "has_report_config( $name )"
.el .SS "has_report_config( \f(CW$name\fP )"
.IX Subsection "has_report_config( $name )"
Returns true if there is a report configuration named \f(CW$name\fR in
this DlfStore.
.SS "\fIreport_configurations()\fP"
.IX Subsection "report_configurations()"
Returns as an array ref the list of ReporConfig currently configured
in the DlfStore
.ie n .SS "get_report_config( $name )"
.el .SS "get_report_config( \f(CW$name\fP )"
.IX Subsection "get_report_config( $name )"
Returns the Lire::ReportConfig object named \f(CW$name\fR. Throws an exception
if it doesn' exists.
.SH "DLF STREAMS RELATED METHOD"
.IX Header "DLF STREAMS RELATED METHOD"
A DlfStore can contains multiple Dlf Stream. Dlf Stream is data
conforming to a \s-1DLF\s0 schema. The streams are represented by
Lire::DlfStream objects.
.SS "\fIdlf_streams()\fP"
.IX Subsection "dlf_streams()"
List the \s-1DLF\s0 stream available in the \s-1DLF\s0 store. This returns a list of
DlfSchema's name.
.ie n .SS "has_dlf_stream( $name )"
.el .SS "has_dlf_stream( \f(CW$name\fP )"
.IX Subsection "has_dlf_stream( $name )"
Returns true if the DlfStore contains a DlfStream conforming to the
schema \f(CW$name\fR.
.ie n .SS "get_stream_config( $name )"
.el .SS "get_stream_config( \f(CW$name\fP )"
.IX Subsection "get_stream_config( $name )"
Returns the Lire::Config::Dictionary instance which contains the
stream configuration for the \f(CW$name\fR DlfStream. This method will create
an instance from the default if necessary. If \f(CW$name\fR isn't a valid
schema name, this method will throw an error.
.SS "\fIconfigured_dlf_streams()\fP"
.IX Subsection "configured_dlf_streams()"
Returns the list of DlfStreams which are referenced by the store
configuration. This is the result of \fIdlf_streams()\fR plus all schemas
that exists and are used by one of the confiured ImportJob or
DlfStreamSpec.
.ie n .SS "open_dlf_stream( $name, [$mode], [$sort_spec] )"
.el .SS "open_dlf_stream( \f(CW$name\fP, [$mode], [$sort_spec] )"
.IX Subsection "open_dlf_stream( $name, [$mode], [$sort_spec] )"
Returns a Lire::DlfStream object that can be used to a \s-1DLF\s0 stream in
the schema \f(CW$name\fR. The \f(CW$mode\fR parameter can either \*(L"r\*(R" or \*(L"w\*(R" and
defaults to \*(L"r\*(R".
.PP
If the mode is \*(L"w\*(R", the Lire::DlfStream is opened for writing (new Dlf
records can be inserted). If the DlfStore didn't contains a stream
\&\f(CW$name\fR, an empty one will be created.
.PP
If the mode is \*(L"r\*(R", the Lire::DlfStream is opened for reading (no \s-1DLF\s0
records may be inserted). An exception will be thrown if there is no
stream \f(CW$name\fR available.
.PP
When the stream is opened in \*(L"r\*(R" mode, a sort order can be specified
by passing a \f(CW$sort_spec\fR. A \f(CW$sort_spec\fR is a white-space delimited list
of field names which should specify the sort order. Reverse sort order
can be specified by prefixing the field's name by '\-'.
.ie n .SS "run_analysers( $stream, [ $dlf_source ] )"
.el .SS "run_analysers( \f(CW$stream\fP, [ \f(CW$dlf_source\fP ] )"
.IX Subsection "run_analysers( $stream, [ $dlf_source ] )"
Runs all the configured analysers on the \s-1DLF\s0 stream \f(CW$stream\fR.
\&\f(CW$dlf_source\fR limit the records which should be analysed.
.SS "\fIclean_streams()\fP"
.IX Subsection "clean_streams()"
Remove records that are days older than what is configured in the
\&'keep_days' parameter.
.SH "REPORTS RELATED METHOD"
.IX Header "REPORTS RELATED METHOD"
A DlfStore also contains the periodically generated reports. These
reports are usually configured through the \fIlire\fR\|(1) command. The
generated reports are stored in Lire \s-1XML\s0 native format by period.
.ie n .SS "put_report( $job, $schedule, $report )"
.el .SS "put_report( \f(CW$job\fP, \f(CW$schedule\fP, \f(CW$report\fP )"
.IX Subsection "put_report( $job, $schedule, $report )"
Saves the \f(CW$report\fR Lire::Report which was generated by \f(CW$job\fR and
\&\f(CW$schedule\fR. Returns the filename where the report was saved.
.ie n .SS "find_report_source( $job, $schedule, [$time] )"
.el .SS "find_report_source( \f(CW$job\fP, \f(CW$schedule\fP, [$time] )"
.IX Subsection "find_report_source( $job, $schedule, [$time] )"
This method will returns an hash reference containing parameters on
how the ReportJob \f(CW$job\fR should be generated for the ReportSchedule
\&\f(CW$schedule\fR. The boundaries of the period are determined according to
\&\f(CW$time\fR which detauls to now.
.PP
The hash reference will contain a 'source' key as well as possible
others:
.IP "source" 4
.IX Item "source"
Specify from what kind of source the report should be generated.
Possible values are 'dlf' when the report should be generated from
\&\s-1DLF\s0, 'merging' when the report should be generated by merging previous
\&\s-1XML\s0 reports and 'none' when no data is available for that period and
the report cannot be generated.
.Sp
Note that 'merging' is only available as a source for schedule above
\&'daily'. i.e. 'hourly' and 'daily' reports can only be generated from
\&\s-1DLF\s0. Also of important is the fact that only 'daily' reports are
available as a source of merging. So you need a daily report schedule
to generate 'weekly', 'monthly' and 'yearly' schedule by merging.
.IP "start" 4
.IX Item "start"
The timestamp at which the available data for the period starts. This
can be higher than the requested period's starting boundary.
.IP "end" 4
.IX Item "end"
The timestamp at which the available data for the period ends. This
can be lower than the requested period's ending boundary.
.IP "coverage" 4
.IX Item "coverage"
An integer between 0 and 100 representing the ratio of data available
for the requested period. For example, if only 6 hours of data are
available for a 'daily' report, the 'coverage' will be 25.
.IP "reports" 4
.IX Item "reports"
This key is only available when 'source' is 'merging'. It contains an
array of report files which should be used as the source of merging.
.IP "days" 4
.IX Item "days"
This key is only available when 'source' is 'merging'. It contains the
days for which a reports was available for merging. For example, if
only 6 daily reports were available to generate a 'weekly' report,
this will contain those 6 days dates in \s-1ISO\s0 format (%Y\-%m\-%d).
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fILire::DlfConverter\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 DlfStore.pm,v 1.41 2011/11/15 16:48:40 wraay Exp $
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2002,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\s0 \s-1ANY\s0 \s-1WARRANTY\s0; without even the implied warranty of
\&\s-1MERCHANTABILITY\s0 or \s-1FITNESS\s0 \s-1FOR\s0 A \s-1PARTICULAR\s0 \s-1PURPOSE\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.
.SH "POD ERRORS"
.IX Header "POD ERRORS"
Hey! \fBThe above document had some coding errors, which are explained below:\fR
.IP "Around line 821:" 4
.IX Item "Around line 821:"
You forgot a '=back' before '=head1'