Simple Persistence for Java
~~~~~~~~~~~~~~~~~~~~~~~~~~~

This library is an Object/Relation mapping framework for Java. It
is designed to be easy to use (no xmls to write, no tables to create,
no ids to generate, no primary keys to fiddle with, just point it to the 
database, check the apidoc for 3 basic methods and code away). It supports 
transactions, has it's own simple query language (very similar to sql), 
can handle object references, lists, maps.

When to use this framework instead of the bazillion others
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The aim of this Java library is to provide a _simple_ persistence
(Object/Relation mapping) layer. It's main design goals:
* Simple things should be easy to do. For example saving/deleting a Java object
  should be simple. Selecting should also be easy to write.
* It should not require any kind of generating, or code modification.
  I think generating/copying more than a few lines of code usually
  indicates bad design.
* It should not require any interaction with a database on lower level
  from the developer. As a developer I usually don't like databases
  which require me to tweak settings, install/create "tablespaces", adjust
  indexes, create tables, define rows, create "instances", etc. Other then
  performance tuning, why should I care about these things? All I want to 
  do is save an object, right? This generally is the most fundamental design 
  goal of the library.
* Selecting should be a bit easier and more readable than SQL. It also
  should use objects and not "tables", since we store objects. Also,
  this may mean the query language has not so many options/capabilities,
  but that's ok, if they are not needed most of the time.

That said, you can use this library if you are only manipulating objects,
and do not want to bother setting up complex tables and their interrelations.
In my experience, writing web applications usually requires saving
simple data structures, and querying in paged, ordered result sets. This
library does just that. 

Documentation
~~~~~~~~~~~~~

Hm... Well. Check the apidoc (generated with 'ant apidoc'), look at 
the test code under 'src/test'. There are 3 methods and an sql like
language to learn, so I guess that should do it.
Check the website for a tutorial: http://netmind.hu/persistence.

Building
~~~~~~~~

To build, copy your jdbc driver into the 'lib' directory, then

   $ ant

After that, you may edit the 'config/test.properties' file, to setup
your driver class and url for the tests. Then 

   $ ant test

to run the tests. If all test run correctly, you are ready to go. 

Requirements
~~~~~~~~~~~~

The library requires:

* Java 1.4 runtime
* JDBC driver/datasource (currently supported: Postgres)

To use the persistence library, you need the following jar files:

* log4j-1.2.8.jar (or any other post 1.2 log4j library)
* netmind-persistence.jar (this code)
* java-cup-11-runtime.jar (the lr parser runtime for the query language)