NAME

       Lire::Aggregator - Base class for all aggregator operators

SYNOPSIS

           use base qw/ Lire::Aggregator /;

DESCRIPTION

       The Lire::Aggregator is the base class for all the aggregator operators available in Lire.
       It implements behavior common to all the aggregator as well as defining some methods that
       need to be implemented by subclasses.

       In Lire, an aggregator is an operator which will group DLF records.  Other operators like
       avg or sum will then compute values in these groups of DLF records. Aggregators can be
       nested to compute values on hierarchical groups.

METHODS

   ops( [$new_ops] )
       Returns the operators contained in this aggregator. The returned value is a reference to
       an array of Lire::ReportOperator objects.

       If the $new_ops is used, it changes the content of this aggragagor to these new values.
       $new_ops should be a reference to an array containing Lire::ReportOperator objects.

   op_by_name( $name )
       Returns the operator named $name in this aggregator. An exception is thrown if there is no
       such operator.

   is_name_defined( $name )
       Returns true if this aggregator contains an operator named $name.

METHODS FOR SUBCLASSES

   print( $fh, $pfx )
       This methods implements the print() method required by Lire::ReportOpetor. It prints the
       XML element named after op() and takes care of writing the XML representation of all the
       children operation. It also takes care of writing the name and label attribute.  Other
       attributes can be added to the XML element by overriding the xml_attrs() method. Other
       children elements could be added to the output stream by overriding the print_content()
       method.

   xml_attrs()
       This method can be used to write additional XML attributes. The returned string will be
       output in the XML element.

   print_content( $fh, $pfx )
       This method prints the operators contained in this aggregator. It can be overriden to add
       some other elements.

   create_group_info( $info )
       FIXME

       Subclasses have to override the create_categorical_info() method for this implementation.

   create_categorical_info( $info )
       This method is used by the implementation of create_group_info() to add the categorical
       ColumnInfo provided by the aggregator.

   create_entries( $subreport )
       This method is used by Lire::ReportSpec to fill the Lire::Report::Subreport with the
       entries when creating the subreport.

       The $subreport parameter contains the Subreport object to which the subreport's entries
       should get added.

       This method will only be called on the top-level aggregator in the report.

   build_query( $query )
       FIXME

   set_group_summary( $group, $row )
       FIXME

   create_entry( $group, $row )
       FIXME

MERGING AGGRATOR API

       It defines additional methods required by Aggregator implementation to be able to merge
       data..

       The base Aggregator implementation takes care of merging the summary information included
       in the Lire XML reports.

       The merging specifics to the aggregator should be implemented in the
       init_agggregator_data(), update_aggregator_data() and end_aggregator_data() methods.

       This class also takes care of the case when the aggregator is the top-level aggregator,
       that is the immediate child of the report-calc-spec element in the report specification),

IMPLEMENTATION OF Lire::ReportOperator MERGING METHODS

init_merge( $period_start, $period_end )

       The default implementation makes sure that all contained operators are inited.

       Implementation of specific aggregator must chain up to this method, if they override it.

   end_merge()
       The default implementation makes sure that all operators gets the end_report() event.

       Subclasses should chain up to this method, if they override it.

   init_group_data()
       The Aggregator implements init_group_data(). It takes care of computing the summary
       information. Subclass does the equivalent in init_aggregator_data().

   merge_group_data( $value, $data )
       The Aggregator implements merge_group_data(). It takes care of merging the summary
       information. Subclass does the equivalent in merge_aggregator_data().

   end_group_data($data)
       The Aggregator implements end_group_data(). It takes care of computing the summary
       information. Subclass does the equivalent in end_aggregator_data().

   add_entry_value( $entry, $data )
       This method will make sure that the entries of nested aggregator are wrapped up in a
       Lire::Report::Group element.

       There is no reason to override that method since the entries of the aggregator are added
       in the create_group_entries() method.

METHODS THAT SHOULD BE IMPLEMENTED BY SUBCLASSES FOR MERGING

   init_aggregator_data()
       This is the equivalent of init_group_data() and is called from Aggregator's implementation
       of init_group_data().

   merge_aggregator_data( $value, $data )
       This method is the equivalent than merge_group_data() and is called from Aggregator's
       implementation of merge_group_data().

   end_aggregator_data( $data )
       This method is the equivalent of the end_group_data() and is called from Aggregator's
       implementation of end_group_data().

   create_group_entries( $group, $data )
       In this method, the aggregator should add one Lire::Report::Entry object for every group
       merged by the aggregator.

       $group is an instance of Lire::Report::Group to which the entries should be added. $data
       is the data structure returned by init_group_data() for the group in which the aggregator
       is nested (or the only structure that was created when the aggregator is the top-level
       aggregator).

       In this method, the aggregator must make sure to call add_entry_value() on its contained
       operators for each entry created.

SEE ALSO

        Lire::ReportSpec(3pm), Lire::Aggregate(3pm), Lire::ReportOperator(3pm),
        Lire::Group(3pm), Lire::Timegroup(3pm), Lire::Timeslot(3pm),
        Lire::Rangegroup(3pm)

AUTHORS

        Francis J. Lacoste <flacoste@logreport.org>
        Wolgang Sourdeau <wsourdeau@logreport.org>

VERSION

       $Id: Aggregator.pm,v 1.29 2006/07/23 13:16:27 vanbaal Exp $

COPYRIGHT

       Copyright (C) 2001-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.