The base Oreo API's that abstract away your web app's interaction with externally configured data sources and data records. For more information on how to do the XML configuration, see these additional notes.

Oreo provides an object-oriented layer on top of your persistent application data. This API assumes that your data live in an external persistent data source, such as an RDBMS. The core construct is a {@link com.revusky.oreo.Record Record}, which is basically analogous to a row in relational database table. An Oreo record, vended by a {@link com.revusky.oreo.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.oreo.DataRegistry DataRegistry object}. When you attempt to insert a mutable record in a {@link com.revusky.oreo.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.oreo.Record#set(java.lang.String, java.lang.Object) set} routines will cause an {@link com.revusky.oreo.ImmutableDataException ImmutableDataException} to be thrown. Any record vended by an instance of {@link com.revusky.oreo.DataSource com.revusky.oreo.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.oreo.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.oreo.inmemory @see com.revusky.oreo.jdbc @see com.revusky.oreo.metadata @author Jonathan Revusky