Package uk.ac.ed.epcc.webapp.model.data

This package implements the data layer that connects the SQL database with the Java model.

See: Description

Interface Summary

Interface	Description
CloseableIterator<E>	A combination of AutoCloseable and Iterator This allows an iterator that encapsulates a chunking SQL operation.
Composable	A marker for a stand alone interface that can be implemented directly or via a composite.
ConfigParamProvider	Interface for classes/composites that register the Configuration parameters they use.
DataObjectSelector<B extends DataObject>
FieldConstraint	Interface for form constraints that restrict values of a field based on the values in other fields.
FieldSQLExpression<T,X>	A FieldValue that is also a SQLExpression
FieldValue<T,X>	SQLAccessor that represents a field in the DataBase
FilterResult<D>	Interface for containers that hold Filter results Normally a FilterSet produced by the factory.
IndexedLinkManager.LinkProvider<T extends IndexedLinkManager.Link<L,R>,L extends Indexed,R extends Indexed>
LinkComposite<L extends IndexedLinkManager.Link>	An interface for Composites that wish to take part in a IndexedLinkManager.Link.setup() operation The implementing Link class must explicitly look for composites that implement this interface in its IndexedLinkManager.Link.setup() method.
NamedFilterProvider<T>	Interface for classes (Normally DataObjectFactorys or Composites) that can generate named filters.
Owned	Interface for DataObjects that can directly retrieve their factory.
Owner<D>	Interface for factory classes.
Releasable
Removable	Interface for DataObjects that can be removed from a DataObjectFactory.FilterIterator Classes that implement this should therefore have a well defined iteration order that won't per permuted if elements from the start of the sequence are removed.
RestrictedRetirable	Interface for retire operations with restricted access.
Retirable	Interface for DataObjects that support a Retire action
SelectModifier<T>	An interface for Composites that can narrow the select filter
TableStructureContributer<BDO extends DataObject>	An interface for objects that contribute fields etc.
UnRetirable	Interface for Retirable objects where this can be reversed.
UpdateContributor<BDO extends DataObject>	Interface for Composites that need pre-commit access on update

Class Summary

Class	Description
AbstractFilterResult<D>
AbstractSelfSQLValue<T extends DataObject,R>	Field value for a self reference It targets the primary key of the factory.
BasicType<T extends BasicType.Value>	BasicType A base class for building type-safe enumeration classes for use as Status and type fields for BasicDataObject sub-classes.
BasicType.Value	Value inner class representing a possible value of the enclosing BasicType.
BooleanFieldExpression<X extends DataObject>
CachedIndexedProducer<T extends Indexed>	Decorator around a IndexProducer that caches values.
ClassType<T extends ClassType.ClassValue<D>,D extends DataObject>	A variant of BasicType for fields that encode the sub-class in a multi-class factory
ClassType.ClassValue<S extends DataObject>
Composite<BDO extends DataObject,X>	A Composite adds behaviour to a DataObjectFactory by composition but persisted to the same database table.
ConfigTransition<T extends DataObjectFactory>
ConstIndexedSQLValue<T extends DataObject,I extends DataObject>	a IndexedSQLValue that resolves to a constant value.
CounterDistinctMapper<T>	A ResultMapper that returns the number of matching records
CounterMapper	A ResultMapper that returns the number of matching records
CreateAction<BDO extends DataObject>	FormAction class to create the target DataObject from a form This class needs access to package level methods from DataObjectFactory.
CreateComposite<BDO extends DataObject,X extends Composite>	abstract superclass for Composites that implement CreateCustomizer
DatabaseUpgrader	A Command to upgrade the current database.
DataCache<K,V>	DataCache implements caches round queries that will be repeated multiple times, e.g.
DataObject	DataObject is the application facing view of a row in a database table.
DataObjectFactory<BDO extends DataObject>	Factory object for producing DataObjects.
DataObjectFactory.TimeAcceptFilter<T extends DataObject>
DataObjectFormFactory<BDO extends DataObject>	Base class for Forms based on DataObject fields such as create/update forms.
DateFieldExpression<X extends DataObject>	A FieldExpression for a SQL date field.
DiffParser	A DumpParser parses a baseline dump of a database and compares it with the current database state via calls to Dumper#dumpDiff(Record, Record) on an enclosed Dumper.
Dumper	Class to dump DataObjects to files.
DumpParser	A ContentHandler that parses an XML data specification created by the Dumper class The default mode is to try and reproduce the ids present in the dump.
Duration	A class to represent durations of time.
DurationFieldValue<X extends DataObject>	A wrapper that converts a NumberFieldExpression into an SQLAccessor for a Duration with a configurable resolution.
EditTableTransition<T extends DataObjectFactory>
ExistsMapper	A ResultMapper that generates a boolean true/false if the filter matches anything
FieldExpression<T,X extends DataObject>	Abstract class for SQL fields that can be used in expressions.
FieldValueFilter<V,T>	A filter that matches (exactly) a value using a FieldValue Normally FieldValues are either FieldSQLExpressions or FilterProviders but this will work in the remaining cases e.g.
FieldValuePatternArgument<T,X>	A PatternArg corresponding to a constant value for a FieldValue
IndexedFieldValue<T extends DataObject,I extends DataObject>	A SQLAccessor for a field referencing a remote table.
IndexedLinkManager<T extends IndexedLinkManager.Link<L,R>,L extends Indexed,R extends Indexed>	IndexedLinkManager is the base class of Factories that manage Link objects These classes manage many-to-one relationships between model level objects.
IndexedLinkManager.Link<L extends Indexed,R extends Indexed>	Link is an object representing an entry in a linkage table.
LinkManager<T extends LinkManager.Link<L,R>,L extends DataObject,R extends DataObject>	LinkManager is the base class of Factories that manage Link objects These classes manage many-to-one relationships between model level objects.
LinkManager.Link<L extends DataObject,R extends DataObject>	Link is an object representing an entry in a linkage table.
LockedDataCache<BDO extends DataObject>	A DataCache that wraps an arbitrary DataObjectFactory and always returns locked objects.
MultiComposite<BDO extends DataObject,X extends Composite<BDO,X>>	An abstract base class for a Composite that combines multiple Composites of the same type.
MultiFieldConstraint	A composite FieldConstraint.
MultiLinkManager<M extends MultiLinkManager.MultiLink>	MultiLinkManager is a superclass for handling Linkage objects that link multiple tables.
MultiLinkManager.MultiLink
NamedFilterWrapper<T extends DataObject>	A wrapper for resolving named filters from a DataObjectFactory.
NullIterator<E>	An always empty CloseableIterator
NumberFieldExpression<T extends java.lang.Number,X extends DataObject>	A FieldExpression for Number values.
OrphanReferenceFilter<T extends DataObject,BDO extends DataObject>
PatternArg	Class encoding the arguments for a PatternFilter
RangeSearch<D extends DataObject>	Search for an integer id from a range which is not allocated to any record from a table.
RangeSearch.Info
ReferenceAcceptFilter<R extends Indexed,T extends DataObject>	An AcceptFilter version of ReferenceFilter
ReferenceFilter<BDO extends DataObject,R extends Indexed>	Generic SQL filter for selecting records using a peer Object that implements Indexed referenced from a integer field.
Relinker	Class for relinking references.
RemoteAcceptFilter<T extends DataObject,R extends DataObject>	An AcceptFilter version of a Joiner If you need a remote filter which is not known to be a AcceptFilter use DataObjectFactory.getRemoteFilter(DataObjectFactory, String, BaseFilter) as this uses a visitor to produce an optimised implementation strategy
RemoteAccessRoleProvider<U extends AppUser,T extends DataObject,R extends DataObject>	A wrapper round a DataObjectFactory that forwards role relationships from a remote object The AppUser has the role with the target object if the user has the same named role with the remote object the target references.
Repository	Repository encapsulates a Database table.
SelfIdExpression	A SQLExpression for the unique id field.
SelfSQLValue<T extends DataObject>	SQLValue of a Reference to the current record
SetMapper<O>
SimpleClassType<T extends SimpleClassType.ClassValue,O>	Varient of BasicType where the field is used to specify the class of a java object included in the DataObject by composition.
SimpleClassType.ClassValue<S>
SpecificationBuilder	class to guess table specifications based on a existing Repository.
StateRelationshipComposite<U extends AppUser,BDO extends DataObject,X extends StateRelationshipComposite>	A Composite that adds boolean field to an object.
StreamDataFieldExpression<X extends DataObject>
StringFieldExpression<X extends DataObject>
TableDescription	Class to show database info about a Repository
TableUnDumper	An UnDumper that just restores tables.
TimestampDateFieldExpression<T extends DataObject>	FieldExpression that views a numeric field as a date timestamp
TupleFactory<A extends DataObject,AF extends DataObjectFactory<A>,T extends TupleFactory.Tuple<A>>	Factory for sets of DataObjects generated by a join.
TupleFactory.Tuple<A extends DataObject>
TupleSelfSQLValue<A extends DataObject,AF extends DataObjectFactory<A>,T extends TupleFactory.Tuple<A>>	A SQLValue to reference a component of a TupleFactory.Tuple
TypeProducerFieldValue<T extends DataObject,O,D>	A SQLAccessor for a field with a TypeProducer This accessor returns the produced object.
UnDumper	A DumpParser that parses an XML data specification created by the Dumper class and creates the corresponding database state.
ValueFilter<BDO extends DataObject>	A version of SQLValueFilter specifically for DataObjectFactorys It is a good idea to subclass again so as to improve type safety and hide the field name.
XMLDataUtils	This class provides common boilerplate code for the loading and creation of XML data dumps.

Enum Summary

Enum	Description
Repository.IdMode	modes supported by Repository.Record.setID(int)

Package uk.ac.ed.epcc.webapp.model.data Description

This package implements the data layer that connects the SQL database with the Java model.

As far as is reasonably possible we try to encapsulate any dependency on the JDBC classes within this package. We also aim to concentrate the appearance of SQL fragments to be only within this package as much as is reasonably practical. Though it is very unlikely that we will ever want to move away from using JDBC for data persistence this encapsulation makes it easier for us to refactor the implementation. Database tables and records are abstracted into the Repository and Repository.Record classes Select conditions are abstracted into the classes and interfaces in the uk.ac.ed.epcc.webapp.jdbc.filter package.

The data model is that every database table has a corresponding Java class. Instances of these classes correspond to rows in the database.

At lowest level of the API are the Repository and Repository.Record classes. These are final classes that represent a database table and a table record respectively. This package also contains the abstract DataObject and DataObjectFactory classes. These classes are sub-classed to produce the table specific model classes.

There is a very close parallel between Repository/Record and DataObjectFactory/DataObject. The first are Database facing final classes providing an abstraction layer above JDBC. The second are application facing abstract classes that are subclassed to provide customised classes for individual database tables, containing internal references to the the appropriate Repository/Record objects. This two level approach allows a great deal of flexibility to refactor the domain objects without requiring a corresponding reformat of the database schema. It also allows a greater separation of concerns.

The DataObjectFactory class implements methods for extracting sets of multiple database entries. We use a Factory class rather than static methods because this allows us to inherit common factory code and add additional behaviour suitable to particular domain objects.

In many cases the factory and the target class are independent classes (we often keep one as a static inner class of the other to keep them associated). Where the Objects are more likely to be implemented as Sets of objects rather than individuals we can make the DataObject an inner class (or pseudo-inner class) of the Factory see LinkManager and HistoryFactory.

The classes in uk.ac.ed.epcc.model.data.forms provide an interface for building user interface forms. These can be used to easily construct interface forms. Though most modifications to model state come via custom application logic, two very common operations are to create and to modify individual domain objects. This is particularly important as part of the application management functions. The DataObjectFormFactory class contains code to produce creation and update forms for a DataObject based on the SQL schema. This class is sub-classed to produce Creator and Updater which implements the default create/update logic. Individual model classes may sub-class these to customise the behaviour. We also want to be able to set class-specific defaults for both the create and update forms. This is implemented by having the default methods in DataObjectFormFactory call methods in the DataObjectFactory. Originally this functionality was implemented directly in the DataObjectFactory but the forms code was considered to be a sufficiently distinct responsibility to merit its own class.

There are many different frameworks available for doing database persistence of Java objects. This particular scheme is database centric in that much of the behaviour of the object is driven by the Database schema rather than in the source of the object. For example if an additional field is added to a table additional fields will appear in the form used to create that object. A text field that can be null in the database can be left blank in a form. The API of Repository.Record allows DataObjects to access a database field if it exists and to pick up a default value if it does not.