Configuring Common Project Options

This table lists the configurable options shared by two or more EclipseLink project types. In addition to the configurable options described here, you must also configure the options described for the specific EclipseLink project types (see EclipseLink Project Types), as shown in the Configuring EclipseLink Projects table.

How to Configure Project Save Location Using Workbench

The Project Save Location field on the project's General tab is for display only. This field shows the full directory path for the project. All relative locations used in the project are based on this location.

General Tab, Project Save Location

To select a new location, right-click on the project in the Navigator and select Save As from the context menu. See How to Save Projects for more information.

Configuring Project Classpath

The EclipseLink project uses a classpath – a set of directories, JAR files, and ZIP files – when importing Java classes and defining object types.

This table summarizes which projects support project classpath configuration.

Do not include JDBC drivers or other elements required to access the data source in the project classpath. Use the setenv file to specify these application-level settings (see Configuring the Workbench Environment).

How to Configure Project Classpath Using Workbench

To specify the project classpath information, use this procedure:

Select the project object in the Navigator.

Click the General tab in the Editor. The General tab appears. General Tab, Classpath Options

To add a new classpath entry, click Add Entry or Browse and select the directory, .jar file, or .zip file for this project. To create a relative classpath, select an entry and edit the path, as necessary. The path will be relative to the Project Save Location.

To remove a classpath entry, select the entry and click Remove.

To change the order of the entries, select the entry and click Up or Down.

Configuring Method or Direct Field Access at the Project Level

By default, when EclipseLink performs a persistence operation, it accesses the persistent attributes of an object directly: this is known as direct field access. Alternatively, you can configure EclipseLink to access persistent attributes using accessor methods of the object: this is known as method access.

We recommend using field access for mappings. Not only is it more efficient, but using method access may cause issues if the method produces unexpected side-effects.

This table summarizes which projects support mapped field access configuration.

If you enable change tracking on a property (for example, you decorate method getPhone with @ChangeTracking) and you access the field (phone) directly, note that EclipseLink does not detect the change. For more information, see Using Method and Direct Field Access.

How to Configure Method or Direct Field Access at the Project Level Using Workbench

To specify the field access method information, use this procedure:

Select the project object in the Navigator.

Select the Defaults tab in the Editor. The Defaults tab appears. Defaults Tab, Field Accessing Options

Complete the Mapped Field Accessing options.

Configuring Default Descriptor Advanced Properties

You can configure default descriptor advanced properties when using the Workbench.

By default, Workbench displays a subset of features for each descriptor type. You can modify this subset so that descriptors include additional advanced properties by default.

Configuring Existence Checking at the Project Level

When EclipseLink writes an object to the database, it runs an existence check to determine whether to perform an insert or an update operation.

By default, EclipseLink checks against the cache. We recommend that you use this default existence check option for most applications. Checking the database for existence can cause a performance bottleneck in your application.

This table summarizes which projects support existence checking configuration.

By default, this configuration applies to all descriptors in a project. You can also configure existence checking at the descriptor level to override this project-level configuration on a descriptor-by-descriptor basis. For more information, see Configuring Cache Existence Checking at the Descriptor Level.

Use this table to enter data in following fields to specify the existence checking options for newly created descriptors:

Field

Description

Check Cache

Check the session cache. If the object is not in the cache, assume that the object does not exist (do an insert). If the object is in the cache, assume that the object exists (do an update). We recommend using this option for most applications.

Check Database

If an object is not in the cache, query the database to determine if the object exists. If the object exists, do an update. Otherwise, do an insert. Selecting this option may negatively impact performance. For more information, see Using Check Database.

Assume Existence

Always assume objects exist: always do an update (never do an insert). For more information, see Using Assume Existence.

Assume Nonexistence

Always assume objects do not exist: always do an insert (never do an update). For more information, see Using Assume Nonexistence.

Configuring Project Deployment XML Options

You can configure project deployment XML options when using Workbench.

Using Workbench, you can specify the default file names, class names, and directories, when exporting or generating deployment XML. Directories are relative to the project save location (see Configuring Project Save Location), and will contain folders for each generated package.

Configuring Model Java Source Code Options

You can configure model java source code options when using the Workbench.

Using Workbench, you can specify the default file names, class names, and directories, when exporting or generating Java source code for your domain objects. Directories are relative to the project save location (see Configuring Project Save Location), and will contain folders for each generated package.

The cache options you configure at the project level apply globally to all descriptors. Use this section to define global cache options for an EclipseLink project.

You can override the project-level identity map configuration by defining identity map configuration at the descriptor level. For information on caching and defining identity map configuration for a specific descriptor, see Configuring Cache Type and Size at the Descriptor Level.

Note: When using Workbench, changing the project's default identity map does not affect descriptors that already exist in the project; only newly added descriptors ar affected.

For detailed information on caching and object identity, and the recommended settings to maximize EclipseLink performance, see to Cache Type and Object Identity.

Changing the project's default identity map does not affect descriptors that already exist in the project.

Size

Specify the size of the cache as follows:

When using Weak with Soft Subcache or Weak with Hard Subcache, the size is the maximum number of objects stored in the identity map.

When using Full or Weak, the size indicates the starting size of the identity map.

How to Configure Cache Type and Size at the Project Level Using Java

Use one of the following ClassDescriptor methods to configure the descriptor to use the appropriate type of identity map:

useFullIdentitMap

useWeakIdentitMap

useSoftIdentitMap

useSoftCacheWeakIdentitMap

useHardCacheWeakIdentityMap

useNoIdentityMap

Use the ClassDescriptor method setIdentityMapSize to configure the size of the identity map.

Configuring Cache Isolation at the Project Level

If you plan to use isolated sessions (see Cache Isolation), you must configure descriptors as isolated for any object that you want confined to an isolated session cache.

Configuring a descriptor to be isolated means that EclipseLink will not store the object in the shared session cache and the object will not be shared across client sessions. This means that each client will have their own object read directly from the database. Objects in an isolated client session cache can reference objects in their parent server session's shared session cache, but no objects in the shared session cache can reference objects in an isolated client session cache. Isolation is required when using Oracle Database Virtual Private Database (VPD) support or database user-based read security. Isolation can also be used if caching is not desired across client sessions.

This table summarizes which projects support cache isolation configuration.

Use the following information to enter data in the Coordination field:

Coordination Option

Description

When to Use

None

For both existing and new instances, do not propagate a change notification.

Infrequently read or changed objects.

Synchronize Changes

For an existing instance, propagate a change notification that contains each changed attribute. For a new instance, propagate an object creation (along with all the new instance's attributes) only if the new instance is related to other existing objects that are also configured with this change propagation option.

Frequently read or changed objects that contain few attributes or in cases where only a few attributes are frequently changed. Objects that have many or complex relationships.

Synchronize Changes and New Objects

For an existing instance, propagate a change notification that contains each changed attribute. For a new instance, propagate an object creation (along with all the new instance's attributes).

Frequently read or changed objects that contain few attributes or in cases where only a few attributes are frequently changed. Objects that have few or simple relationships.

Invalidate Changed Objects

For an existing instance, propagate an object invalidation that marks the object as invalid in all other sessions. This tells other sessions that they must update their cache from the data source the next time this object is read. For a new instance, no change notification is propagated.

Frequently read or changed objects that contain many attributes in cases where many of the attributes are frequently changed.

Configuring Cache Expiration at the Project Level

By default, objects remain in the cache until they are explicitly deleted (see Deleting Objects) or garbage-collected when using a weak identity map (see Configuring Cache Type and Size at the Project Level). Alternatively, you can configure an object with a CacheInvalidationPolicy that lets you specify, either automatically or manually, that an object is invalid: when any query attempts to read an invalid object, EclipseLink will go to the data source for the most up-to-date version of that object and update the cache with this information.

Using cache invalidation ensures that your application does not use stale data. It provides a better performing alternative to refreshing (see Configuring Cache Refreshing).

This table summarizes which projects support cache invalidation configuration.

Configuring Project Comments

You can define a free-form textual comment for each project. You can use these comments however you whish: for example, to record important project implementation details such as the purpose or importance of a project.

In a Workbench project, the comments are stored in the EclipseLink deployment XML file. There is no Java API for this feature.