Entity Management Settings

The <entities> configuration element specifies front end settings that are relevant on the client side and in embedded mode.

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 (whose value is "true" or "false") specifies whether the Enhancer Agent should be loaded to enhance persistable types on the fly, even if it is not specified explicitly at the command line. This is currently an experimental feature, supported only on selected JVMs.
• The reflection attribute specifies how non enhanced classes are handled. ObjectDB can manage non enhanced classes by using reflection at the cost of performance. The possible values of the reflection attribute represent different policies:
  • "error" - all persistable classes must be enhanced - otherwise an exception is thrown.
  • "warning" - a warning is logged for every non enhanced class.
  • "ignore" - reflection is used for non enhanced classes - with no error or warning.
  • "force" - reflection is used even for enhanced classes (for troubleshooting).

The <cache> element

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

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

• The ref attribute specifies the reference type for holding non dirty entities in the persistence context of the EntityManagerjavax.persistence.EntityManagerJPA interfaceInterface used to interact with the persistence context.See JavaDoc Reference Page... (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 EntityManagerFactoryjavax.persistence.EntityManagerFactoryJPA interfaceInterface used to interact with the entity manager factory for the persistence unit.See JavaDoc Reference Page... and shared by all its EntityManager instances. The level 2 cache is disabled by specifying 0 or 0mb.

The <fetch> element

<fetch hollow="true" />

The hollow attribute of the <fetch> element (whose value is "true" or "false") specifies if lazy loading of entity objects content is enabled. Instantiating entity objects as hollow, and loading their persistent content lazily, when they are accessed, could improve performance. However, for some applications disabling this ability could be more efficient.

The <persist> element

  <persist serialization="false" />

The serialization attribute of the <persist> element (whose value is "true" or "false") specifies if serialization should be used as a fallback persisting method for instances of serializable types that are non persistable otherwise (e.g. a user defined class, which is not an entity class, mapped super class 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 (whose value is "true", "false" or "auto") specifies if persist operations should always be cascaded for every entity, regardless of local cascade settings.
  The "auto" value functions as "true" when using JDO and as "false" when using JPA.
• The on-persist attribute specifies whether cascading (as a result of either global or local setting) should be applied during persist.
• The on-commit attribute specifies whether cascading (as a result of either global or local setting) should be applied during commit and flush.

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

The <dirty-tracking> element

  <dirty-tracking arrays="false" />

The arrays attribute of the <dirty-tracking> element specifies if modifications to array cells should be tracked automatically in enhanced classes. See the Updating Entities section in chapter 3 for more details.