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.