Package com.revusky.niggle.data

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

See:
          Description

Interface Summary
DataListener The interface implemented by objects that listen to data-related events thrown by instances of com.revusky.niggle.data.MutableDataSource.
DataRegistry The interface implemented by objects that vend "virgin" instances of a Record.
DataSource a marker interface representing objects that contain a set of Records indexed by a lookup key
FieldDescriptor An interface implemented by objects that describe the constraints on the field of a niggle data record.
MutableDataSource Interface implemented by objects that manage a collection of records.
Record An interface that describes the canonical methods of a data record in the niggle framework.
RecordDescriptor A metadata object that describes what is in a record.
RecordFilter An interface for objects that can filter a set of records based on some criterion.
Session Interface that represents a session
ValidatingRecordInput A marker interface that indicates that records should be validated as they are read in.
 

Class Summary
AbstractDataSource A convenient base class for DataSource implementations.
AbstractMutableDataSource A convenient base class for MutableDataSource implementations.
AntiRecord An AntiRecord is to a regular record like Anti-matter is to matter.
DataEvent An event that encapsulates something happening in a MutableDataSource -- the insertion, deletion or updating of a record
DataRegistryImpl This object plays a central role in the niggle framework.
DataUtil a holder for various useful static routines dealing with niggle data
DefaultRecord A concrete implementation of the Record interface In this implementation, the records can be written out as a human-readable string.
DefaultRecordInputStream An implementation of the ObjectInput interface for slurping Records off a stream in their default flat-file format, which is not the standard Java serialised object format.
DefaultRecordOutputStream An implementation of ObjectOutput for spitting out niggle records onto a stream in their default flat-file format.
RecordFilter.ClassConstraint  
RecordFilter.FieldConstraint  
RecordFilter.IntersectionFilter  
RecordFilter.NegationFilter  
RecordFilter.NullFilter  
RecordFilter.TypeConstraint  
RecordFilter.UnionFilter  
RecordReference An object that represents a weak or soft reference to an underlying Record object.
 

Exception Summary
DataException The base exception for niggle data.
DuplicateRecordException A DataException that indicates that there has been an attempt to insert a new record with a primary key that is already taken.
ImmutableDataException thrown when an attempt is made to modify data in an immutable data record.
InvalidDataException thrown when there is an attempt to set data in some invalid way.
InvalidFieldException thrown when there is an attempt to access data from a record via a field that does not belong to that record.
MangledDataException Thrown when there is an attempt to put a value in a record's fields that does not match the metadata description, e.g. alpha in numeric field, value out of range.
MissingDataException Thrown when an attempt is made to initialize a record which is missing a required field.
MissingRecordException Thrown when a client tries to modify a record that has already been deleted.
ModifiedRecordException Thrown when a client tries to modify a record that was modified by another process since it was requested from a data source.
UnknownRecordTypeException exception thrown when an customized object input stream encounters a record type that it doesn't know about.
 

Package com.revusky.niggle.data Description

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 Record, which is basically analogous to a row in relational database table. A Niggle record, vended by a 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 DataRegistry object. When you attempt to insert a mutable record in a 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 set routines will cause an ImmutableDataException to be thrown. Any record vended by an instance of 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 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.

Author:
Jonathan Revusky
See Also:
com.revusky.niggle.data.inmemory, com.revusky.niggle.data.jdbc, com.revusky.niggle.data.metadata