Welcome to the 0.7 release of jga.

jga is a functors library: the intent is to explore and exploit
functors as a design and implementation tool to reduce boilerplate
coding.  A functor is an object that encapsulates a function or
expression: it can take arguments and produce results, as can any
method, expression, or function (in other languages that support
functions).  Unlike an expression, as an object it can be passed as an
argument without being executed; it can be persisted to a database or
file; it can be serialized and passed from client to server (and
back); and it can be instantiated at runtime based on information
unavailable at compile-time.

How many times have you...

...found a method that does almost exactly what you want, except for
   one or two lines?

...created a new class in order to override one simple method, because
   it is almost what you need?

...written a boilerplate implementation of an interface that knows
   about your specific business objects or your specific application?

...copied an entire class to change the one line or method rather
   than refactoring it?</li><br/>

Functors provide a mechanism that can reduce all of the design
problems: they allow you to (in effect) pass a line of code as an
argument to a constructor or method, giving you a way to parameterize
objects on simple behavour.

jga borrows the functors from C++ STL library, and extends them with
functors that are natural for java programmers.  jga also borrows the
notion that basic functors implementing common operations can be
profitably combined into compound structures to implement more useful
logic.

Compound functors of the type that jga promotes fall naturally into a
tree structure.  Taking advantage of this yields a use of functors
that may be relatively new to many: as a form of executable metadata
that can be interpreted for the information embodied in the structure.
To facilitate this, all jga functors provide support for a Visitor
implementation.  

The most natural application of a functor library is in the
implementation of common algorithms, such as those defined in STL.
jga provides a set of such algorithms that have been adapted to java
conventions and idioms, as opposed to being a direct port of STL.

An area that is rife with one line interfaces is event driven programming
of the sort that is typified by Swing.  jga includes the beginnings of a
set of tools for use in GUI coding that addresses the common problems
described above: the continual reinvention of the same set of small
wheels in the set of listeners, editors, renderers, and models that 
accompany a typical Swing program.


Status
======

In this release: 

  - Support for the Java 1.5.0_02

  - The new FunctorParser (and it's typesafe extension GenericParser)
    allow functors to be described using java-like syntax: the parser
    creates the functor that implements the logic described in the 
    expression.

  - Hacker's Worksheet is the next phase in the evolution of the 
    Spreadsheet engine included in the prior release.  This application
    uses the FunctorParser to implement a spreadsheet whose expression
    langauge looks like java in most respects.

For more information, see the CHANGES document.


Requirements
============

 1) Either the Java 1.4.x or 1.5.x JDKs.  The jga-0.7.jar supports 
Generics and is used with the 1.5 JDK, while the jga-0.7-retro.jar supports
development  with the Java 1.4.x JDK without generics.

 2) [Optional] JUnit 3.8.1 and jfcUnit 1.0.3 (if you want to run the tests)


Installation
============

At this point, installation is pretty simple.  Copy jga-0.7.jar or 
jga-0.7-retro.jar (depending on which compiler you use) onto your classpath 
and you're pretty much set.


Building jga
============

To rebuild this version, you must use the 1.5.0_02 release of the Java JDK.

1) Unpack src.jar

2) To build the standard version, use the 'jar' target

   $ ant jar

To build the compatability version, use the 'retrojar' target

   $ ant retrojar


Testing jga-retro-0.7
=====================

The test suite used to ensure 1.4 compatability is built with the 2.2 version
of the early access generic java compiler, which used to be available at

http://developer.java.sun.com/developer/earlyAccess/adding_generics/

However, the last version available through the early access program was 
version 2.4, in which the command line option that I use to derive the test
suite for 1.4 support was removed.  If you have the 2.2 version of the early
access compiler, then you can derive the test suite via ant using the 
enclosed build.xml -- that part of the build script is reasonably well 
commented for what you need to do.  

I've included the non-genericized source code for the test suite in the 
complete distribution, so you can test the jga-retro jar using the 1.4 
compiler.  If you have the 2.2 version of the early access compiler, then 
you can derive this test suite yourself -- I've included notes in the 
build.xml file to get you started.

To test the 1.4 compatability verion, use a 1.4 compatable JVM and run
ant

   $ ant -f build.xml test.nogj

Release Plans
=============

I still anticipate that at some point, continued development on the
the 1.4 compatable jar will end -- the source code will diverge at
that point, and no new features will be added to the 1.4 compatable
jar.  Bugs found will be fixed in both jars, so there may be
subsequent releases of the 1.4 compatable jar, but only as bugs are
found and fixed.  The final version number for the 1.4 compatable jar
will be jga-0.9.jar.

I also still believe that the swing package will be broken out into a
separate jar, named jga-swing-M.n.jar.  I will be focusing on swing
development for a little while longer, possibly looking at ways in
which jga can be incorporated into jdnc.

The core parts of the library (ie, the fn and util packages) are fairly
stable -- there may be one last round of name deprecation, but I anticipate
no major redesign. 

I'm still considering some of the additional features listed below, but
they will be added to a post 1.0 release.


Possible Development
====================

I expect to continue development, with releases every few weeks.  I
think the tasks yet to be done are:

 1) JDBC visitors: using functors to describe the selection criteria
for JDBC statements, providing support for dynamically generating
queries

 2) predicate algebra: the functors form a way to work with
information sybolically -- I want to explore this area to see what can
come of it.  I have used similar concepts with functors in the past to
accomplish some interesting things in the user interface area

 3) EJB usage: using functors on the server side (at least as
parameters for finder methods and for primary keys)

 4) Procedure interface analagous to the current Functor, Predicate,
and Generator interfaces.  Procedure is a common extension in other 
libraries that are covering similar ground as this one.

 5) VariableFunctors: functors that take variable numbers of arguments

  Interface VariableFunctor<R> {
    public R fn(Object[] args);
  }
     
  - or -

  Interface VariableFunctor<T,R> {
    public R fn(List<T> args);
  }

 6) More Adaptors
  
  chainUnary1st   B(bf,uf)   bf.fn(uf(x), y)    :: bf.distribute(uf,Identity)
  chainUnary2nd   B(bf,uf)   bf.fn(x, uf(y))    :: bf.distribute(Identity,uf)
  chainBinary1st  B(bf,bf1)  bf.fn(bf1(x,y), y) :: bf.compose(bf1,Project2nd)
  chainBinary2nd  B(bf,bf1)  bf.fn(x, bf1(x,y)) :: bf.compose(Project1st,bf1)
  swap            B(bf)      bf.fn(y,x)         :: bf.compose(Project2nd,Project1st)
  split           U(bf)      bf.fn(x,x)         :: bf.compose(Identity,Identity)