Chapter 4. Basic Persistence
Prev	Part III. Persistence Layer	Next

Basic Persistence

Table of Contents

Object Initialization
Listing objects and sorting lists

The persistence layer of the CDM primarily consists of a set of data access objects (DAOs). These DAOs are generic, strongly typed, and form a hierachy that reflects the inheritance of the data entities that they provide access too. The root DAO implements ICdmEntityDao.

Table 4.1. ICdmEntityDao methods

Method	Description
`UUID saveOrUpdate(T newOrTransientEntity);`	Makes a new object persistent, or persists the state of a transient object.
`Map<UUID,T> save(Collection<T> newEntities);`	Makes a collection of new objects persistent.
`UUID save(T newEntity);`	Makes a new object persistent.
`UUID update(T newEntity);`	Makes changes to a transient object persistent.
`UUID merge(T newEntity);`	Merges the state of a detached object into the persisted version.
`UUID delete(T persistentEntity);`	Deletes a persistent object.
`List<T> list(Class<? extends T> clazz, Integer limit, Integer start, List<OrderHint> orderHints, List<String> propertyPaths);`	Returns a (sub-)list of objects matching the type `clazz`, sorted according to the order hints and initialized according to the propertyPaths.
`int count(Class<? extends T> clazz);`	Returns a count of objects matching the type `clazz`.
`T find(UUID uuid);`	Returns an object of type T matching the supplied uuid if it exists.
`Collection<T> find(Collection<UUID> uuids);`	Returns a collection of objects of type T matching the uuids supplied, if they exist.
`T load(UUID uuid, Collection<String> propertyPaths);`	Returns an object of type T with properties initialized according to the rules described below.
`Set<T> load(Collection<UUID> uuids, Collection<String> propertyPaths);`	Returns a collection of objects of type T matching the uuids supplied, if they exist, initialized according to the rules described below.
`boolean exists(UUID uuid);`	Returns true if there is an object of type T in the database matching the supplied uuid.
`Class<T> getType();`	Returns the class of objects that this DAO provides access to.

Figure 4.1. An overview of the cdm persistence layer

The DAO hierarchy in the CDM persistence layer. Data Access Objects are strongly typed and their hierarchy follows the hierarchy of major entities in the CDM.

Object Initialization

DAO methods that return objects, return entities without any relationships initialized by default (to learn more about initialization of related entities, lazy-loading etc, please consult the hibernate documentation). Because some applications (particularly stateless multi-user applications with concise units of work i.e. web applications), may wish to limit the length of transactions, it is important to be able to explicitly initialize related entities according to the particular use-case. The CDM library allows application developers to do this on a per-method call basis.

Properties of the root object specified using java-beans-like syntax and passed using the propertyPaths parameter will be initialialised before the object(s) are returned and can safely used. Applications that access other properties (that are part of related entities) outside of the transaction in which the entity was retrieved (i.e. the entity is detached) are likely to throw a LazyInitializationException. In addition to specifying properties by name, developers can also use an asterisk (*) to represent all *-to-many properties, and a dollar sign ($) to represent all *-to-one properties of the root entity or a related entity. Using a wildcard terminates the property path (i.e. it is not valid syntax to include characters after a wildcard in a propertyPath expression - the wildcard must be the final character in the string).

Listing objects and sorting lists

In addition to allowing single objects and collections of objects matching specific UUIDs to be returned, the GenericDAO also allows lists of objects of type T to be returned (to allow browsing of the entire collection of entities, for example). In many cases, applications will wish to restrict the total number of objects returned to a subset of the total available objects (to reduce resource requirements, or increase speed of rendering of a response, for example). This can be achieved by supplying non-null limit and start parameters to restrict the total number of objects returned. These parameters are analogous to the "limit" and "offset" parameters in SQL and are zero-based (i.e. the first result is 0, not 1).

Lists of objects are returned sorted according to the orderHints parameter. Like the propertyPaths parameter, OrderHint objects take a java-beans-style string that indicates the property or related entity that the list of returned objects should be ordered by, and a SortOrder that determined whether the list is sorted in ascending or descending order.