Table of Contents
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 (or mode) refers to a web container, EJB container, application client container of JEUS Managed Server.
More accurately, it refers to the thread controlled by each container. An example is the thread of the web thread pool configured in the web engine. If there is a thread which is not controlled by a container, such as a thread pool created by an application, it will be managed in the same way as in the Java SE environment.
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
[Example 2.1] Configuring Database in the Java EE Mode
<?xml version="1.0" encoding="UTF-8"?>
<persistence xmlns="http://java.sun.com/xml/ns/persistence">
<persistence-unit name="em" transaction-type="JTA">
<jta-data-source>jdbc/MyDB</jta-data-source>
</persistence-unit>
</persistence>
1. If <transaction-type> is not set in the Java EE environment, by default, JTA transaction will be used.
2. For information on how to configure DB Data Source in JEUS, refer to JEUS Server Guide. "Chapter 6. DB Connection Pool and JDBC".
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'.
[Example 2.2] Configuring Database in the Java SE Mode
<?xml version="1.0" encoding="UTF-8"?>
<persistence xmlns="http://java.sun.com/xml/ns/persistence">
<persistence-unit name="em" transaction-type="RESOURCE_LOCAL">
<properties>
<property name="eclipselink.jdbc.driver"
value="org.apache.derby.jdbc.ClientDriver"/>
<property name="eclipselink.jdbc.url"
value="jdbc:derby://localhost:1527/testdb"/>
<property name="eclipselink.jdbc.user" value="APP"/>
<property name="eclipselink.jdbc.password" value="APP"/>
</properties>
</persistence-unit>
</persistence>
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.
Database type can be detected by using DatabaseMetaData.getDatabaseProductName() of the JDBC driver which searches for a database vendor name using regular expressions.
[Example 2.3] Configuring Database Type
<?xml version="1.0" encoding="UTF-8"?>
<persistence xmlns="http://java.sun.com/xml/ns/persistence">
<persistence-unit name="em">
<jta-data-source>jdbc/MyDB</jta-data-source>
<properties>
<property name="eclipselink.target-database" value="DB2"/>
</properties>
</persistence-unit>
</persistence>
Descriptions for each database type value are as follows:
[Table 2.2] eclipselink.target-Database Property
| Value | Description |
|---|---|
| Auto | Automatic Sensing (Default) |
| Attunity | Attunity DBMS |
| Cloudscape | Cloudscape DBMS |
| DB2 | IBM DB2 DBMS |
| DB2Mainframe | IBM DB2 Mainframe DBMS |
| DBase | DBase DBMS |
| Derby | Apache Derby DBMS |
| HSQL | HSQL DBMS |
| Informix | Informix DBMS |
| JavaDB | JavaDB DBMS |
| MySQL4 | MySQL DBMS |
| Oracle | Oracle DBMS |
| PointBase | PointBase DBMS |
| PostreSQL | PostreSQL DBMS |
| SQLAnyWhere | SQLAnywhere DBMS |
| SQLServer | Microsoft SQLServer DBMS |
| Sybase | Sybase DBMS |
| TimesTen | Oracle Timesten DBMS |
| Customized class name | Used to add DBMS that is not supported by default. |
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.
[Example 2.4] Automatic Schema Creation
<?xml version="1.0" encoding="UTF-8"?>
<persistence xmlns="http://java.sun.com/xml/ns/persistence">
<persistence-unit name="em">
<jta-data-source>jdbc/MyDB</jta-data-source>
<properties>
...
<property name="eclipselink.ddl-generation" value="create-tables" />
...
</properties>
</persistence-unit>
</persistence>
Refer to the following table for configuration properties related to automatic schema creation.
When DDL is created, Java type is created according to the corresponding the Database SQL type, as shown in the following table.
[Table 2.3] Java Type to SQL Type Mappings
| Java Type | Derby, JavaDB, Cloudscape | Oracle | DB2 | Sybase | SQLServer | MySQL |
|---|---|---|---|---|---|---|
| boolean, Boolean | SMALLINT | NUMBER(1) | SMALLINT | BIT | BIT | TINYINT(1) |
| int, Integer | INTEGER | NUMBER(10) | INTEGER | INTEGER | INTEGER | INTEGER |
| long, Long | BIGINT | NUMBER(19) | INTEGER | NUMERIC(19) | NUMERIC(19) | BIGINT |
| float, Float | FLOAT | NUMERIC(19,4) | FLOAT | FLOAT(16) | FLOAT(16) | FLOAT |
| double, Double | FLOAT | NUMERIC(19,4) | FLOAT | FLOAT(32) | FLOAT(32) | DOUBLE |
| short, Short | SMALLINT | NUMBER(5) | SMALLINT | SMALLINT | SMALLINT | SMALLINT |
| byte, Byte | SMALLINT | NUMBER(3) | SMALLINT | SMALLINT | SMALLINT | SMALLINT |
java.lang .Number | DECIMAL | NUMBER(38) | DECIMAL(15) | NUMERIC(38) | NUMERIC(28) | DECIMAL(38) |
java.math .BigInteger | BIGINT | NUMBER(38) | BIGINT | NUMERIC(38) | NUMERIC(28) | BIGINT |
java.math .BigDecimal | DECIMAL | NUMBER(38) | DECIMAL(15) | NUMERIC(38) | NUMERIC(28) | DECIMAL(38) |
java.lang .String | VARCHAR(255) | VARCHAR(255) | VARCHAR(255) | VARCHAR(255) | VARCHAR(255) | VARCHAR(255) |
| char, Character | CHAR(1) | CHAR(1) | CHAR(1) | CHAR(1) | CHAR(1) | CHAR(1) |
| byte[], Byte[], java.sql.Blob | BLOB(64000) | LONG RAW | BLOB(64000) | TEXT | TEXT | TEXT(64000) |
| char[], Character[], java.sql.Clob | CLOB(64000) | LONG | CLOB(64000) | TEXT | TEXT | TEXT(64000) |
| java.sql.Date | DATE | DATE | DATE | DATETIME | DATETIME | DATE |
| java.sql.Time | TIME | DATE | TIME | DATETIME | DATETIME | TIME |
java.sql .Timestamp | TIMESTAMP | DATE | TIMESTAMP | DATETIME | DATETIME | DATETIME |
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.
[Example 2.5] Caching Type Configuration Example
<?xml version="1.0" encoding="UTF-8"?>
<persistence xmlns="http://java.sun.com/xml/ns/persistence">
<persistence-unit name="em">
<jta-data-source>jdbc/MyDB</jta-data-source>
<properties>
...
<property name="eclipselink.ddl-generation" value="create-tables" />
<property name="eclipselink.cache.type.default" value="NONE" />
<property name="eclipselink.cache.size.default" value="999" />
<property name="eclipselink.cache.shared.default" value="false" />
...
</properties>
</persistence-unit>
</persistence>
Refer to the following table for more information about options related to caching.
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.
[Example 2.6] Using Query Hint
List employees
= em.createQuery("SELECT e FROM Employee e WHERE e.name = :name")
.setParameter("name", name)
.setHint("eclipselink.refresh", true)
.getResultList();
The following shows supported query hints.
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.
[Example 2.7] Logging Configuration Example
<?xml version="1.0" encoding="UTF-8"?>
<persistence xmlns="http://java.sun.com/xml/ns/persistence">
<persistence-unit name="em">
<jta-data-source>jdbc/MyDB</jta-data-source>
<properties>
...
<property name="eclipselink.logging.level" value="FINE"/>
<property name="eclipselink.logging.logger" value="DefaultLogger"/>
...
</properties>
</persistence-unit>
</persistence>
The following shows more detailed information:
1. Refer to http://wiki.eclipse.org/EclipseLink/UserGuide/JPA for more information about EclipseLink.
2. Refer to http://www.eclipse.org/eclipselink/documentation/2.4/solutions/migrnativetoplink.htm when converting from TopLink to EclipseLink.