@PersistenceCapable (jdo)

The @javax.jdo.annotation.PersistenceCapable is used by JDO/DataNucleus to indicate that a class is a domain entity to be persisted to the database.

Apache Causeway also checks for this annotation, and if the @PersistenceCapable#schema attribute is present will use it to form the object type.

Causeway parses the @PersistenceCapable annotation from the Java source code; it does not query the JDO metamodel. This means that it the @PersistenceCapable annotation must be used rather than the equivalent <class> XML metadata.

This value is used internally to generate a string representation of an objects identity (the Oid). This can appear in several contexts, including:

as the value of Bookmark#getObjectType() and in the toString() value of Bookmark (see BookmarkService)
in the serialization of OidDto in the command and interaction schemas
in the URLs of the RestfulObjects viewer
in the URLs of the Web UI (Wicket viewer)
in XML snapshots generated by the XmlSnapshotService

The actual format of the object type used by Apache Causeway for the concatenation of schema() and @PersistenceCapable#table(). If the table() is not present, then the class' simple name is used instead.

Examples

For example:

@javax.jdo.annotations.PersistenceCapable(schema="custmgmt")
public class Customer {
    ...
}

has an object type of custmgmt.Customer, while:

@javax.jdo.annotations.PersistenceCapable(schema="custmgmt", table="Address")
public class AddressImpl {
    ...
}

has an object type of custmgmt.Address.

On the other hand:

@javax.jdo.annotations.PersistenceCapable(table="Address")
public class AddressImpl {
    ...
}

does not correspond to an object type, because the schema attribute is missing.

Precedence

The rules of precedence for determining a domain object’s object type are:

@Discriminator
@DomainObject#logicalTypeName
@PersistenceCapable, if at least the schema attribute is defined.

If both schema and table are defined, then the value is “schema.table”. If only schema is defined, then the value is “schema.className”.
Fully qualified class name of the entity.

This might be obvious, but to make explicit: we recommend that you always specify an object type for your domain objects.

Otherwise, if you refactor your code (change class name or move package), then any externally held references to the OID of the object will break. At best this will require a data migration in the database; at worst it could cause external clients accessing data through the Restful Objects viewer to break.

If the object type is not unique across all domain classes then the framework will fail-fast and fail to boot. An error message will be printed in the log to help you determine which classes have duplicate object tyoes.