Java Accumulators and Variants Files

JAccumulator Numeric Library for Java
=====================================

The JAccumulator package brings the convenient type conversion and ad hoc composition capabilities of Javascript to Java programming structures, and fulfills several design goals:

* Accumulators provide a common interface to all value carriers managed by this library, and provide automatic conversions between each, so that they may be manipulated without regard to their underlying implementation strategy (i.e., Strings may be treated like Numbers, doubles like ints, and so on).  Numeric Accumulators allow mathematical operations with any other Accumulator (numeric or otherwise) regardless of their implementation strategy; that is, an integral Accumulator can increment its value against the value of a floating point Accumulator without the caller coding for the implementation type of either.  Likewise, an integral Accumulator can be incremented with the parsed numeric value of a text-based Accumulator without the caller explicitly converting between them.  This is helpful, for instance, in the parsing and production of XML code.

* Accumulators can improve system resource consumption in the case where too many value carriers would be created because of their original non-mutable nature.  For instance,  instead of creating new Double objects after every step in a series of numeric calculations, a single mutable floating point Accumulator may be used and its primitive value modified as needed.

* Accumulators can aid information hiding, and improve design modularity, in the case of hierarchical computations.  Instead of specifying an explicit numeric precision in an API, and forcing a caller to become aware of (and beholden to) that specification, a generic Accumulator could be accepted instead, allowing the caller to specify their own precision requirement.  Both caller and computation producer can remain independent of the other's precision (and even implementation) requirements for the results. This independence can be extended through as many indirections as necessary. For instance, a caller can specify their own implementation to receive the sum of a hierarchy of numbers and the successive provider of each layer of those numbers can remain independent of that implementation choice (e.g., no need to specify getDoubleSum() for instance, or other such implementation-dependent interfaces).

* The default abstract implementation class, Accumulator, is derived from Number and can be used as a replacement for generic Numbers wherever needed.

Accumulators are implemented to help Java provide as many opportunities for performance optimization as possible.  Practically this has meant assigning all variables and methods final by default unless a need arises to allow virtuality or replacement.

Version 4 BETA-1
----------------
* COMPLETE redesign (sorry)
* New structure introduces the Primitive heirarchy as distinct from Accumulator
* Primitives are the simple value carriers, Accumulators introduce heirarchical composition, and Accumulators expand on Primitives through inclusion, not direct extension
* Accumulators are a three-way association between a Primitive, a Javascript-like associative list (from Jupperware), and a function
* Accumulator-level function implementation development is left to other packages, NOT JAccumulator
* Primitive-level functions are included such as RandomPrimitive and Milliseconds
* The BETA-1 package will be released to use and testing prior to the completion of documentation

Version 2.1 BETA-1
----------------
* Added an explicit VoidAccumulator to provide a non-null "null" value that will not throw an exceptions where null values are not expected
* Finer-grained interfaces now separate read functions from write functions in the various contexts
* Introduction of Variant
* Introduced many String- and StringBuffer-like functions
* Operation enumeration support now more modular
* Test enumeration compliments Operation

Version 2.0 BETA-2
----------------
* Introduction of StringAccumulator
* Improved support of String-to-Number conversions
* String/Number conversions now dependent upon Locale and NumberFormat
* Initial support of "void" precision (an accumulator with a "null" value)

Version 2.0 BETA-1
----------------
* "Venetian Blind" interface style
* Better support for generics
* Now supporting boolean and char as numeric values

Version 1.0 BETA-2
----------------
* Improved Java template characteristics
* Added simple String parsing (setValue(String))
* Improved reflection characteristics with all generic Number-based function prototypes (e.g., incrementBy(Number))
* Moved "execute" functionality from AccumulatorOperation enumeration into where it belongs: the Accumulator class
* Improved Javadoc

Version 1.0 BETA-1
----------------
The beta release of this library should be fully functional and should pass all unit tests.  This library just hasn't yet been tested "in the field."  Note that many functions are "final," which I did in order to allow the compiler to perform function inlining to increase performance (I wish Java had explicit inlining, but it does not--sigh).

Building:

This library has been built using Maven 3.  I have included the pom.xml file for your amusement.

Please direct all comments, suggestions and gripes to:
Nicole Tedesco
nicole@tedesco.name

I would really appreciate knowing how this library works out for you, and even the context within which it is being used.