Check for a behavior change in JPA MetaModel code generation concerning ListAttribute

This rule flags persistence.xml files to warn the user about a behavior change in OpenJPA concerning code generated using ListAttribute.

If you are migrating an application which is not using the JPA 2.0 specification, then you will not encounter this issue. If your application is not using the Criteria API or Metamodel API from the JPA 2.0 specification, then you will not encounter this issue.

The type of applications that are potentially affected by this change are those applications which utilize the type-safe JPA Criteria API interface or the JPA Metamodel API interface directly. Note that this Metamodel API was introduced as part of the JPA 2.0 specification. There are two version of WebSphere which include the JPA 2.0 specification which exhibit the problem described earlier. Those are:

• WebSphere version 7 with the OSGi/JPA 2.0 Feature Pack, and
• WebSphere version 8

WebSphere v8.5 utilizes and ships OpenJPA 2.2.0. In previous releases (see the preceeding paragraph) OpenJPA's MetaModel implementation generated a ListAttribute for every array. This behavior is correct if the array is stored as a PersistentCollection, but not correct for un-annotated arrays (e.g. byte[], char[]). In OpenJPA 2.2.0 this behavior was corrected so that arrays which are not stored as PersistentCollections will use a SingularAttribute instead of a ListAttribute.

To maintain backward compatibility a property and value can be set in the persistence.xml file. Specifically, to use code which has not been regenerated you can set <property name="openjpa.Compatibility" value="UseListAttributeForArrays=true"/> in the persistence.xml file. If your application environment regenerates your metamodel code, then you will not experience this issue and you do not need to use this property. The newly regenerated code will have the proper declaration. However, if your application does not regenerate the metamodel code, which might be the case when doing a binary migration, then you can use this property to allow the old generated code to be used with the new runtime.

To assist in maintaining backward compatibility, during configuration transformation a system property, UseListAttributeForArrays=true, will be set. However, a system property for OpenJPA is ignored if the application already has it set. This rule notifies the user when setting the UseListAttributeForArrays system property will be ignored because it cannot override an existing openjpa.Compatibility setting in the persistence.xml file.

This rule will flag persistence.xml files when:

• the following two conditions are met:
  • Java files in the same project contain the @javax.persistence.metamodel.StaticMetamodel annotation, and
  • The value of the annotation corresponds to a class in the persistence-unit which contains the openjpa.Compatibility property
• and either:
  • The openjpa.Compatibility property is set but does not contain the value "UseListAttributeForArrays", or
  • The openjpa.Compatibility property is set and the value "UseListAttributeForArrays" equals anything other than "true"

When the automated fix for this rule becomes available it will modify the UseListAttributeForArrays value in the openjpa.Compatibility property so that the value will contain value="UseListAttributeForArrays=true" .

The recommended action is one of the following.

• If metamodel classes are not regenerated then backwards compatibility can be maintained by setting the openjpa.Compatibility property UseListAttributeForArrays to true in the persistence.xml. This can be accomplished using the automated fix which will be provided.
• Regenerate the canonical metamodel classes. Note that these regenerated classes will only run in WebSphere v8.5 and will not run correctly on prior versions of WebSphere.
• Modify the Entity code to use the @PersistentCollection annotation (OpenJPA specific annotation)

For more information see,

• MetaModel Attributes for Arrays