.\" 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 "Aggregator 3pm"
.TH Aggregator 3pm "2006-07-23" "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::Aggregator \- Base class for all aggregator operators
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use base qw/ Lire::Aggregator /;
.Ve
.SH "DESCRIPTION"
.IX Header "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.
.PP
In Lire, an aggregator is an operator which will group \s-1DLF\s0 records.
Other operators like avg or sum will then compute values in these
groups of \s-1DLF\s0 records. Aggregators can be nested to compute values on
hierarchical groups.
.SH "METHODS"
.IX Header "METHODS"
.SS "ops( [$new_ops] )"
.IX Subsection "ops( [$new_ops] )"
Returns the operators contained in this aggregator. The returned value
is a reference to an array of Lire::ReportOperator objects.
.PP
If the \f(CW$new_ops\fR is used, it changes the content of this aggragagor to
these new values. \f(CW$new_ops\fR should be a reference to an array
containing Lire::ReportOperator objects.
.ie n .SS "op_by_name( $name )"
.el .SS "op_by_name( \f(CW$name\fP )"
.IX Subsection "op_by_name( $name )"
Returns the operator named \f(CW$name\fR in this aggregator. An exception is
thrown if there is no such operator.
.ie n .SS "is_name_defined( $name )"
.el .SS "is_name_defined( \f(CW$name\fP )"
.IX Subsection "is_name_defined( $name )"
Returns true if this aggregator contains an operator named \f(CW$name\fR.
.SH "METHODS FOR SUBCLASSES"
.IX Header "METHODS FOR SUBCLASSES"
.ie n .SS "print( $fh, $pfx )"
.el .SS "print( \f(CW$fh\fP, \f(CW$pfx\fP )"
.IX Subsection "print( $fh, $pfx )"
This methods implements the \fIprint()\fR method required by
Lire::ReportOpetor. It prints the \s-1XML\s0 element named after \fIop()\fR and
takes care of writing the \s-1XML\s0 representation of all the children
operation. It also takes care of writing the name and label attribute.
Other attributes can be added to the \s-1XML\s0 element by overriding the
\&\fIxml_attrs()\fR method. Other children elements could be added to the
output stream by overriding the \fIprint_content()\fR method.
.SS "\fIxml_attrs()\fP"
.IX Subsection "xml_attrs()"
This method can be used to write additional \s-1XML\s0 attributes. The
returned string will be output in the \s-1XML\s0 element.
.ie n .SS "print_content( $fh, $pfx )"
.el .SS "print_content( \f(CW$fh\fP, \f(CW$pfx\fP )"
.IX Subsection "print_content( $fh, $pfx )"
This method prints the operators contained in this aggregator. It can
be overriden to add some other elements.
.ie n .SS "create_group_info( $info )"
.el .SS "create_group_info( \f(CW$info\fP )"
.IX Subsection "create_group_info( $info )"
\&\s-1FIXME\s0
.PP
Subclasses have to override the \fIcreate_categorical_info()\fR method for
this implementation.
.ie n .SS "create_categorical_info( $info )"
.el .SS "create_categorical_info( \f(CW$info\fP )"
.IX Subsection "create_categorical_info( $info )"
This method is used by the implementation of \fIcreate_group_info()\fR to add
the categorical ColumnInfo provided by the aggregator.
.ie n .SS "create_entries( $subreport )"
.el .SS "create_entries( \f(CW$subreport\fP )"
.IX Subsection "create_entries( $subreport )"
This method is used by Lire::ReportSpec to fill the
Lire::Report::Subreport with the entries when creating the subreport.
.PP
The \f(CW$subreport\fR parameter contains the Subreport object to which the
subreport's entries should get added.
.PP
This method will only be called on the top-level aggregator in the
report.
.ie n .SS "build_query( $query )"
.el .SS "build_query( \f(CW$query\fP )"
.IX Subsection "build_query( $query )"
\&\s-1FIXME\s0
.ie n .SS "set_group_summary( $group, $row )"
.el .SS "set_group_summary( \f(CW$group\fP, \f(CW$row\fP )"
.IX Subsection "set_group_summary( $group, $row )"
\&\s-1FIXME\s0
.ie n .SS "create_entry( $group, $row )"
.el .SS "create_entry( \f(CW$group\fP, \f(CW$row\fP )"
.IX Subsection "create_entry( $group, $row )"
\&\s-1FIXME\s0
.SH "MERGING AGGRATOR API"
.IX Header "MERGING AGGRATOR API"
It defines additional methods required by Aggregator implementation to
be able to merge data..
.PP
The base Aggregator implementation takes care of merging the summary
information included in the Lire \s-1XML\s0 reports.
.PP
The merging specifics to the aggregator should be implemented in
the \fIinit_agggregator_data()\fR, \fIupdate_aggregator_data()\fR and
\&\fIend_aggregator_data()\fR methods.
.PP
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),
.SH "IMPLEMENTATION OF Lire::ReportOperator MERGING METHODS"
.IX Header "IMPLEMENTATION OF Lire::ReportOperator MERGING METHODS"
.ie n .SH "init_merge( $period_start, $period_end )"
.el .SH "init_merge( \f(CW$period_start\fP, \f(CW$period_end\fP )"
.IX Header "init_merge( $period_start, $period_end )"
The default implementation makes sure that all contained operators are
inited.
.PP
Implementation of specific aggregator must chain up to this method, if
they override it.
.SS "\fIend_merge()\fP"
.IX Subsection "end_merge()"
The default implementation makes sure that all operators gets the
\&\fIend_report()\fR event.
.PP
Subclasses should chain up to this method, if they override it.
.SS "\fIinit_group_data()\fP"
.IX Subsection "init_group_data()"
The Aggregator implements \fIinit_group_data()\fR. It takes care of
computing the summary information. Subclass does the equivalent in
\&\fIinit_aggregator_data()\fR.
.ie n .SS "merge_group_data( $value, $data )"
.el .SS "merge_group_data( \f(CW$value\fP, \f(CW$data\fP )"
.IX Subsection "merge_group_data( $value, $data )"
The Aggregator implements \fImerge_group_data()\fR. It takes care of merging
the summary information. Subclass does the equivalent in
\&\fImerge_aggregator_data()\fR.
.SS "end_group_data($data)"
.IX Subsection "end_group_data($data)"
The Aggregator implements \fIend_group_data()\fR. It takes care of
computing the summary information. Subclass does the equivalent in
\&\fIend_aggregator_data()\fR.
.ie n .SS "add_entry_value( $entry, $data )"
.el .SS "add_entry_value( \f(CW$entry\fP, \f(CW$data\fP )"
.IX Subsection "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.
.PP
There is no reason to override that method since the entries of the
aggregator are added in the \fIcreate_group_entries()\fR method.
.SH "METHODS THAT SHOULD BE IMPLEMENTED BY SUBCLASSES FOR MERGING"
.IX Header "METHODS THAT SHOULD BE IMPLEMENTED BY SUBCLASSES FOR MERGING"
.SS "\fIinit_aggregator_data()\fP"
.IX Subsection "init_aggregator_data()"
This is the equivalent of \fIinit_group_data()\fR and is called from
Aggregator's implementation of \fIinit_group_data()\fR.
.ie n .SS "merge_aggregator_data( $value, $data )"
.el .SS "merge_aggregator_data( \f(CW$value\fP, \f(CW$data\fP )"
.IX Subsection "merge_aggregator_data( $value, $data )"
This method is the equivalent than \fImerge_group_data()\fR and is called
from Aggregator's implementation of \fImerge_group_data()\fR.
.ie n .SS "end_aggregator_data( $data )"
.el .SS "end_aggregator_data( \f(CW$data\fP )"
.IX Subsection "end_aggregator_data( $data )"
This method is the equivalent of the \fIend_group_data()\fR and is called
from Aggregator's implementation of \fIend_group_data()\fR.
.ie n .SS "create_group_entries( $group, $data )"
.el .SS "create_group_entries( \f(CW$group\fP, \f(CW$data\fP )"
.IX Subsection "create_group_entries( $group, $data )"
In this method, the aggregator should add one Lire::Report::Entry
object for every group merged by the aggregator.
.PP
\&\f(CW$group\fR is an instance of Lire::Report::Group to which the entries
should be added. \f(CW$data\fR is the data structure returned by
\&\fIinit_group_data()\fR for the group in which the aggregator is nested (or
the only structure that was created when the aggregator is the
top-level aggregator).
.PP
In this method, the aggregator must make sure to call
\&\fIadd_entry_value()\fR on its contained operators for each entry created.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.Vb 3
\& Lire::ReportSpec(3pm), Lire::Aggregate(3pm), Lire::ReportOperator(3pm),
\& Lire::Group(3pm), Lire::Timegroup(3pm), Lire::Timeslot(3pm),
\& Lire::Rangegroup(3pm)
.Ve
.SH "AUTHORS"
.IX Header "AUTHORS"
.Vb 2
\& Francis J. Lacoste <flacoste@logreport.org>
\& Wolgang Sourdeau <wsourdeau@logreport.org>
.Ve
.SH "VERSION"
.IX Header "VERSION"
\&\f(CW$Id:\fR Aggregator.pm,v 1.29 2006/07/23 13:16:27 vanbaal Exp $
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2001\-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.