de.schwarzrot.data
Interface Entity

All Superinterfaces:

Comparable<Entity>, com.jgoodies.binding.beans.Observable, Serializable

All Known Subinterfaces:

ChildEntity<E>, MetaEntity<N>, NamedChildEntity<A,B>, NamedEntity<E>

All Known Implementing Classes:

AbstractConfigBase, AbstractEntity, AbstractEntityReference, AbstractMetaChildEntity, AbstractMetaEntity, AbstractSysConfig, AbstractWeightedEntityReference, ApplicationConfig, AttributeDomain, ColumnDefinition, DatabaseModel, DesktopConfig, DriveMapping, DSConfig, IdxSegmentInfo, IndexDefinition, ModellerConfig, Option, OptionBundle, PageProperties, SampleConfig, SchemaDefinition, ServiceConfig, ServiceDefinition, TableDefinition, User, WorkerConfig

public interface Entity
extends Comparable<Entity>, Serializable, com.jgoodies.binding.beans.Observable

Entity is the interface to bring persistence to business objects. As business objects should not contain any stuff tied to any persistence layer, but the persistencs layers needs some additional information for proper handling, the AbstractEntity will contain all that stuff.

As this frameworks main focus is the rich client application, every entity is a model for gui-handling by intention, so it will integrate to jgoodies forms or glazedlists or the like.

As we provide type overloading at persistence level, the meta-information is held in POJO instances and not in annotations. But ... this may subject of change some day.

Author:

Reinhard Mantey

See Also:

AbstractEntity

Method Summary

Long	getCModified() returns the number of modifications that happened to this instance.
List<SortInfo>	getDefaultOrder() returns a list of SortInfo, that build the order for default list-queries.
Date	getDtCreated() returns the timestamp when this instance was created
Date	getDtModified() returns the timestamp of the last saving operation.
Long	getId() returns the id of an Entity-instance.
Map<String,String>	getMappings() returns a map with mappings of logical property names to physical property names (column names in database terms).
String	getPersistenceName() returns the name of the entity for persistance.
String	getSchemaName() returns the schema for this entity.
Map<String,Integer>	getSkipList() returns a map with property names, that EntityManagers should ignore.
Class<?>	getSystemClass() return the classtype for system usage
String	getUCreated() returns the name of the user, that created this instance
String	getUModified() returns the name of the user, that triggered the last write operation for this instance.
List<String>	getUniqColumnNames() returns a list of property names, which serve to detect a uniq instance without the usage of the primary key.
List<String>	getUserAttributes() return a list of properties, that are user attributes.
String	getVariantColumnName() returns the name of the property that is used to distinguish Entity-variants.
Map<Object,String>	getVariantTypeMap() returns a map with the content of getVariantColumnName as key and fully qualified classnames as value.
boolean	isDirty() returns whether the instance contains changes not saved to persistence.
boolean	isUserType() returns true, if this entity is a usertype and false, if it is a system type
boolean	isVirtual() returns whether this class is virtual or real.
void	setCModified(Long modified) set's the number of modifications, that happened to this instance.
void	setDirty(boolean dirty) marks an instance as dirty, which means the instance has changes, not written to persistence yet.
void	setDtCreated(Date dtCreated) set's the timestamp of the moment, this instance was created.
void	setDtModified(Date dtModified) set's the timestamp of the last modification.
void	setId(Long id) set's the id of this instance.
void	setUCreated(String created) set's the name of the user, that created this instance.
void	setUModified(String modified) set's the name of the user, that performed the last modification of this instance.
void	validate(boolean read) will be called just before saving and after loading, so it is intended to give the opportunity to calculate virtual fields.

Methods inherited from interface java.lang.Comparable

compareTo

Methods inherited from interface com.jgoodies.binding.beans.Observable

addPropertyChangeListener, removePropertyChangeListener

Method Detail

getCModified

Long getCModified()

returns the number of modifications that happened to this instance.

Returns:

a modification counter

getDefaultOrder

List<SortInfo> getDefaultOrder()

returns a list of SortInfo, that build the order for default list-queries.

Returns:

a list of property names

getDtCreated

Date getDtCreated()

returns the timestamp when this instance was created

Returns:

a timestamp

getDtModified

Date getDtModified()

returns the timestamp of the last saving operation.

Returns:

a timestamp

getId

Long getId()

returns the id of an Entity-instance. Normally the id are the primary key for the instances in persistence layer.

Returns:

the id of an instance

getMappings

Map<String,String> getMappings()

returns a map with mappings of logical property names to physical property names (column names in database terms).

Every implementation should respect the parents mappings. The following sample shows different mapping types:

 public Map<String, String> getMappings() {
     Map<String, String> mappings = super.getMappings();
     mappings.put("title", "name");
     mappings.put("streams", Stream.class.getName());
     mappings.put("pageDefinitions", "pageType|" + ThemeElement.class.getName());
     return mappings;
 }
 

The mappings explained:

"title" -> "name"

the logical "title"-attribute is stored to persistence with a physical name "name"

"streams" -> Stream.class.getName()

the "streams" property holds related children. Unknown children are hold in a List, known (named) children are hold in a Map. The mapped value is used as classname to create child instances.

"pageDefinitions" -> "pageType|" + ThemeElement.class.getName()

pageDefinitions is a property of type Map, that holds grouped children. Known children are hold by a Map, unknown children by a List, so "pageDefinitions" may contain elements of type Map, or List. pageType, a property of ThemeElement, is used to group the children. The word before the '|' is the property name used as key value for grouping and the type after '|' is used to create instances.

Returns:

a Map with property names as keys and column names as values.

getPersistenceName

String getPersistenceName()

returns the name of the entity for persistance. Normally it would be the same result as getClass().getSimpleName(), but some storage may have size limitations, or don't support case sensitive names, so this call is to deal with that kind of limitations.

Returns:

the entity-name used for persistence

getSchemaName

String getSchemaName()

returns the schema for this entity. Not all storage types support schemata, so on systems, where the schema is not supported, it will be a prefix to the persistent name.

Returns:

a schema name

getSkipList

Map<String,Integer> getSkipList()

returns a map with property names, that EntityManagers should ignore. These properties may be virtual properties, that not should be saved to persistence and/or methods that start with 'get' and that are not getters.

Implemention uses HashMaps for performance reasons, but the values are never used. So the map consists of propertynames as keys and an Integer as Value.

Every implementation should use the Map from parent class:

 public Map<String, Integer> getSkipList() {
     Map<String, Integer> skipList = super.getSkipList();
     skipList.put("a_virtual_field", 1);
     return skipList;
 }
 

Returns:

a Map

getSystemClass

Class<?> getSystemClass()

return the classtype for system usage

Returns:

a class

getUCreated

String getUCreated()

returns the name of the user, that created this instance

Returns:

a username

getUModified

String getUModified()

returns the name of the user, that triggered the last write operation for this instance.

Returns:

a username

getUniqColumnNames

List<String> getUniqColumnNames()

returns a list of property names, which serve to detect a uniq instance without the usage of the primary key. In database context this list is used to decide, whether a save operation needs an update or an insert.

Returns:

a list of property names

getUserAttributes

List<String> getUserAttributes()

return a list of properties, that are user attributes. Default is to return null to signal, that all properties are user attributes. In case this entity is a system entity, there may exists attributes, that may be overridded by users. So return a list of those attributes.

Returns:

a list of property names

getVariantColumnName

String getVariantColumnName()

returns the name of the property that is used to distinguish Entity-variants. This is neede, if several entities share the same storage, so the real classname has to be determined by a stored value.

Returns:

the name of a property

getVariantTypeMap

Map<Object,String> getVariantTypeMap()

returns a map with the content of getVariantColumnName as key and fully qualified classnames as value.

There are 2 types of polymorphism supported:

known children

all derived types are known and not expected to increase. In this case a shortcut could be saved to persistence which gets resolved by this map.

unknown children

the type system is open for user expansion. In this case the returned map must be null and the content of the getVariantColumnName must hold the canonical class name of the java classes.

Example (for known children): suppose a table animals that should hold entities Cat and Dog. The class Animal will overload the method getPersistenceName, wich returns "animal". Additionally it will declare an Enum as

 Enum Animal { 
  CAT,
  DOG
 };
 

as well as a property animalType of type Animal. The constructor of Cat initializes the property animalType with CAT, the constructor of Dog initializes the property animalType with DOG. The variantTypeMap returned will then look like:

 Map<Animal, String> variantTypeMap = new HashMap<Animal, String>();
 
 variantTypeMap.put(CAT, Cat.class.getName());
 variantTypeMap.put(DOG, Dog.class.getName());
 

Example (for known children): if the sample from above should support more animals, even those unknown at time of writing, getVariantTypeMap() should return null . The content of column animalType should then match Cat.class.getName() instead of just Cat.

Returns:

a map with values of getVariantColumnName as key and fully qualified classnames as value, or null for unknown child types.

isDirty

boolean isDirty()

returns whether the instance contains changes not saved to persistence.

Returns:

boolean

isUserType

boolean isUserType()

returns true, if this entity is a usertype and false, if it is a system type

Returns:

true or false

isVirtual

boolean isVirtual()

returns whether this class is virtual or real.

When you have a table, that should contain animals and you implent classes for each animal type, you don't want that instances of class Animal should exists. Normally you would make such a class abstract, but this is forbidden for beans and so for entities! This method signals the EntityManager that Animal is not the type of the entity. Instead it has to be determined by the loaded content.

Returns:

true for virtual (abstract) classes, default false

setCModified

void setCModified(Long modified)

set's the number of modifications, that happened to this instance.
This method should be considered internal!.

Parameters:

modified - the new modification counter

setDirty

void setDirty(boolean dirty)

marks an instance as dirty, which means the instance has changes, not written to persistence yet. Each setter should observe the changes and mark the instance as dirty as necessary.

Parameters:

dirty - - true if instance has unsafed changes

See Also:

AbstractEntity

setDtCreated

void setDtCreated(Date dtCreated)

set's the timestamp of the moment, this instance was created.
This method should be considered internal!.

Parameters:

dtCreated - a timestamp

setDtModified

void setDtModified(Date dtModified)

set's the timestamp of the last modification.
This method should be considered internal!.

Parameters:

dtModified - a timestamp

setId

void setId(Long id)

set's the id of this instance. From application point of view, this should NOT occure, but on reading from persistence, it must be set.
So this method should be considered internal!.

Parameters:

id - the id for this instance

setUCreated

void setUCreated(String created)

set's the name of the user, that created this instance.
This method should be considered internal!.

Parameters:

created - a username

setUModified

void setUModified(String modified)

set's the name of the user, that performed the last modification of this instance.
This method should be considered internal!.

Parameters:

modified - a username

validate

void validate(boolean read)

will be called just before saving and after loading, so it is intended to give the opportunity to calculate virtual fields.

Parameters:

read - signals whether calculation should be done for reading or for writing