Package de.schwarzrot.data

provides the basic classes and interfaces for anonymous persistence.

See:
Description

Interface Summary

ChildEntity<E extends Entity>	interface for all children types, that means for entities, that model a 1:n relation and which need to keep the id of the parent instance.
Entity	Entity is the interface to bring persistence to business objects.
EntityReference<A extends Entity,B extends Entity>	reference handle class to handle anonymous references.
NamedChildEntity<A,B extends Entity>	is an NamedEntity and a ChildEntity.
NamedEntity<E>	interface for all entities, that could be identified by their name.
VdrEntity	interface to mark an Entity as being attached to the VDR
WeightedEntityReference<A extends Entity,B extends Entity,T>	interface for anonymous references, that need to be sorted

Class Summary

ResourceNode

TreeNode implementation to build a tree from help pages.

Package de.schwarzrot.data Description

provides the basic classes and interfaces for anonymous persistence. This is the data-part of the anonymous Persistence layer.

Requirements for the persistence layer

• strong separation of persistence code from application
• application should only use calls like find or save without having to care about used relations or the type of persistence
• persistence should be flexible and extensible, even at runtime
• I didn't want the application developer having to care about persistence code (i.e. SQL)
• and the biggest one: I only wanted one source for a business class

Design decisions

The last requirement leaded to a baseclass for all business classes, as they are involved in user interactions (so they need to be a Model ), they may be sent across the network, so they need to be serializable and of cause, they should contain enuf information, that a workflow from one storage over transmission between different VMs into a quite different storage should work.

Entity is the interface, that all business classes should derive from and AbstractEntity is the base implementation to cutoff all the grunt work from business classes. I decided to use the model from jgoodies binding, so the jgoodies forms library could be used to ease the creation of nifty user interfaces.

Every business class must provide a public default constructor (like any bean should do). This is needed for the extended reflection.

See de.schwarzrot.data.access for the worker part of Persistence layer.

Reference resolution

Most references are solved by contract from the persistence layer:

direct relationship (1:1 in database terms)

A direct relationship is given, if one Entity has a property of (sub)type Entity.

Child - relationship (1:n in database terms)

A child relationship is true, when the child contains information about its parent and the parent knows a bunch of children. So a child can have one parent and a parent can have several children, but each of them may be related only once.
The persistence layer differs two kinds of children:

• named children - the parent has a property Map<Object, NamedChildEntity>, where the key of the map is the result of namedChild.getName(). NamedChildEntity is parameterizable, so the return type of getName() could be specified with generics.

  The Map returned by getMappings() must contain an entry like:

   myMappings.put("children", YourChildEntity.class.getName());
   

  That's all, what needs to be done by the application developer to implement a named child relation

• unnamed children. - the parent has a property List<ChildEntity> and the Map returned by getMappings() must contain an entry like:

   myMappings.put("children", YourChildEntity.class.getName());
   

Sometimes it is necessary, to group children. In this case, the parent's children property will always be a Map, with the grouping value as key. Named children will be grouped by Map<GroupClass, Map<NameClass, NamedChildrenClass>>, unnamed children will be grouped by Map<GroupClass, List<ChildClass>>. To enable the persistence layer to support grouped children, the parent's Map returned by getMappings() needs an entry like:

 myMappings.put("children", "groupingPropertyName|" + GroupedChildrenClass.class.getName());
 

See de.schwarzrot.data.test.domain for basic implementations.

anonymous - relationship (n:m in database terms)

In this relationship, no entity has a direct link to the related entity. In database terms, this relation is build by an intermediate table, that holds the primary keys of the related table-entries. As quite often, this kind of relationship holds properties valid for given relation only, I decided to use intermediate objects too - EntityReference is the base class for the anonymous relationship and WeightedEntityReference the base class, for sorted relations. Implementation of both reference types must also be an Entity.

Implementation of business objects is quite the same, as with named/unnamed children. The master- Entity has a property Map<Object, EntityReference> to hold the related instances, where reference.getWeight() is the key for the Map. Unsorted references can be hold in a property List<EntityReference>.

Internals

persistence introduced the desire in statistics, so some basic properties are required for all entities. The application-developer may use them, but need not care about them. The EntityHandler will do that.

Other informational Entity-methods needed to deal with persistence:

getPersistenceName

not all storage systems support case sensitive name handling, others may have size restrictions, so this is a way to bring a different name into the play

getSchemaName

not all storage systems support schemata. To allow different catalogs in the same storage, the schema name is used as schema name on systems that support schemas, on other systems it is used as a prefix for the persistence name.

getDefaultOrder

if instances of this entity should be sorted by default, this call returns a list of properties to sort the instances by.

getMappings

in case that a property needs a different name in storage systems, or types of children have to be specified

getSkipList

virtual properties and/or functions with 'get'-prefix that are not getters need to get hidden for generic processing.

isUserType

specifies, whether a user may change and save this entity. It's up to the EntityManager to respect this call. Don't rely upon all EntityManagers doing so.

getUserAttributes

entities, where isUserType() returns false may specify properties, that a user is allowed to change and save

getUniqColumnNames

At saving time, it must be asured, that instances that are intended of being uniq don't get duplicated, so this method returns a list of properties, that make an instance uniq. The id-property must not be part of that list.

isVirtual

if one database table should contain data from different classes, this function must return true

The persistence layer supports two types of virtualization:

• closed virtualization. The closed virtualization means, all possible classes for given table are known at compile time, so this could be realized with an Enum-Class-mapping ( getVariantTypeMap()). Sample for closed virtualization is de.schwarzrot.rec.domain.Stream.

• open virtualization. The open virtualization is used, when the range of classes are not known at compile time, or when a table is intended to be extended at runtime. That cases are realized by storing the fully qualified classname in the table. A non-trivial sample for open virtualization is de.schwarzrot.dvd.theme.domain.ThemeBase.

getVariantTypeMap

If several classes share the same database table, the type of a row needs to be determined from the contained data. This map is used to match a key field to a classname.