Chapter 2. Configuring Provider

Table of Contents

2.1. Database Configuration
2.1.1. Configuration for Each Environment
2.1.2. Configuring Database Type
2.1.3. Configuring Automatic Schema Creation
2.2. Caching
2.3. Query Hint
2.4. Logging Configuration

This chapter describes how to configure EclipseLink, the basic provider of JEUS. The configuration is needed to implement features that are not defined in JPA specifications, and needs to be set accurately according to each application.

This section describes how to configure the database for each environment and database type, and how to automatically create the database schema.

Database configuration is different for each environment.

Java EE Environment

Java EE environment (or mode) refers to a web container, EJB container, application client container of JEUS Managed Server.

Target database to be used is set by the persistence.xml descriptor. The <jta-data-source> and <non-jta-data-source> elements are set according to the transaction type.

  • When using global transactions

    • Set <transaction-type> to JTA

    • Set <jta-data-source> to the JNDI name of the corresponding data source.

  • When using local transactions

    • Set <transaction-type> to RESOURCE_LOCAL

    • Set <non-jta-data-source> to the JNDI name of the corresponding data source


Java SE Environment

The Java SE environment (or mode) indicates that JPA is not used in a Java EE container, but in environments like the Java stand-alone client environment. Only local transactions can be used in this environment, and the JDBC properties, of the target database, must be configured.

Set <transaction-type>to 'RESOURCE_LOCAL'.


Descriptions for each property are as follows:


In general, database type can be detected through JDBC connection information. However, the 'eclipselink.target-database' property can be set for cases when automatic sensing feature does not work properly or when a separate database is used.

Note

Database type can be detected by using DatabaseMetaData.getDatabaseProductName() of the JDBC driver which searches for a database vendor name using regular expressions.


Descriptions for each database type value are as follows:


DBMS, that is not supported by default, can be used by separately implementing the DBMS support features. In this case, you can specify the name of the corresponding class. For more information on this, refer to Reference Data.

To use the feature that automatically creates the DB schema, set the following property. The property enables the DB tables and constraints to be automatically created when an application is deployed.


Refer to the following table for configuration properties related to automatic schema creation.

ItemDescription
eclipselink.ddl-generation

Setting on how to create DDL(Data Descriptor Language) for schema.

  • none: Does nothing (the default value).

  • create-tables: Creates new tables while keeping current ones.

  • drop-and-create-tables: Removes current tables and creates new ones.

When DDL is created, Java type is created according to the corresponding the Database SQL type, as shown in the following table.


JPA supports 1st-level caching called persistence context by default. However, since persistence context (except extended persistence context) is newly created for each transaction, caching between transactions is not supported. To compensate for this, TopLink Essentials provides 2nd-level caching capability.

Because 2nd-level caching is supported in the EntityManagerFactory level, all EntityManagers created in the same EntityManagerFactory use the shared cache. An entity, that does not exist in persistence context, is obtained from the 2nd-level cache, if the entity exists there. This will help improve performance when repeatedly performing a reading job.


Refer to the following table for more information about options related to caching.

ItemDescription
eclipselink.cache.type.default

Sets the caching type.

  • Full: Caches objects using hard references. They exist in the cache until the entity is removed.

  • HardWeak: Similar to Weak. Often used objects are cached using hard references.

  • SoftWeak: Similar to Weak. Often used objects are cached using soft references. Often used objects are removed when system is out of memory (the default value).

  • Weak: Caches objects using weak references. They are removed after garbage collection (GC).

  • NONE: Does not save objects in a cache. To disable the caching feature, change the toplink.cache.shared.xxx property.

eclipselink.cache.size.defaultSets the maximum number of objects that can be saved in the cache (the default value: 1,000)
eclipselink.cache.shared.default

Sets whether a shared cache is used.

  • true: Objects are saved in the shared cache. All EntityManagers use the cache (the default value).

  • false: Objects are not saved in the shared cache. EntityManagers do not share the cache. If set to "false," the 2nd-level caching is not used.

eclipselink.cache.type.<ENTITY>

Sets the cache type for each entity.

<ENTITY> may be replaced by an entity name or a fully-qualified class name. All entities related to the entity must have the same setting.

Same as the value described for eclipselink.cache.type.default.

eclipselink.cache.size.<ENTITY>

Sets the cache size for each Entity

<ENTITY> may be replaced by an entity name or a fully-qualified class name

Same as the value described for eclipselink.cache.size.default.

eclipselink.cache.shared.<ENTITY>

Sets whether each entity uses the shared cache.

<ENTITY> may be replaced by an entity name or a fully-qualified class name. All entities related to the entity must have the same setting.

Same as the value described for eclipselink.cache.shared.default.

Caution

When the 2nd-level caching is used, changes to DB data does not apply to the cache when changes are made directly or by external applications. In this case, the value in the cache, instead of the most recent value, is returned to the applications.

To prevent this, set the caching options accordingly or use EntityManager.refresh() and toplink.refresh query hint or locking (pessimistic/optimistic).

When using query objects, query hint enables the use of features supported by the provider.

It can be set when a query is performed as shown in the following example. It can also be set by @QueryHintAnnotation when using Named Query.


The following shows supported query hints.

ItemDescription
eclipselink.pessimistic-lock

Sets whether pessimistic locking is used when "SELECT" is performed.

  • NoLock: Does not use the locking (the default value).

  • Lock: Uses the locking by executing the "SELECT ... FOR UPDATE" statement.

  • NoLockWait: Uses the locking by executing the "SELECT ... FOR UPDATE NO WAIT" statement.

eclipselink.refresh

Sets whether to update a cache with the latest values from DB.

  • true: Gets the latest values and updates the cache.

  • false : Uses the values in the cache (the default value).

To see more detailed logs, configure the logging level.

By default, the logging level is set to the default level (INFO) of JEUS Server. Use the eclipselink.logging.level property to change the level for each persistence unit.

In the Java EE mode, the JEUS logger provided by JEUS is used by default. In the Java SE mode, the DefaultLogger is used by default. Use the eclipselink.logging.logger property to change this.


The following shows more detailed information:

ItemDescription
eclipselink.logging.level

Sets the logging level.

  • OFF: Log is not recorded

  • SEVERE

  • WARNING

  • INFO (the default value)

  • CONFIG

  • FINE: set to this level for more information related to SQL.

  • FINER

  • FINEST

eclipselink.logging.logger

Sets the logger to be used.

  • JEUSLogger: The logger provided by JEUS.

    (The default value for the Java EE mode)

  • DefaultLogger: The default standard output Logger

    (The default value for the Java SE mode)

  • JavaLogger: java.util.logging Logger.

  • Custom class name: Set to this logger if a separate logger is implemented