Table of Contents
This chapter describes how to configure the basic provider of JEUS, EclipseLink. 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.
The Java EE environment (or mode) refers to a web container, EJB container, application client container of a JEUS Managed Server.
More accurately, the environment 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 is also managed in the same way as the container-controlled 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. In this environment, only local transactions can be used, 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>
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>
The following describes each database type value:
| Value | Description |
|---|---|
| Auto | Automatic Sensing (Default) |
| Cloudscape | Cloudscape DBMS |
| DB2 | IBM DB2 DBMS |
| DB2Mainframe | IBM DB2 Mainframe DBMS |
| Derby | Apache Derby DBMS |
| HSQL | HSQL DBMS |
| JavaDB | JavaDB DBMS |
| MySQL4 | MySQL DBMS |
| Oracle | Oracle DBMS |
| PostreSQL | PostreSQL DBMS |
| SQLServer | Microsoft SQLServer DBMS |
| Sybase | Sybase DBMS |
| Customized class name | Used to add DBMS that is not supported by default. |
| Others | For other DBs, refer to the target-database section in the Persistence Property Extensions Reference page of eclipselink. |
If you want to use a DBMS that is not supported by default, you can implement the DBMS support features by specifying the corresponding class name. For more information, 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>
The following is a configuration property associated with automatic schema creation.
When DDL is created, a Java type is created according to the corresponding the Database SQL type. The following table is a summary of Java types and the Database SQL types:
| 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, Eclipse Link 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>
The following table describes caching options:
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 are query hints supported in JEUS8.
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.
n 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. You can change the default logger by using the eclipselink.logging.logger property.
[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:
For more information about EclipseLink, refer to http://wiki.eclipse.org/EclipseLink/UserGuide/JPA.