NAME

       Lire::DlfStore - Interface to a DLF store

SYNOPSIS

         use Lire::DlfStore;

         my $store = Lire::DlfStore->open( "mystore", 1 );
         my $avail_streams = $store->dlf_streams;

DESCRIPTION

   open( $store_path, [ $create ] );
       Opens a Lire::DlfStore residing in the directory pointed by $store_path and returns a Lire::DlfStore
       instance that can be used to access its content.

       If the store $store_path wasn't created, the method will die unless the $create parameter was set to
       true.

       If the store is locked by another process, the method will also die.

       Trying to open the same store twice from the same process will fail.

   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.

   is_closed()
       Returns true if this DlfStore was closed and cannot be used anymore.

   path
       Returns the path to the store. This is the argument used to create the store.

   config
       Returns the configuration of the store instantiated as a Lire::Config::ConfigFile.

   import_jobs()
       Returns as an array ref the list of ImportJob currently configured in the DlfStore

   report_jobs()
       Returns as an array ref the list of ReportJob currently configured in the DlfStore

   has_report_config( $name )
       Returns true if there is a report configuration named $name in this DlfStore.

   report_configurations()
       Returns as an array ref the list of ReporConfig currently configured in the DlfStore

   get_report_config( $name )
       Returns the Lire::ReportConfig object named $name. Throws an exception if it doesn' exists.

DLF STREAMS RELATED METHOD

       A DlfStore can contains multiple Dlf Stream. Dlf Stream is data conforming to a DLF schema. The streams
       are represented by Lire::DlfStream objects.

   dlf_streams()
       List the DLF stream available in the DLF store. This returns a list of DlfSchema's name.

   has_dlf_stream( $name )
       Returns true if the DlfStore contains a DlfStream conforming to the schema $name.

   get_stream_config( $name )
       Returns the Lire::Config::Dictionary instance which contains the stream configuration for the $name
       DlfStream. This method will create an instance from the default if necessary. If $name isn't a valid
       schema name, this method will throw an error.

   configured_dlf_streams()
       Returns the list of DlfStreams which are referenced by the store configuration. This is the result of
       dlf_streams() plus all schemas that exists and are used by one of the confiured ImportJob or
       DlfStreamSpec.

   open_dlf_stream( $name, [$mode], [$sort_spec] )
       Returns a Lire::DlfStream object that can be used to a DLF stream in the schema $name. The $mode
       parameter can either "r" or "w" and defaults to "r".

       If the mode is "w", the Lire::DlfStream is opened for writing (new Dlf records can be inserted). If the
       DlfStore didn't contains a stream $name, an empty one will be created.

       If the mode is "r", the Lire::DlfStream is opened for reading (no DLF records may be inserted). An
       exception will be thrown if there is no stream $name available.

       When the stream is opened in "r" mode, a sort order can be specified by passing a $sort_spec. A
       $sort_spec 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 '-'.

   run_analysers( $stream, [ $dlf_source ] )
       Runs all the configured analysers on the DLF stream $stream.  $dlf_source limit the records which should
       be analysed.

   clean_streams()
       Remove records that are days older than what is configured in the 'keep_days' parameter.

REPORTS RELATED METHOD

       A DlfStore also contains the periodically generated reports. These reports are usually configured through
       the lire(1) command. The generated reports are stored in Lire XML native format by period.

   put_report( $job, $schedule, $report )
       Saves the $report Lire::Report which was generated by $job and $schedule. Returns the filename where the
       report was saved.

   find_report_source( $job, $schedule, [$time] )
       This method will returns an hash reference containing parameters on how the ReportJob $job should be
       generated for the ReportSchedule $schedule. The boundaries of the period are determined according to
       $time which detauls to now.

       The hash reference will contain a 'source' key as well as possible others:

       source
           Specify  from what kind of source the report should be generated.  Possible values are 'dlf' when the
           report should be generated from DLF, 'merging'  when  the  report  should  be  generated  by  merging
           previous  XML  reports  and 'none' when no data is available for that period and the report cannot be
           generated.

           Note that 'merging' is only available as a source for  schedule  above  'daily'.  i.e.  'hourly'  and
           'daily'  reports  can  only  be  generated  from DLF. 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.

       start
           The  timestamp  at  which  the  available  data  for  the  period starts. This can be higher than the
           requested period's starting boundary.

       end The timestamp at which the available data for the period ends. This can be lower than  the  requested
           period's ending boundary.

       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.

       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.

       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 ISO format (%Y-%m-%d).

SEE ALSO

       Lire::DlfConverter(3pm)

AUTHOR

         Francis J. Lacoste <flacoste@logreport.org>

VERSION

       $Id: DlfStore.pm,v 1.41 2011/11/15 16:48:40 wraay Exp $

COPYRIGHT

       Copyright (C) 2002,2004 Stichting LogReport Foundation LogReport@LogReport.org

       This file is part of Lire.

       Lire is free software; you can redistribute it and/or modify it under the terms of the GNU General Public
       License  as  published  by  the  Free  Software  Foundation; either version 2 of the License, or (at your
       option) any later version.

       This program is distributed in the hope that it will be useful, but WITHOUT ANY  WARRANTY;  without  even
       the  implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public
       License for more details.

       You should have received a copy of the GNU General Public License along with this program (see  COPYING);
       if not, check with http://www.gnu.org/copyleft/gpl.html.

Lire 2.1.1                                         2013-08-27                                      DlfStore(3pm)