Friday Jan 18, 2013

JPA 2.1 Implementation - EclipseLink M6 integrated in GlassFish 4 (TOTD #195)

As TOTD #187 explained, one of the new features in JPA 2.1 is Schema Generation. It refers to generation of database artifacts like tables, indexes, and constraints in a database schema. Read TOTD #187 for more details. This Tip Of The Day (TOTD) will explain how to use this feature in GlassFish 4.

JPA 2.1 is implemented in EclipseLink and the status shows that a decent progress is made. EclipseLink Milestone builds shows the dates when milestones are released. It typically takes a few days for the milestone to be integrated in GlassFish 4 after the release.

How do you know which milestone is integrated in GlassFish 4 ?

Issue the following commmand in glassfish/modules directory:
unzip -p org.eclipse.persistence.core.jar META-INF/MANIFEST.MF | grep Bundle-Version
to see an output as:
Bundle-Version: 2.5.0.v20130110-d839ca4
If we break the version string then it shows this is version 2.5.0 and dated 20130110 in the format YYYYMMDD, that would be Jan 10, 2013. Based upon the milestone release dates, this indicates M6 is integrated.

I tried this with the latest nightly build (dated Jan 18). By the time you read this blog, a newer version may be integrated and so the version string may look different.

Now lets see this in action!

The sample code explained below can be downloaded here and run on GlassFish 4 1/17 nightly. A promoted build after this nightly should work too.

Create an Entity class as:
@Entity
@Table
@NamedQueries({
@NamedQuery(name = "Employee.findAll", query = "SELECT e FROM Employee e")
})
public class Employee implements Serializable {
private static final long serialVersionUID = 1L;
@Id
@GeneratedValue(strategy = GenerationType.AUTO)
private int id;

@Column(length=40)
private String name;
This is a simple Employee entity that has two fields id and name. A trivial @NamedQuery is defined to retrieve the list of employees.

The associated persistence.xml looks like:

<?xml version="1.0" encoding="UTF-8"?>
<persistence version="2.0" xmlns="http://java.sun.com/xml/ns/persistence" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_2_0.xsd">
<persistence-unit name="MyPU" transaction-type="JTA">
<jta-data-source>jdbc/sample</jta-data-source>
<properties>
<property name="javax.persistence.schema-generation-action" value="drop-and-create"/>
<property name="javax.persistence.schema-generation-target" value="database"/>
<property name="eclipselink.deploy-on-startup" value="true"/>
</properties>
</persistence-unit>
</persistence>

Other than the usual elements like <persistence-unit> and <jta-data-source>, the newly introduced properties - javax.persistence.schema-generation-action and javax.persistence.schema-generation-target define the action and target for the schema generation. The action is to drop and create the tables. The target defines to perform the action in the database. These properties control the behavior of schema generation and their meaning is defined in TOTD #187. Notice, the third property is EclipseLink specific and is specified to eagerly initialize the Persistence Unit. This will ensure that the schema is generated during the application deployment itself. Otherwise it is generated when the PU is first accessed.

This will generate the table in the database defined by jdbc/sample JDBC resource. This resource is pre-defined for JavaDB that is already bundled with GlassFish 4.

After this, you can write a simple EJB as:

@Stateless
public class EmployeeBean {

@PersistenceContext
EntityManager em;

public void persist(Employee e) {
em.persist(e);
}

public List<Employee> get() {
return em.createNamedQuery("Employee.findAll", Employee.class).getResultList();
}
}

And invoke it from a Servlet as:

for (int i=0; i<5; i++) {
bean.persist(new Employee("Name" + i));
}
for (Employee e : bean.get()) {
out.println(e.getName() + "<br>");
}

A different set of properties may be specified as:

<properties>
<property name="javax.persistence.schema-generation-action" value="drop-and-create"/>
<property name="javax.persistence.schema-generation-target" value="scripts"/>
<property name="javax.persistence.ddl-create-script-target" value="createfoo.sql"/>
<property name="javax.persistence.ddl-drop-script-target" value="dropfoo.sql"/>
<property name="eclipselink.deploy-on-startup" value="true"/>
<property name="eclipselink.application-location" value="/tmp"/>
</properties>
These properties specify the action as "drop-and-create", i.e. drop and create the tables. The target specifies the the action to be performed in a script. The *.script-target property specifies the name of the files for create and drop DDL. The following scripts are generated:

more /tmp/createfoo.sql 
CREATE TABLE EMPLOYEE (ID INTEGER NOT NULL, NAME VARCHAR(40), PRIMARY KEY (ID))
CREATE TABLE SEQUENCE (SEQ_NAME VARCHAR(50) NOT NULL, SEQ_COUNT DECIMAL(15), PRIMARY KEY (SEQ_NAME))
INSERT INTO SEQUENCE(SEQ_NAME, SEQ_COUNT) values ('SEQ_GEN', 0)
CREATE TABLE SEQUENCE (SEQ_NAME VARCHAR(50) NOT NULL, SEQ_COUNT DECIMAL(15), PRIMARY KEY (SEQ_NAME))
INSERT INTO SEQUENCE(SEQ_NAME, SEQ_COUNT) values ('SEQ_GEN', 0)

more /tmp/dropfoo.sql
DROP TABLE EMPLOYEE
DELETE FROM SEQUENCE WHERE SEQ_NAME = 'SEQ_GEN'

By default, the scripts are generated in glassfish/domains/domain1 directory. In this case, an EclipseLink-specific property to identify the base location of the generated files is specified.

As TOTD #187 explains, you can bundle DDL and DML scripts to generate and populate the database. Are you ready to test drive JPA 2.1 implemented using EclipseLink 2.5 in GlassFish 4 ?

JPA 2.1 Public Review specification has been available for a few days now. The Appendix A in the specification provide revision history in case you want to focus on the newly added features only.  If you are a JUG member, you may consider adopting this JSR and provide feedback!

Wednesday Nov 21, 2012

JPA 2.1 Schema Generation (TOTD #187)

UPDATED: May 24, 2012

JPA 2.1 specification is now final and can be download from here. The Reference Implementation is integrated in GlassFish 4 Promoted Builds (soon to be final). The Schema Generation property names have changed since the blog was originally published and is now updated in the table below.

Blog from Nov 11, 2012

This blog explained some of the key features of JPA 2.1 earlier. Since then Schema Generation has been added to JPA 2.1. This Tip Of The Day (TOTD) will provide more details about this new feature in JPA 2.1.

Schema Generation refers to generation of database artifacts like tables, indexes, and constraints in a database schema. It may or may not involve generation of a proper database schema depending upon the credentials and authorization of the user. This helps in prototyping of your application where the required artifacts are generated either prior to application deployment or as part of EntityManagerFactory creation. This is also useful in environments that require provisioning database on demand, e.g. in a cloud.

This feature will allow your JPA domain object model to be directly generated in a database. The generated schema may need to be tuned for actual production environment. This usecase is supported by allowing the schema generation to occur into DDL scripts which can then be further tuned by a DBA.

The following set of properties in persistence.xml or specified during EntityManagerFactory creation controls the behaviour of schema generation.

Property Name
Purpose
Values
javax.persistence.schema-generation.database.action
Specifies the action to be taken by the persistence provider with regard to the database artifacts Per.book "none", "create", "drop-and-create", "drop"
javax.persistence.schema-generation.scripts.action
Specifies which scripts are to be generated by the persistence provider Per.book "none", "create", "drop-and-create", "drop"
javax.persistence.schema-generation.create-source
javax.persistence.schema-generation.drop-source
Specifies whether the creation/dropping of database artifacts is to occur on the basis of the object/relational mapping metadata, DDL script, or a combination of the two.
"metadata", "script", "metadata-then-script", "script-then-metadata"
javax.persistence.schema-generation.create-database-schemas
Specifies whether the persistence provider is to create the database schema(s) in addi- tion to creating database objects such as tables, sequences, constraints, etc.
"true", "false"
javax.persistence.schema-generation.scripts.create-target
javax.persistence.schema-generation.scripts.drop-target
If scripts are to be generated, controls target locations for writing of scripts. Writers are pre-configured for the persistence provider. Need to be specified only if scripts are to be generated.
java.io.Writer (e.g. MyWriter.class) or URL strings
javax.persistence.database-product-name,
javax.persistence.database-major-version, javax.persistence.database-minor-version
Needed if scripts are to be generated and no connection to target database. Values are those obtained from JDBC DatabaseMetaData.

javax.persistence.schema-generation.scripts.create-script-source
javax.persistence.schema-generation.scripts.drop-script-source
Specifies locations from which DDL scripts are to be read. Readers are pre-configured for the persistence provider.
java.io.Reader (e.g. MyReader.class) or URL strings
javax.persistence.schema-generation.connection
JDBC connection to be used for schema generation

javax.persistence.sql-load-script-source
Specifies location of SQL bulk load script.
java.io.Reader (e.g. MyReader.class) or URL string

Section 11.2 in the JPA 2.1 specification defines the annotations used for schema generation process. For example, @Table, @Column, @CollectionTable, @JoinTable, @JoinColumn, are used to define the generated schema. Several layers of defaulting may be involved. For example, the table name is defaulted from entity name and entity name (which can be specified explicitly as well) is defaulted from the class name. However annotations may be used to override or customize the values.

The following entity class:

@Entity public class Employee {
    @Id private int id;
    private String name;
    . . .
    @ManyToOne     private Department dept; }

is generated in the database with the following attributes:

  • Maps to EMPLOYEE table in default schema
  • "id" field is mapped to ID column as primary key
  • "name" is mapped to NAME column with a default VARCHAR(255). The length of this field can be easily tuned using @Column.
  • @ManyToOne is mapped to DEPT_ID foreign key column. Can be customized using JOIN_COLUMN.

In addition to these properties, couple of new annotations are added to JPA 2.1:

  • @Index - An index for the primary key is generated by default in a database. This new annotation will allow to define additional indexes, over a single or multiple columns, for a better performance. This is specified as part of @Table, @SecondaryTable, @CollectionTable, @JoinTable, and @TableGenerator. For example:

    @Table(indexes = {@Index(columnList="NAME"), @Index(columnList="DEPT_ID DESC")})
    @Entity public class Employee {
        . . .
    }

    The generated table will have a default index on the primary key. In addition, two new indexes are defined on the NAME column (default ascending) and the foreign key that maps to the department in descending order.
  • @ForeignKey - It is used to define foreign key constraint or to otherwise override or disable the persistence provider's default foreign key definition. Can be specified as part of JoinColumn(s), MapKeyJoinColumn(s), PrimaryKeyJoinColumn(s). For example:

    @Entity public class Employee {
        @Id private int id;
        private String name;

        @ManyToOne
        @JoinColumn(foreignKey=@ForeignKey(foreignKeyDefinition="FOREIGN KEY (MANAGER_ID) REFERENCES MANAGER"))
        private Manager manager;
        . . .
    }

    In this entity, the employee's manager is mapped by MANAGER_ID column in the MANAGER table. The value of foreignKeyDefinition would be a database specific string.

A complete replay of Linda's talk at JavaOne 2012 can be seen here (click on CON4212_mp4_4212_001 in Media).

These features will be available in GlassFish 4 promoted builds in the near future. The development in EclipseLink is tracked here.

JPA 2.1 will be delivered as part of Java EE 7. The different components in the Java EE 7 platform are tracked here.

JPA 2.1 Expert Group has released Early Draft 2 of the specification. Section 9.4 and 11.2 provide all details about Schema Generation. The latest javadocs can be obtained from here. And the JPA EG would appreciate feedback.

About

profile image
Arun Gupta is a technology enthusiast, a passionate runner, author, and a community guy who works for Oracle Corp.


Java EE 7 Samples

Stay Connected

Search

Archives
« April 2014
SunMonTueWedThuFriSat
  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
   
       
Today