Entity Management Settings

The <entities> configuration element specifies client-side and embedded-mode settings. The default configuration file contains the following <entities> element:

<entities>
  <enhancement agent="true" reflection="warning" />
  <cache ref="weak" level2="0mb" />
  <fetch hollow="true" />
  <persist serialization="false" />
  <cascade-persist always="auto" on-persist="false" on-commit="true" />
  <dirty-tracking arrays="false" />
</entities>

The <enhancement> element

  <enhancement agent="true" reflection="warning" />

The <enhancement> element specifies enhancement-related settings:

• The agent attribute (with a value of "true" or "false") specifies whether to load the Enhancer Agent to enhance persistable types on the fly, even if you do not specify it explicitly on the command line. This is an experimental feature that is supported only on select JVMs.
• The reflection attribute specifies how non-enhanced classes are handled. ObjectDB can manage non-enhanced classes by using reflection, which can affect performance. The possible values of the reflection attribute represent different policies:
  • "error" - All persistable classes must be enhanced; otherwise, ObjectDB throws an exception.
  • "warning" - ObjectDB logs a warning for every non-enhanced class.
  • "ignore" - ObjectDB uses reflection for non-enhanced classes with no error or warning.
  • "force" - ObjectDB uses reflection even for enhanced classes (for troubleshooting).

The <cache> element

  <cache ref="weak" level2="0mb" />

The <cache> element specifies settings for the two entity cache mechanisms:

• The ref attribute specifies the reference type for holding non-dirty entities in the persistence context of the EntityManagerjakarta.persistence.EntityManagerInterface used to interact with the persistence context., which serves as a first-level cache. The valid values are "weak", "soft", and "strong". Modified entities are always held by strong references in the persistence context (until commit or flush), regardless of this setting.
• The level2 attribute specifies the size of the shared level-2 cache that is managed by the EntityManagerFactoryjakarta.persistence.EntityManagerFactoryInterface used to interact with the persistence unit, and to create new instances of EntityManager . and shared by all its EntityManager instances. To disable the level-2 cache, specify 0 or 0mb.

The <fetch> element

<fetch hollow="true" />

The hollow attribute of the <fetch> element (with a value of "true" or "false") specifies whether to enable lazy loading of entities content. Instantiating entities as hollow and loading their persistent content lazily when they are accessed can improve performance. However, for some applications, disabling this feature is more efficient.

The <persist> element

  <persist serialization="false" />

The serialization attribute of the <persist> element (with a value of "true" or "false") specifies whether to use serialization as a fallback persistence method for instances of serializable types that are otherwise non-persistable (for example, a user-defined class that is not an entity, mapped superclass, or embeddable class).

The <cascade-persist> element

  <cascade-persist always="auto" on-persist="false" on-commit="true" />

The <cascade-persist> element specifies global settings for cascading persist operations:

• The always attribute (with a value of "true", "false", or "auto") specifies whether to always cascade persist operations for every entity, regardless of local cascade settings.
  The "auto" value functions as "true" when you use JDO and as "false" when you use JPA.
• The on-persist attribute specifies whether to apply cascading (as a result of either a global or local setting) during a persist operation.
• The on-commit attribute specifies whether to apply cascading (as a result of either a global or local setting) during commit and flush operations.

Note: Both JPA and JDO require cascading the persist operation twice: first during the persist operation and later during a commit or flush operation. Usually, cascading only at commit time is sufficient and more efficient than double cascading.

The <dirty-tracking> element

  <dirty-tracking arrays="false" />

The arrays attribute of the <dirty-tracking> element specifies whether to automatically track modifications to array cells in enhanced classes. For more details, see the Updating Entities section in Chapter 3.