Author: simonetripodi
Date: Fri Jun 1 12:55:30 2012
New Revision: 1345145
URL: http://svn.apache.org/viewvc?rev=1345145&view=rev
Log:
[FUNCTOR-18] Fix duplicated entries in examples page of [functor] website, and replace <br/>
tags in aggregator.xml - patch submitted by Bruno P. Kinoshita
Removed:
commons/proper/functor/trunk/src/site/xdoc/aggregate.xml
Modified:
commons/proper/functor/trunk/src/changes/changes.xml
commons/proper/functor/trunk/src/site/xdoc/aggregator.xml
commons/proper/functor/trunk/src/site/xdoc/examples.xml
Modified: commons/proper/functor/trunk/src/changes/changes.xml
URL: http://svn.apache.org/viewvc/commons/proper/functor/trunk/src/changes/changes.xml?rev=1345145&r1=1345144&r2=1345145&view=diff
==============================================================================
--- commons/proper/functor/trunk/src/changes/changes.xml (original)
+++ commons/proper/functor/trunk/src/changes/changes.xml Fri Jun 1 12:55:30 2012
@@ -23,6 +23,9 @@
</properties>
<body>
<release version="1.0" date="2012-??-??" description="First release.">
+ <action dev="simonetripodi" issue="FUNCTOR-18" due-to="Bruno P. Kinoshita">
+ Fix duplicated entries in examples page of [functor] website, and replace <br/>
tags in aggregator.xml
+ </action>
<action dev="simonetripodi" issue="FUNCTOR-17">
Move developers from @author tags to pom.xml
</action>
Modified: commons/proper/functor/trunk/src/site/xdoc/aggregator.xml
URL: http://svn.apache.org/viewvc/commons/proper/functor/trunk/src/site/xdoc/aggregator.xml?rev=1345145&r1=1345144&r2=1345145&view=diff
==============================================================================
--- commons/proper/functor/trunk/src/site/xdoc/aggregator.xml (original)
+++ commons/proper/functor/trunk/src/site/xdoc/aggregator.xml Fri Jun 1 12:55:30 2012
@@ -29,134 +29,141 @@ limitations under the License.
computations to this data to "aggregate" it. The design allows for a pluggable
implementation to be used for the purpose of aggregation and also provides flexibility
with regards to storing the data being fed to this component.
- <br/>
+ </p>
+ <p>
There are 2 implementations as far as storage is concerned : <i>nostore</i>
and
<code>List</code>-backed store. The former should be used when the aggregation
formula is simple enough to be applied on-the-fly without having to traverse a series
of data -- e.g. summarizing / adding the data -- while the latter can perform more
advanced processing -- e.g.
statistical calculations: median, average, percentile etc.
</p>
- </section>
-
+ </section>
+
<section name="Storage">
- <p>The <code>List</code>-backed store implementation stores the whole
data series in a
- growing <code>List</code> such that when data is aggregated one can traverse
the
- series and apply complex formulas (find the <a href="http://en.wikipedia.org/wiki/Median"
- target="_blank">median</a> of a set of numeric values for instance).
- <br/>
- The framework allows for any <code>List</code>-based implementation to
be plugged in, by
- implementing <a href="apidocs/org/apache/commons/functor/aggregator/AbstractListBackedAggregator.html#createList()">createList()</a>,
- however, there is also an <code>ArrayList</code>-based implementation provided
in
- <a href="apidocs/org/apache/commons/functor/aggregator/ArrayListBackedAggregator.html">ArrayListBackedAggregator</a>
- which can be used out-of-the-box.
- </p>
-
- <p>While the <i>store</i> implementation stores the data in a list,
the <i>nostore</i> one
- stores just a single object -- every time data is fed into the <code>Aggregator</code>,
- the data stored in this object and the data
- <a href="apidocs/org/apache/commons/functor/aggregator/Aggregator.html#add(T)">passed
in</a>
- are "aggregated" there and then using the supplied
- <a href="apidocs/org/apache/commons/functor/BinaryFunction.html">formula</a>
and the result of this operation
- is stored back in the object this implementation uses to store data.
- <br/>
- This has the implication that unlike the list-backed storage implementation (where
the
- result of aggregating the data is not known until <a href="apidocs/org/apache/commons/functor/aggregator/Aggregator.html#evaluate()">evaluate()</a>
- is called), with the <i>nostore</i> implementation the result is known
(and saved back) at
- any moment. This arguably makes this class "faster", however this comes at the cost
of a
- slower <a href="apidocs/org/apache/commons/functor/aggregator/Aggregator.html#add(T)">add()</a>
- operation, as the aggregation formula is applied. Also, let's remind ourselves that
not all
- formulas can be implemented using the <i>nostore</i> implementation (see
above).
+ <p>
+ The <code>List</code>-backed store implementation stores the whole data
series in a
+ growing <code>List</code> such that when data is aggregated one can traverse
the
+ series and apply complex formulas (find the <a href="http://en.wikipedia.org/wiki/Median"
+ target="_blank">median</a> of a set of numeric values for instance).
+ </p>
+ <p>
+ The framework allows for any <code>List</code>-based implementation to
be plugged in, by
+ implementing <a href="apidocs/org/apache/commons/functor/aggregator/AbstractListBackedAggregator.html#createList()">createList()</a>,
+ however, there is also an <code>ArrayList</code>-based implementation
provided in
+ <a href="apidocs/org/apache/commons/functor/aggregator/ArrayListBackedAggregator.html">ArrayListBackedAggregator</a>
+ which can be used out-of-the-box.
+ </p>
+ <p>
+ While the <i>store</i> implementation stores the data in a list, the
<i>nostore</i> one
+ stores just a single object -- every time data is fed into the <code>Aggregator</code>,
+ the data stored in this object and the data
+ <a href="apidocs/org/apache/commons/functor/aggregator/Aggregator.html#add(T)">passed
in</a>
+ are "aggregated" there and then using the supplied
+ <a href="apidocs/org/apache/commons/functor/BinaryFunction.html">formula</a>
and the result of this operation
+ is stored back in the object this implementation uses to store data.
+ </p>
+ <p>
+ This has the implication that unlike the list-backed storage implementation (where
the
+ result of aggregating the data is not known until <a href="apidocs/org/apache/commons/functor/aggregator/Aggregator.html#evaluate()">evaluate()</a>
+ is called), with the <i>nostore</i> implementation the result is known
(and saved back) at
+ any moment. This arguably makes this class "faster", however this comes at the cost
of a
+ slower <a href="apidocs/org/apache/commons/functor/aggregator/Aggregator.html#add(T)">add()</a>
+ operation, as the aggregation formula is applied. Also, let's remind ourselves that
not all
+ formulas can be implemented using the <i>nostore</i> implementation (see
above).
</p>
</section>
-
+
<section name="Flushing Data">
<p>
- The data an aggregator handles can be "reset" at any point -- in the case of the
- <i>store</i> implementation this means emptying the <code>List</code>;
in the case
- of <i>nostore</i> this means setting the "start value" to a "neutral"
value -- for
- instance 0 for implementations which involve additions (<code>Y + 0 = Y</code>),
1 for
- multiplication (<code>Y * 1 = Y</code>) etc. This operation ultimately
resets the
- aggregator to the initial state it was in when created in the first place. This feature
- allows for a caller to schedule regular resets to free up resources etc.
+ The data an aggregator handles can be "reset" at any point -- in the case of the
+ <i>store</i> implementation this means emptying the <code>List</code>;
in the case
+ of <i>nostore</i> this means setting the "start value" to a "neutral"
value -- for
+ instance 0 for implementations which involve additions (<code>Y + 0 = Y</code>),
1 for
+ multiplication (<code>Y * 1 = Y</code>) etc. This operation ultimately
resets the
+ aggregator to the initial state it was in when created in the first place. This
feature
+ allows for a caller to schedule regular resets to free up resources etc.
</p>
</section>
-
+
<section name="Timers">
<p>
- Retrieving the data and regular intervals then flush/reset the aggregator was an
- envisaged scenario for the aggregator -- so the base class
- <a href="apidocs/org/apache/commons/functor/aggregator/AbstractTimedAggregator.html">AbstractTimedAggregator</a>
- offers support to start a timer internally to do that. The class offers a <i>listener</i>
- mechanism where classes can register to receive <a href="apidocs/org/apache/commons/functor/aggregator/TimedAggregatorListener.html">timer
notifications</a> (if timer support was configured) and after all listeners have been
- notified the aggregator is <a href="apidocs/org/apache/commons/functor/aggregator/Aggregator.html#reset()">reset</a>.
- The result of
- <a href="apidocs/org/apache/commons/functor/aggregator/Aggregator.html#evaluate()">evaluate()</a>
- (the result of aggregating data) is passed in to the listeners. This allows for an
object
- to simply register itself as a timer listener to the aggregator and only react to
the
- timer notifications (e.g. write the result to a file for offline analysis etc) while
the
- aggregator itself manages all the internals.
+ Retrieving the data and regular intervals then flush/reset the aggregator was an
+ envisaged scenario for the aggregator -- so the base class
+ <a href="apidocs/org/apache/commons/functor/aggregator/AbstractTimedAggregator.html">AbstractTimedAggregator</a>
+ offers support to start a timer internally to do that. The class offers a <i>listener</i>
+ mechanism where classes can register to receive <a href="apidocs/org/apache/commons/functor/aggregator/TimedAggregatorListener.html">timer
notifications</a> (if timer support was configured) and after all listeners have been
+ notified the aggregator is <a href="apidocs/org/apache/commons/functor/aggregator/Aggregator.html#reset()">reset</a>.
+ The result of
+ <a href="apidocs/org/apache/commons/functor/aggregator/Aggregator.html#evaluate()">evaluate()</a>
+ (the result of aggregating data) is passed in to the listeners. This allows for
an object
+ to simply register itself as a timer listener to the aggregator and only react
to the
+ timer notifications (e.g. write the result to a file for offline analysis etc)
while the
+ aggregator itself manages all the internals.
</p>
-
<p>
When the data is being flushed/reset, a
<a href="apidocs/org/apache/commons/functor/aggregator/TimedAggregatorListener.html">TimedAggregatorListener</a>
can be registered to receive a notification. The notification is sent <b>after</b>
the data is reset.
Prior to resetting the data, <a href="apidocs/org/apache/commons/functor/aggregator/Aggregator.html#evaluate()">evaluate()</a>
- is called, and the result of the evaluation is sent to the listener.<br/>
+ is called, and the result of the evaluation is sent to the listener.
+ </p>
+ <p>
This allows for data aggregated periodically to be processed (e.g. logged, written
into a database etc) without
worrying about what happens in between.
</p>
-
<p>
- There are 2 ways the
- <a href="apidocs/org/apache/commons/functor/aggregator/AbstractTimedAggregator.html">AbstractTimedAggregator</a>
- can be configured with timer support:
- </p>
- <ul>
- <li><b>Using a per-instance timer</b> : by default, when using
the
- <a href="apidocs/org/apache/commons/functor/aggregator/AbstractTimedAggregator.html#AbstractTimedAggregator(long)">1
- parameter constructor</a> with a value > 0, the aggregator will create
a
- <code>Timer</code> object internally and schedule the regular task of
resetting the
- aggregator under this <code>Timer</code>. While this helps preventing
memory leaks
- (both <code>Aggregator</code> and <code>Timer</code> will
be recycled together) it
- does increase the threading level in the system with each aggregator object created.
- If your system creates a lot of <code>AbstractTimedAggregator</code>
instances with
- timer support, you might want to consider using the shared timer (see below).</li>
- <li><b>Using a shared timer</b> : the <a
- href="apidocs/org/apache/commons/functor/aggregator/AbstractTimedAggregator.html">AbstractTimedAggregator</a>
- class creates a <a
- href="apidocs/org/apache/commons/functor/aggregator/AbstractTimedAggregator.html#MAIN_TIMER">static
- timer instance</a> which can be shared amongst all instances of this class,
if using
- <a
- href="apidocs/org/apache/commons/functor/aggregator/AbstractTimedAggregator.html#AbstractTimedAggregator(long,
boolean)">the
- constructor with 2 params</a>. When doing so, each such instance will schedule
its
- regular reset task against this timer. While this reduces the memory footprint and
- threading on the system, it can lead to memory leaks if this is not handled correctly.
- Therefore please make sure you invoke <a
- href="apidocs/org/apache/commons/functor/aggregator/AbstractTimedAggregator.html#stop()">stop()</a>
- on such aggregators when finished working with them.</li>
- </ul>
- <p>
- It is recommended you always invoke <a
- href="apidocs/org/apache/commons/functor/aggregator/AbstractTimedAggregator.html#stop()">stop()</a>
- at the end of the lifecycle of an aggregator -- regardless of timer support (shared
/
- per instance) or not -- in particular calling <code>stop()</code> on an
aggregator with
- no timer support has no effect, however doing so ensures code uniformity and cleanliness.
+ There are 2 ways the
+ <a href="apidocs/org/apache/commons/functor/aggregator/AbstractTimedAggregator.html">AbstractTimedAggregator</a>
+ can be configured with timer support:
+ </p>
+ <p>
+ <ul>
+ <li><b>Using a per-instance timer</b> : by default, when
using the
+ <a href="apidocs/org/apache/commons/functor/aggregator/AbstractTimedAggregator.html#AbstractTimedAggregator(long)">1
+ parameter constructor</a> with a value > 0, the aggregator will
create a
+ <code>Timer</code> object internally and schedule the regular task
of resetting the
+ aggregator under this <code>Timer</code>. While this helps preventing
memory leaks
+ (both <code>Aggregator</code> and <code>Timer</code>
will be recycled together) it
+ does increase the threading level in the system with each aggregator object
created.
+ If your system creates a lot of <code>AbstractTimedAggregator</code>
instances with
+ timer support, you might want to consider using the shared timer (see below).</li>
+ <li><b>Using a shared timer</b> : the <a
+ href="apidocs/org/apache/commons/functor/aggregator/AbstractTimedAggregator.html">AbstractTimedAggregator</a>
+ class creates a <a
+ href="apidocs/org/apache/commons/functor/aggregator/AbstractTimedAggregator.html#MAIN_TIMER">static
+ timer instance</a> which can be shared amongst all instances of this
class, if using
+ <a
+ href="apidocs/org/apache/commons/functor/aggregator/AbstractTimedAggregator.html#AbstractTimedAggregator(long,
boolean)">the
+ constructor with 2 params</a>. When doing so, each such instance will
schedule its
+ regular reset task against this timer. While this reduces the memory footprint
and
+ threading on the system, it can lead to memory leaks if this is not handled
correctly.
+ Therefore please make sure you invoke <a
+ href="apidocs/org/apache/commons/functor/aggregator/AbstractTimedAggregator.html#stop()">stop()</a>
+ on such aggregators when finished working with them.</li>
+ </ul>
+ </p>
+ <p>
+ It is recommended you always invoke <a
+ href="apidocs/org/apache/commons/functor/aggregator/AbstractTimedAggregator.html#stop()">stop()</a>
+ at the end of the lifecycle of an aggregator -- regardless of timer support (shared
/
+ per instance) or not -- in particular calling <code>stop()</code> on
an aggregator with
+ no timer support has no effect, however doing so ensures code uniformity and cleanliness.
</p>
</section>
-
+
<section name="Examples">
- <p>An example of usage for this component (though not necessarily the only one)
could be in
- a highly transactional system where, for instance, the average transaction time can
be an
- indication of the system health. While a fully-fledged monitoring system can say monitor
- the system load, file system etc., you might also want your monitoring system to keep
an
- eye on the average transaction time. One way to do so is have an <a
- href="apidocs/org/apache/commons/functor/aggregator/AbstractTimedAggregator.html">AbstractTimedAggregator</a>
- which is capturing each transaction execution time and every say 5 seconds it computes
- the arithmetic mean (average) and writes that to a log file (which then your monitoring
- system can tail). To do so you would use a piece of code like this:
+ <p>
+ An example of usage for this component (though not necessarily the only one) could
be in
+ a highly transactional system where, for instance, the average transaction time can
be an
+ indication of the system health. While a fully-fledged monitoring system can say
monitor
+ the system load, file system etc., you might also want your monitoring system to
keep an
+ eye on the average transaction time. One way to do so is have an <a
+ href="apidocs/org/apache/commons/functor/aggregator/AbstractTimedAggregator.html">AbstractTimedAggregator</a>
+ which is capturing each transaction execution time and every say 5 seconds it computes
+ the arithmetic mean (average) and writes that to a log file (which then your monitoring
+ system can tail). To do so you would use a piece of code like this:
</p>
-
+
<source>
public class AggregatorTesting implements TimedAggregatorListener<Double> {
Aggregator<Double> agg;
@@ -185,16 +192,16 @@ public class AggregatorTesting implement
t.add( 2.0 );
/* .. */
}
-}
+}
</source>
-
+
<p>Now let's assume that you occasionally see the odd spike in transaction times
-- which,
for the purpose of this example, we'll assume is normal. As such you are not concerned
with
these spikes, so you want a formula to exclude them. Chances are an arithmetic median
would be more appropriate in this case; in which case the code above can suffer just
a
small change:
</p>
-
+
<source>
...
AbstractTimedAggregator<Double> aggregator = new ArrayListBackedAggregator<Double>(new
DoubleMedianValueAggregatorFunction(),
@@ -206,14 +213,14 @@ public class AggregatorTesting implement
take less than a certain execution time, so you replace the median formula with a
percentile one:
</p>
-
+
<source>
...
AbstractTimedAggregator<Double> aggregator = new ArrayListBackedAggregator<Double>(new
DoublePercentileAggregatorFunction(95),
5000L);
...
</source>
-
+
<p>Or maybe your health indicator is the number of transactions going through
the system
every 5 seconds. In this case you can use a <i>nostore</i> aggregator with
a sum formula
like this:
@@ -254,58 +261,62 @@ public class AggregatorTesting implement
}
}
</source>
-
+
<p>(Bear in mind that there is also a
<a href="apidocs/org/apache/commons/functor/aggregator/functions/IntegerCountAggregatorBinaryFunction.html">IntegerCountAggregatorBinaryFunction</a>
too!)
</p>
-
+
<p>This has the advantage of a lower memory footprint as well (see above). If
your healthcheck
indicator is based on the maximum transaction time over a 5 seconds interval, then
you simply
replace the <a href="apidocs/org/apache/commons/functor/aggregator/AbstractNoStoreAggregator.html#getAggregationFunction()">aggregation
function</a> with a max value implementation:
</p>
-
+
<source>
...
AbstractTimedAggregator<Double> aggregator = new AbstractNoStoreAggregator<Double>(
new DoubleMaxAggregatorBinaryFunction(), 5000L) {
...
</source>
-
- <p>Or you can simply roll out your own code -- if using the <i>nostore</i>
implementation,
- all you need to do is implement a
- <a href="apidocs/org/apache/commons/functor/BinaryFunction.html">BinaryFunction</a>
and pass
- it to the <a href="apidocs/org/apache/commons/functor/aggregator/AbstractNoStoreAggregator.html#AbstractNoStoreAggregator(org.apache.commons.functor.BinaryFunction)">Aggregator
- constructor</a>. This function will receive the already-stored
- aggregated value as the first parameter, and data just passed in (via <a
- href="apidocs/org/apache/commons/functor/aggregator/Aggregator.html#add(T)">add()</a>)
as the
- second parameter; the result of this function will be stored back in the aggregator.
- <br/>
- For the list-based aggregators, use an instance of
- <a href="apidocs/org/apache/commons/functor/aggregator/AbstractListBackedAggregator.html">AbstractListBackedAggregator</a>
- and pass in an instance of <a href="apidocs/org/apache/commons/functor/UnaryFunction.html">UnaryFunction</a>
- which accepts a <code>List</code> and returns a single object.
- <br/>
- Have a look at the
- <a href="apidocs/org/apache/commons/functor/aggregator/functions/package-summary.html">org.apache.commons.functor.aggregator.functions
- package</a> which includes a set of functions to achieve various of these tasks
already.
- </p>
-
- <p><b>Note on class naming</b> : You will notice in the
- <a href="apidocs/org/apache/commons/functor/aggregator/functions/package-summary.html">org.apache.commons.functor.aggregator.functions
- package</a> there are functions with similar names -- e.g.
- <a href="apidocs/org/apache/commons/functor/aggregator/functions/DoubleSumAggregatorFunction.html">DoubleSumAggregatorFunction</a>
- and <a href="apidocs/org/apache/commons/functor/aggregator/functions/DoubleSumAggregatorBinaryFunction.html">DoubleSumAggregatorBinaryFunction</a>.
- The naming convention is that if the function takes 2
- parameters (i.e. it is an instance of <a href="apidocs/org/apache/commons/functor/BinaryFunction.html">BinaryFunction</a>
then the
- name of the class in this package will contain <code>BinaryFunction</code>,
otherwise, if it is an instance
- of <a href="apidocs/org/apache/commons/functor/UnaryFunction.html">UnaryFunction</a>
then the
- name will only contain <code>Function</code>.<br/>
- The reason behind it is that instances of <code>BinaryFunction</code> can
be used with
- <a href="apidocs/org/apache/commons/functor/aggregator/AbstractNoStoreAggregator.html">AbstractNoStoreAggregator</a>
- whereas the instances of <code>UnaryFunction</code> can be used
- with <a href="apidocs/org/apache/commons/functor/aggregator/AbstractTimedAggregator.html">AbstractTimedAggregator</a>.
- </p>
+
+ <p>Or you can simply roll out your own code -- if using the <i>nostore</i>
implementation,
+ all you need to do is implement a
+ <a href="apidocs/org/apache/commons/functor/BinaryFunction.html">BinaryFunction</a>
and pass
+ it to the <a href="apidocs/org/apache/commons/functor/aggregator/AbstractNoStoreAggregator.html#AbstractNoStoreAggregator(org.apache.commons.functor.BinaryFunction)">Aggregator
+ constructor</a>. This function will receive the already-stored
+ aggregated value as the first parameter, and data just passed in (via <a
+ href="apidocs/org/apache/commons/functor/aggregator/Aggregator.html#add(T)">add()</a>)
as the
+ second parameter; the result of this function will be stored back in the aggregator.
+ </p>
+ <p>
+ For the list-based aggregators, use an instance of
+ <a href="apidocs/org/apache/commons/functor/aggregator/AbstractListBackedAggregator.html">AbstractListBackedAggregator</a>
+ and pass in an instance of <a href="apidocs/org/apache/commons/functor/UnaryFunction.html">UnaryFunction</a>
+ which accepts a <code>List</code> and returns a single object.
+ </p>
+ <p>
+ Have a look at the
+ <a href="apidocs/org/apache/commons/functor/aggregator/functions/package-summary.html">org.apache.commons.functor.aggregator.functions
+ package</a> which includes a set of functions to achieve various of these tasks
already.
+ </p>
+
+ <p><b>Note on class naming</b> : You will notice in the
+ <a href="apidocs/org/apache/commons/functor/aggregator/functions/package-summary.html">org.apache.commons.functor.aggregator.functions
+ package</a> there are functions with similar names -- e.g.
+ <a href="apidocs/org/apache/commons/functor/aggregator/functions/DoubleSumAggregatorFunction.html">DoubleSumAggregatorFunction</a>
+ and <a href="apidocs/org/apache/commons/functor/aggregator/functions/DoubleSumAggregatorBinaryFunction.html">DoubleSumAggregatorBinaryFunction</a>.
+ The naming convention is that if the function takes 2
+ parameters (i.e. it is an instance of <a href="apidocs/org/apache/commons/functor/BinaryFunction.html">BinaryFunction</a>
then the
+ name of the class in this package will contain <code>BinaryFunction</code>,
otherwise, if it is an instance
+ of <a href="apidocs/org/apache/commons/functor/UnaryFunction.html">UnaryFunction</a>
then the
+ name will only contain <code>Function</code>.
+ </p>
+ <p>
+ The reason behind it is that instances of <code>BinaryFunction</code> can
be used with
+ <a href="apidocs/org/apache/commons/functor/aggregator/AbstractNoStoreAggregator.html">AbstractNoStoreAggregator</a>
+ whereas the instances of <code>UnaryFunction</code> can be used
+ with <a href="apidocs/org/apache/commons/functor/aggregator/AbstractTimedAggregator.html">AbstractTimedAggregator</a>.
+ </p>
</section>
</body>
-</document>
+</document>
\ No newline at end of file
Modified: commons/proper/functor/trunk/src/site/xdoc/examples.xml
URL: http://svn.apache.org/viewvc/commons/proper/functor/trunk/src/site/xdoc/examples.xml?rev=1345145&r1=1345144&r2=1345145&view=diff
==============================================================================
--- commons/proper/functor/trunk/src/site/xdoc/examples.xml (original)
+++ commons/proper/functor/trunk/src/site/xdoc/examples.xml Fri Jun 1 12:55:30 2012
@@ -222,7 +222,29 @@ filteredGenerator.run(compositeProcedure
The <a href="http://svn.apache.org/viewvc/commons/proper/functor/trunk/src/test/java/org/apache/commons/functor/example/lines/">lines</a>
package demonstrates a functional approach to IO using Generators and the Algorithms
class.
</p>
- </subsection>
+ </subsection>
+
+ <subsection name="Aggregators">
+ <p>
+ There are some code snippets / examples for the <code>org.apache.commons.functor.aggregator</code>
package
+ available on <a href="aggregator.html">this page</a>. Also, to exemplify
the usage of the <code>Aggregator</code>
+ classes, there are code examples in the test section.
+ </p>
+ <p>
+ First such set of example involves the usage of the <i>nostore</i> <code>Aggregator</code>.
Code can be found in
+ <a href="http://svn.apache.org/viewvc/commons/proper/functor/trunk/src/test/java/org/apache/commons/functor/example/aggregator/nostore/">org.apache.commons.functor.example.aggregator.nostore</a>.
+ This shows how can you use an aggregator which doesn't store the data series and
processes them on the fly.
+ Also, there are examples provided which show how can you implement your own aggregation
function
+ to be used with this <code>Aggregator</code> type.
+ </p>
+ <p>
+ For using an <code>Aggregator</code> which stores the data series in
a list, examples are in
+ <a href="http://svn.apache.org/viewvc/commons/proper/functor/trunk/src/test/java/org/apache/commons/functor/example/aggregator/list/">org.apache.commons.functor.example.aggregator.list</a>.
+ This shows how can you use the <code>ArrayList</code>-backed aggregator
or provide your own <code>List</code>-based implementation.
+ Also, there are examples provided which show how can you implement your own aggregation
function
+ to be used with this <code>Aggregator</code> type.
+ </p>
+ </subsection>
<subsection name="Code Katas">
<p>
@@ -270,80 +292,9 @@ filteredGenerator.run(compositeProcedure
<a href="http://svn.apache.org/repos/asf/commons/proper/functor/trunk/src/test/java/org/apache/commons/functor/example/kata/four/TestSoccer.java">soccer
(football)</a>
parsers.
</dd>
-
</dl>
</subsection>
- <subsection name="Generators">
- <p>
- The <a href="http://svn.apache.org/viewvc/commons/proper/functor/trunk/src/test/java/org/apache/commons/functor/example/lines/">lines</a>
- package demonstrates a functional approach to IO using Generators and the Algorithms
class.
- </p>
- </subsection>
-
- <subsection name="Aggregators">
- <p>
- There are some code snippets / examples for the <code>org.apache.commons.functor.aggregator</code>
package
- available on <a href="aggregator.html">this page</a>. Also, to exemplify
the usage of the <code>Aggregator</code>
- classes, there are code examples in the test section.
- <br/>
- First such set of example involves the usage of the <i>nostore</i>
<code>Aggregator</code>. Code can be found in
- <a href="http://svn.apache.org/viewvc/commons/proper/functor/trunk/src/test/java/org/apache/commons/functor/example/aggregator/nostore/">org.apache.commons.functor.example.aggregator.nostore</a>.
- This shows how can you use an aggregator which doesn't store the data series
and processes them on the fly.
- Also, there are examples provided which show how can you implement your own aggregation
function
- to be used with this <code>Aggregator</code> type.
- <br/>
- For using an <code>Aggregator</code> which stores the data series
in a list, examples are in
- <a href="http://svn.apache.org/viewvc/commons/proper/functor/trunk/src/test/java/org/apache/commons/functor/example/aggregator/list/">org.apache.commons.functor.example.aggregator.list</a>.
- This shows how can you use the <code>ArrayList</code>-backed aggregator
or provide your own <code>List</code>-based implementation.
- Also, there are examples provided which show how can you implement your own aggregation
function
- to be used with this <code>Aggregator</code> type.
- </p>
- </subsection>
-
- <subsection name="Reuse Through Composition">
- <p>
- The Functor package, and more generally, a functional approach
- to program design, supports a powerful technique for balancing
- behavior specialization and code reuse.
- </p>
- <p>
- Traditional Object Oriented design suggests inheritence as a
- mechanism code reuse, and method overloading as a mechanism for
- specialization. For example, one defines a general purpose, perhaps
- even abstract class, say <i>AbstractList</i>, and then extend or
- specialize this parent via subclasses, inheriting some behaviors
- and overloading others.
- </p>
- <p>
- Functors encourage another, complementary approach to code reuse
- and behavior specialiazation: composition. Following a compositional
- design, we create a number of simple objects and then combine them to
- create more complex behaviors. For example, the
- <a href="http://commons.apache.org/pool/">Commons Pool</a>
- component defines an <code>ObjectPool</code> type that maintains
- a collection of pooled objects, but delegates to a
- <code>PoolableObjectFactory</code> to create, validate and destroy
- the objects to be pooled. Arbitrary <code>ObjectPool</code>
- implementations can be composed with arbitrary
- <code>PoolableObjectFactory</code>
- implementations in order to create new types of pools.
- </p>
- <p>
- The
- <a href="http://svn.apache.org/repos/asf/commons/proper/functor/trunk/src/test/java/org/apache/commons/functor/example/FlexiMapExample.java">FlexiMap
example</a>
- applies this design to <code>java.util.Map</code>, demonstrating
how
- "pluggable" functors can be applied to a generic <code>Map</code>
structure in order
- to introduce new behaviors.
- </p>
- <p>
- The
- <a href="http://svn.apache.org/repos/asf/commons/proper/functor/trunk/src/test/java/org/apache/commons/functor/example/map">map</a>
- package is a more complete example of this, implementing a number of the Commons-Collections
Maps
- derived from a base
- <a href="http://svn.apache.org/repos/asf/commons/proper/functor/trunk/src/test/java/org/apache/commons/functor/example/map/FunctoredMap.java">FunctoredMap</a>.
- </p>
- </subsection>
<subsection name="A Quicksort Implementation">
<p>
The <a href="http://svn.apache.org/repos/asf/commons/proper/functor/trunk/src/test/java/org/apache/commons/functor/example/QuicksortExample.java">Quicksort
example</a>
|