[#javax-jdo-annotation-PersistenceCapable]
= @PersistenceCapable (jdo)

:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.



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 Isis also checks for this annotation, and if the `@PersistenceCapable#schema` attribute is present will use it to form the object type.

[NOTE]
====
Isis 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>` link:http://www.datanucleus.org/products/accessplatform_4_0/jdo/class_mapping.html[XML metadata].

Moreover, while JDO/DataNucleus will recognize annotations on either the field or the getter method, Apache Isis (currently) only inspects the getter method.
Therefore ensure that the annotation is placed there.
====

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 xref:refguide:applib:index/services/bookmark/BookmarkService.adoc[BookmarkService])
* in the serialization of `OidDto` in the xref:refguide:schema:cmd.adoc[command] and xref:refguide:schema:ixn.adoc[interaction] schemas
* in the URLs of the xref:vro:ROOT:about.adoc[RestfulObjects viewer]
* in the URLs of the xref:vw:ROOT:about.adoc[Web UI (Wicket viewer)]
* in XML snapshots generated by the xref:refguide:applib:index/services/xmlsnapshot/XmlSnapshotService.adoc[XmlSnapshotService]


The actual format of the object type used by Apache Isis 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:

[source,java]
----
@javax.jdo.annotations.PersistenceCapable(schema="custmgmt")
public class Customer {
    ...
}
----

has an object type of `custmgmt.Customer`, while:

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

has an object type of `custmgmt.Address`.

On the other hand:

[source,java]
----
@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:

1. xref:refguide:applib-ant:Discriminator.adoc[@Discriminator]
2. `@DomainObject#logicalTypeName`
3. xref:refguide:applib-ant:PersistenceCapable.adoc[@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`".

4. Fully qualified class name of the entity.

[TIP]
====
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 xref:vro:ROOT:about.adoc[Restful Objects] viewer to break.
====

[NOTE]
====
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.
====
