The base Niggle API's that abstract away your web app's interaction with externally configured datasources.

Niggle provides an object-oriented layer on top of your persistent application data. This API assumes that your data live in an external data source, such as an RDBMS. The core construct is a {@link com.revusky.niggle.data.Record Record}, which is basically analogous to a row in relational database table. A Niggle record, vended by a {@link com.revusky.niggle.data.DataSource DataSource} instance, is an immutable set of key=value pairs. The immutability semantics exist to guarantee thread safety and data validity.

A newly created Record, however, is mutable. One can create a new one by cloning an existing record or it can be vended by the singleton {@link com.revusky.niggle.data.DataRegistry DataRegistry object}. When you attempt to insert a mutable record in a {@link com.revusky.niggle.data.MutableDataSource MutableDataSource}, the DataSource object will attempt to validate it, and if that is successful, the record is frozen, i.e. made immutable. After that point, attempts to call the {@link com.revusky.niggle.data.Record#set(java.lang.String, java.lang.Object) set} routines will cause an {@link com.revusky.niggle.data.ImmutableDataException ImmutableDataException} to be thrown. Any record vended by an instance of {@link com.revusky.niggle.data.DataSource com.revusky.niggle.data.DataSource} will be in an immutable state. Since the record data is validated against externally specified constraints as a condition of being inserted in a DataSource container, and after that, it is immutable, this means that we have pretty much an iron-clad guarantee about the validity of data in a Record that is vended by a DataSource. It also frees us from typical synchronization worries, since the immutable data cannot be modified out from under us by another thread.

Every type of Record has associated with it a {@link com.revusky.niggle.data.RecordDescriptor RecordDescriptor} instance that encapsulates the metadata that is externally specified in XML. This will typically tell us what kinds of objects are in the fields and what constraints they must satisfy -- for example that it is an integer between 0 and 100, or a string of at most 20 characters. This is the metadata against which a record is validated.

@see com.revusky.niggle.data.inmemory @see com.revusky.niggle.data.jdbc @see com.revusky.niggle.data.metadata @author Jonathan Revusky