= ArchitectureJdoRules
: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.

A library of architecture tests to ensure coding conventions are followed for classes annotated with the JDO _javax.jdo.annotations.PersistenceCapable_ annotation.

== API

[source,java]
.ArchitectureJdoRules.java
----
class ArchitectureJdoRules {
  ArchRule every_logicalTypeName_and_jdo_discriminator_must_be_same()
  ArchRule every_jdo_PersistenceCapable_must_be_annotated_with_DomainObject_nature_of_ENTITY()     // <.>
  ArchRule every_jdo_PersistenceCapable_must_be_annotated_with_Version()     // <.>
  ArchRule every_jdo_PersistenceCapable_must_be_annotated_as_XmlJavaAdapter_PersistentEntityAdapter()     // <.>
  ArchRule every_jdo_PersistenceCapable_must_implement_Comparable()     // <.>
  ArchRule every_jdo_PersistenceCapable_must_be_annotated_as_Uniques_or_Unique()     // <.>
  ArchRule every_jdo_PersistenceCapable_with_DATASTORE_identityType_must_be_annotated_as_DataStoreIdentity()     // <.>
  ArchRule every_jdo_PersistenceCapable_must_have_schema()     // <.>
  DescribedPredicate<JavaAnnotation<?>> PersistenceCapable_schema()
  DescribedPredicate<JavaAnnotation<?>> PersistenceCapable_with_DATASTORE_identityType()
  ArchRule every_injected_field_of_jdo_PersistenceCapable_must_be_annotated_with_NotPersistent()     // <.>
  DescribedPredicate<JavaClass> areEntities()
  DescribedPredicate<? super JavaClass> areSubtypeEntities()
}
----

<.> xref:#every_jdo_PersistenceCapable_must_be_annotated_with_DomainObject_nature_of_ENTITY_[every_jdo_PersistenceCapable_must_be_annotated_with_DomainObject_nature_of_ENTITY()]
+
--
This rule requires that classes annotated with the JDO _javax.jdo.annotations.PersistenceCapable_ annotation must also be annotated with the Apache Isis xref:refguide:applib:index/annotation/DomainObject.adoc[DomainObject] annotation specifying that its _DomainObject#nature() nature_ is an _org.apache.isis.applib.annotation.Nature#ENTITY entity_ .
--
<.> xref:#every_jdo_PersistenceCapable_must_be_annotated_with_Version_[every_jdo_PersistenceCapable_must_be_annotated_with_Version()]
+
--
This rule requires that classes annotated with the JDO _javax.jdo.annotations.PersistenceCapable_ annotation must also be annotated with the JDO _javax.jdo.annotations.Version_ annotation (in support of optimistic locking checks).
--
<.> xref:#every_jdo_PersistenceCapable_must_be_annotated_as_XmlJavaAdapter_PersistentEntityAdapter_[every_jdo_PersistenceCapable_must_be_annotated_as_XmlJavaAdapter_PersistentEntityAdapter()]
+
--
This rule requires that classes annotated with the JDO _javax.jdo.annotations.PersistenceCapable_ annotation must also be annotated with the Apache Isis _javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter_ annotation with a value of _org.apache.isis.applib.jaxb.PersistentEntityAdapter_ `.class` .
--
<.> xref:#every_jdo_PersistenceCapable_must_implement_Comparable_[every_jdo_PersistenceCapable_must_implement_Comparable()]
+
--
This rule requires that classes annotated with the JDO _javax.jdo.annotations.PersistenceCapable_ annotation must also implement _Comparable_ .
--
<.> xref:#every_jdo_PersistenceCapable_must_be_annotated_as_Uniques_or_Unique_[every_jdo_PersistenceCapable_must_be_annotated_as_Uniques_or_Unique()]
+
--
This rule requires that classes annotated with the JDO _javax.jdo.annotations.PersistenceCapable_ annotation and is not a subtype entity, must also be annotated with the JDO _javax.jdo.annotations.Uniques_ or _javax.jdo.annotations.Unique_ constraints.
--
<.> xref:#every_jdo_PersistenceCapable_with_DATASTORE_identityType_must_be_annotated_as_DataStoreIdentity_[every_jdo_PersistenceCapable_with_DATASTORE_identityType_must_be_annotated_as_DataStoreIdentity()]
+
--
This rule requires that classes annotated with the JDO _javax.jdo.annotations.PersistenceCapable_ annotation must also be annotated with the JDO _javax.jdo.annotations.Uniques_ or _javax.jdo.annotations.Unique_ constraints.
--
<.> xref:#every_jdo_PersistenceCapable_must_have_schema_[every_jdo_PersistenceCapable_must_have_schema()]
+
--
This rule requires that classes annotated with the JDO _javax.jdo.annotations.PersistenceCapable_ annotation must have the _javax.jdo.annotations.PersistenceCapable#schema() schema_ attribute set.
--
<.> xref:#every_injected_field_of_jdo_PersistenceCapable_must_be_annotated_with_NotPersistent_[every_injected_field_of_jdo_PersistenceCapable_must_be_annotated_with_NotPersistent()]
+
--
This rule requires that injected fields in classes annotated with the JDO _PersistenceCapable_ annotation must also be annotated with JDO _javax.jdo.annotations.NotPersistent_ annotation.
--

== Members

[#every_jdo_PersistenceCapable_must_be_annotated_with_DomainObject_nature_of_ENTITY_]
=== every_jdo_PersistenceCapable_must_be_annotated_with_DomainObject_nature_of_ENTITY()

This rule requires that classes annotated with the JDO _javax.jdo.annotations.PersistenceCapable_ annotation must also be annotated with the Apache Isis xref:refguide:applib:index/annotation/DomainObject.adoc[DomainObject] annotation specifying that its _DomainObject#nature() nature_ is an _org.apache.isis.applib.annotation.Nature#ENTITY entity_ .

[#every_jdo_PersistenceCapable_must_be_annotated_with_Version_]
=== every_jdo_PersistenceCapable_must_be_annotated_with_Version()

This rule requires that classes annotated with the JDO _javax.jdo.annotations.PersistenceCapable_ annotation must also be annotated with the JDO _javax.jdo.annotations.Version_ annotation (in support of optimistic locking checks).

The rule does _not_ apply to any entities that are subtype entities where there is a supertype entity.

[#every_jdo_PersistenceCapable_must_be_annotated_as_XmlJavaAdapter_PersistentEntityAdapter_]
=== every_jdo_PersistenceCapable_must_be_annotated_as_XmlJavaAdapter_PersistentEntityAdapter()

This rule requires that classes annotated with the JDO _javax.jdo.annotations.PersistenceCapable_ annotation must also be annotated with the Apache Isis _javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter_ annotation with a value of _org.apache.isis.applib.jaxb.PersistentEntityAdapter_ `.class` .

Tnis is so that entities can be transparently referenced from XML-style view models.

[#every_jdo_PersistenceCapable_must_implement_Comparable_]
=== every_jdo_PersistenceCapable_must_implement_Comparable()

This rule requires that classes annotated with the JDO _javax.jdo.annotations.PersistenceCapable_ annotation must also implement _Comparable_ .

This is so that entities have a natural ordering and can safely be added to parented collections of type _java.util.SortedSet_ .

[#every_jdo_PersistenceCapable_must_be_annotated_as_Uniques_or_Unique_]
=== every_jdo_PersistenceCapable_must_be_annotated_as_Uniques_or_Unique()

This rule requires that classes annotated with the JDO _javax.jdo.annotations.PersistenceCapable_ annotation and is not a subtype entity, must also be annotated with the JDO _javax.jdo.annotations.Uniques_ or _javax.jdo.annotations.Unique_ constraints.

This is so that entities will have an alternative business key in addition to the system-defined surrogate key.

[#every_jdo_PersistenceCapable_with_DATASTORE_identityType_must_be_annotated_as_DataStoreIdentity_]
=== every_jdo_PersistenceCapable_with_DATASTORE_identityType_must_be_annotated_as_DataStoreIdentity()

This rule requires that classes annotated with the JDO _javax.jdo.annotations.PersistenceCapable_ annotation must also be annotated with the JDO _javax.jdo.annotations.Uniques_ or _javax.jdo.annotations.Unique_ constraints.

This is so that entities will have an alternative business key in addition to the system-defined surrogate key.

The rule does _not_ apply to any entities that are subtype entities where there is a supertype entity.

[#every_jdo_PersistenceCapable_must_have_schema_]
=== every_jdo_PersistenceCapable_must_have_schema()

This rule requires that classes annotated with the JDO _javax.jdo.annotations.PersistenceCapable_ annotation must have the _javax.jdo.annotations.PersistenceCapable#schema() schema_ attribute set.

This is so that entity tables are organised into an appropriate structure (ideally mirroring that of the entities).

[#every_injected_field_of_jdo_PersistenceCapable_must_be_annotated_with_NotPersistent_]
=== every_injected_field_of_jdo_PersistenceCapable_must_be_annotated_with_NotPersistent()

This rule requires that injected fields in classes annotated with the JDO _PersistenceCapable_ annotation must also be annotated with JDO _javax.jdo.annotations.NotPersistent_ annotation.

The rationale here is that injected services are managed by the runtime and are not/cannot be persisted.

In fact, JDO is tolerant to such fields and will not trip up. So another more pragmatic reason is that, if using JDO type-safe queries, then the injected fields will not appear incorrectly in the generated Q classes.
