net.java.ao

Interface RawEntity<T>

All Known Subinterfaces:

Entity

public interface RawEntity<T>

The superinterface for all entities, regardless of primary key. Developers may choose to extend this interface rather than Entity if they need to specify a custom primary key field. As this interface is the most generic superinterface in the entity hierarchy, it defines most of the common entity methods, such as save() and addPropertyChangeListener(PropertyChangeListener).

This interface is parameterized for the sake of typechecking in the EntityManager.find(Class, String, Object...) method. The generic type specified when inheriting this interface should be the same as the return type of the primary key method. Unfortunately, this is unenforcable, so it is left up to the developers to ensure the spec is followed.

Author:

Daniel Spiewak

Method Summary

Modifier and Type	Method and Description
void	addPropertyChangeListener(java.beans.PropertyChangeListener listener) Adds a property change listener to the entity.
EntityManager	getEntityManager() Retrieves the EntityManager instance which manages this entity.
<X extends RawEntity<T>> java.lang.Class<X>	getEntityType() Returns the actual Class instance which corresponds to the original entity interface.
void	init() Called when the entity instance is created.
void	removePropertyChangeListener(java.beans.PropertyChangeListener listener) Removes a property change listener from the entity.
void	save() Saves all changed (dirty) fields within the entity to the database.

Method Detail

init

void init()

Called when the entity instance is created. This method is defined here in order to provide a common interface through an existing mechanism. It is designed to be implemented within an entity defined implementation. Any calls to this method will be ignored by AO unless a defined implementation is present.

save

void save()

Saves all changed (dirty) fields within the entity to the database. This method should almost never be overridden within a defined implementation. However, it is possible to do so if absolutely necessary.

getEntityManager

EntityManager getEntityManager()

Retrieves the EntityManager instance which manages this entity. This method can be used by defined implementations to get the relevant EntityManager instance in order to run custom queries.

Returns:

The instance which manages this entity.

getEntityType

<X extends RawEntity<T>> java.lang.Class<X> getEntityType()

Returns the actual Class instance which corresponds to the original entity interface. This is necessary because calling Object.getClass() on a proxy instance doesn't return the value one would expect. As such, RawEntity provides this method to give developers access to the originating entity interface. Example:

public interface Person extends Entity {
     // ...
 }

 // ...
 Person p = manager.get(Person.class, 2);
 p.getEntityType();         // returns Person.class
 p.getClass();           // indeterminate return value, probably something like $Proxy26.class

Returns:

The Class which defines the entity in question.

addPropertyChangeListener

void addPropertyChangeListener(java.beans.PropertyChangeListener listener)

Adds a property change listener to the entity. This method is included partly to emphasize compliance with the bean spec (sort of), but more to enable developers to register listeners on the setters. This method is called when the setter is called, not when save() is invoked.

Be aware that the PropertyChangeEvent may or may not have a valid oldValue. This is because retrieving a previous value under many circumstances may result in an extra database SELECT. If no oldValue is available in memory, null will be passed.

Any trivial custom code which only needs to run on mutator invocation should use property change listeners, rather than a defined implementation.

Parameters:

listener - The change listener to add.

removePropertyChangeListener

void removePropertyChangeListener(java.beans.PropertyChangeListener listener)

Removes a property change listener from the entity.

Parameters:

listener - The change listener to remove.

See Also:

addPropertyChangeListener(PropertyChangeListener)