net.sf.mmm.util.bean.api.id

Interface Id<E>

Type Parameters:

E - the generic type of the identified entity.

All Superinterfaces:

AttributeReadUuid, Datatype, Serializable

All Known Implementing Classes:

AbstractId, GenericId, OrientId

public interface Id<E>
extends Datatype, AttributeReadUuid

This is the interface for an ID that uniquely identifies an Entity of a particular type.
An Id is build out of the following parts:

• object-id - the ID that identifies the entity and is unique for a specific type.
• type - is the ID of the type of the identified entity.
• revision - the optional revision of the entity.

Just like the primary key the revision and type of an object do not change. This allows to create an instance of the identified object without additional costs (e.g. database lookup) by a dynamic proxy using lazy loading.
An Id has a compact string representation that can be converted back to an Id. Therefore, the implementation shall provide a String-arg constructor and a static valueOf(String) method.

Since:

8.0.0

Author:

hohwille

See Also:

GenericId

Field Summary

Fields

Modifier and Type	Field and Description
static long	ID_UUID The value used as id if a UUID is used as primary key instead.
static long	VERSION_LATEST The value used as version if it unspecified.
static char	VERSION_SEPARATOR The separator for the version.

Method Summary

Modifier and Type	Method and Description
long	getId()
Class<E>	getType()
UUID	getUuid() Gets the primary key as UUID.
long	getVersion()
String	toString() Returns the official String representation of this Datatype.
Id<E>	withLatestVersion()
Id<E>	withType(Class<?> type)

Field Detail

VERSION_LATEST

static final long VERSION_LATEST

The value used as version if it unspecified. If you are using an Id as link to an Entity you will use this value to point to the recent version of the Entity.

See Also:

Constant Field Values

ID_UUID

static final long ID_UUID

The value used as id if a UUID is used as primary key instead.

See Also:

Constant Field Values

VERSION_SEPARATOR

static final char VERSION_SEPARATOR

The separator for the version.

See Also:

Constant Field Values

Method Detail

getId

long getId()

Returns:

the primary key of the identified Entity as long value. It is only unique for a particular type of an entity. May also be ID_UUID.

getUuid

UUID getUuid()

Gets the primary key as UUID. Most data stores will use a long provided by getId(). However a UUID can be used in the following scenarios:

• Your data store uses UUIDs natively as primary key (e.g. apache cassandra supports this). In such case getId() will always return ID_UUID and getUuid() holds the actual primary key.
• You may need to express a link to a transient entity. Then you can temporary assign a UUID to the entity on the client and link it via such ID. On the server-side the actual UUID based Id can then be replaced with the actual ID while persisting the data.

In other cases this method will simply return null.

Specified by:

getUuid in interface AttributeReadUuid

Returns:

the primary key of the identified Entity as UUID value or null if getId() is used.

getType

Class<E> getType()

Returns:

the Class reflecting the type of the referenced entity.

withType

Id<E> withType(Class<?> type)

Parameters:

type - the value of getType(). Exact type should actually be Class<E> but this prevents simple usage. As the type can not actually be changed with this method, this should be fine.

Returns:

an instance of Id ensured to carry the type.

withLatestVersion

Id<E> withLatestVersion()

Returns:

this Id with a version of VERSION_LATEST e.g. to use the Id as regular foreign key (pointing to the latest revision and not a historic revision).

getVersion

long getVersion()

Returns:

the version of this entity. Whenever the Entity gets updated (a modification is saved and the transaction is committed), this counter is increased. The initial value of a new EntityBean is 0. The version acts as a modification counter for optimistic locking. On each update it will be verified that the version has not been increased already by another transaction. When linking an Entity (Id used as foreign key) the version can act as revision for auditing. If it is VERSION_LATEST it points to the latest revision of the Entity. Otherwise it points to a specific historic revision of the Entity. Depending on the database technology (e.g. when using hibernate envers) the version and the revision can be semantically different. In such case a primary key can not directly be used as revisioned foreign key Id.

toString

String toString()

Description copied from interface: Datatype

Returns the official String representation of this Datatype. While the general contract of Object.toString() is very weak and mainly used for debugging, the contract here is very strong. The returned String has to be suitable for end-users and official output to any kind of sink.
ATTENTION:
This method is not supposed to do internationalization (I18N). See NlsMessage for this purpose and implement NlsObject if you want to support I18N/L10N.

Specified by:

toString in interface Datatype

Overrides:

toString in class Object

Returns:

the String representation of this Id. Will consist of object-id, type and revision separated with a specific separator. Segments that are null will typically be omitted in the String representation.