Aggregator(3pm) 					  LogReport's Lire Documentation					   Aggregator(3pm)

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.

Lire 2.1.1							    2006-07-23							   Aggregator(3pm)