Also, the source code used for the demonstration later on this tutorial can be found here : http://sourceforge.net/projects/syshex/ . It is simply a NetBeans project with the basic classes that we'll modify later on the Tutorial to check stuff.

Right, lets get down to business. In a relational database  tables can bear associations between each other, in JPA these associations are can be mapped onto the Entity Beans in order to represent the database schema. This is done by annotating reference attributes to other Entity Beans. There are 4 types of relationships :

• One to Many
• Many to One
• Many to Many
• One to One

Bidirectional and Unidirectional

These relationship types can be either Bidirectional or Unidirectional. The basic difference between Bidirectional and Unidirectional is that in a Bidirectional relationship, both Entities contain annotated reference attributes between each other and in a Unidirectional relationship only one of the Entity Beans references the other.

Owning Side

Any relationship has an owning side. This is what determines the updates to the relationship in a database. In the case of a Bidirectional relationship, one of the Entity Beans is always the owning side and the other side is called the inverse side. In a Unidirectional relationship, because only one of the Entity Beans in the relationship bears reference to the other, that Entity is the owning side of the relationship and there is no inverse. In One-to-Many and Many-to-One relationships, the Many part of the relationship is always the Owning side.

One To Many

So, for our example lets take two tables, one called Company and the other called Employee. The MySQL Workbench model file can be found with the sources of this tutorial, still it looks like this:

This is the SQL that generates this schema :

 CREATE  TABLE IF NOT EXISTS `jpatutorial2`.`company` (
   `idcompany` INT NOT NULL AUTO_INCREMENT ,
   `name` VARCHAR(45) NOT NULL ,
   `address` VARCHAR(45) NOT NULL ,
   PRIMARY KEY (`idcompany`) )
 ENGINE = InnoDB;

 CREATE  TABLE IF NOT EXISTS `jpatutorial2`.`employee` (
   `idemployee` INT NOT NULL AUTO_INCREMENT ,
   `company` INT NOT NULL ,
   `name` VARCHAR(45) NOT NULL ,
   `phone` VARCHAR(45) NOT NULL ,
   PRIMARY KEY (`idemployee`) ,
   INDEX `fk_employee_company` (`company` ASC) ,
   CONSTRAINT `fk_employee_company`
     FOREIGN KEY (`company` )
     REFERENCES `jpatutorial2`.`company` (`idcompany` )
     ON DELETE NO ACTION
     ON UPDATE NO ACTION)
 ENGINE = InnoDB;

Notice that in our little example the Foreign Key in the employee table is Not Null. So, because Employee is the Many part of this One-To-Many relationship, the EmployeeEntity class will be the owner of the relationship. This means that EmployeeEntity references only one CompanyEntity and that that reference field is annotated with the @ManyToOne annotation. The CompanyEntity class is the inverse of this One-To-Many relationship which means that it references many EmployeesEntities (a collection or list of EmployeeEntity), and that collection is annotated with the @OneToMany annotation. The following bit of code can be found on the EmployeeEntity class and exemplifies what has been said:

  @ManyToOne(optional = false)
  @JoinColumn(name = "company", referencedColumnName = "idcompany")
  private CompanyEntity company;

And this bit on the CompanyEntity class explains the inverse bit:

  @OneToMany(cascade = CascadeType.ALL, mappedBy = "company")
  private Collection<EmployeeEntity> employeeCollection;

These two bits of code make this a One-to-Many / Many-to-One bidirectional relationship because both sides of the relationship have references to the other side.

@ManyToOne

The ManyToOne annotation is used to define a single value association with another entity bean. Because the reference field is defined as a CompanyEntity object called company there is no need to specify further on this annotation which class type is the entity target, this is because it can be inferred. If this was not the case, as if for example the reference field was of type Object:

 private Object company;

In this case the annotation element targetEntity should be used in order to let the Entity Manager know which type of object this Entity has a relation to:

 @ManyToOne(optional = false, targetEntity=CompanyEntity.class)

Other more important and more regularly used elements of the ManyToOne annotation are both cascade, fetch, and optional. The optional element is used to indicate whether this reference can be null or not. The default value is true, and if it is defined as false then the relationship in the database schema must be defined as not-null. The fetch element is used to indicate how the Entity Manager should retrieve the referenced object of this relationship. The two possible values are FetchType.EAGER and FetchType.LAZY, with eager being the default. This element is of particular importance due to its usefulness when dealing with performance and small amounts of memory because it can avoid the initialization of unneeded large objects (imagine a relationship to an Object containing a large byte[] corresponding to a file), and avoid the extra database queries and data transference. It is usually used more on the OneToMany annotation due to the large amount of Object that can get created from retrieving the One side of the relationship. The cascade element of this annotation is used to specify the operations that must be cascaded to the elements of the association. The possible options are as defined in the CascadeTypeenum with the default being that no operations are cascaded by omition of the cascade element:

 public enum CascadeType { ALL, PERSIST, MERGE, REMOVE, REFRESH, DETACH};

The Alloption means the combination of all the remaining options available. We will discuss more on this later on this tutorial. This element is also of particular importance on the OneToMany annotation because it will allow persistence of data from the inverse side of the relationship.

@JoinColumn

The @JoinColumnannotation is used to specify a column on the database table for the relationship. So, in our example, in the EmployeeEntity bean we got the following:

 @JoinColumn(name = "company", referencedColumnName = "idcompany")

And in the SQL to generate the Employee table we got:

 INDEX `fk_employee_company` (`company` ASC) ,
   CONSTRAINT `fk_employee_company`
     FOREIGN KEY (`company` )
     REFERENCES `jpatutorial2`.`company` (`idcompany` )
     ON DELETE NO ACTION
     ON UPDATE NO ACTION)

The name element of the @JoinColumn annotation defines the name of the Foreign Key (FK) column. In this case, the name of the FK column is "company" as defined in the constraint.

The referencedColumnName element of the @JoinColumn annotation is used to define the column in the referenced table for the relationship, which is our case is "idcompany", which is the Primary Key (PK) of the referenced table. This means that it can be omitted here because the default value of referencedColumnName is the PK of the referenced table, which is discovered by looking at the table of the target Entity.

There are many other element options available for this annotation and one particularity about them is that they are all concerning the name element of the @JoinColumn. Other elements are nullable **(if the FK column is nullable) , insertable (if the FK column is to be insertable or generated), unique (if the FK column is unique, defaults to false, but it the FK column is the PK of the referenced table it is not necessary to set as true), table (the name of the table of the reference that contains the column), columnDefinition** (for generating the DLL of the column).

@OneToMany

On the CompanyEntity class we use the @OneToMany annotation in the following way:

 @OneToMany(cascade = CascadeType.ALL, mappedBy = "company")
 private Collection<EmployeeEntity> employeeCollection;

The @OneToMany annotation is used to define a multi-value association to a Collection of Entities.  Because the relationship we are creating is bidirectional (because references exist on both sides of the relationship) the annotation element mappedBy MUST be used to specify the field that exists on the referenced entity which is the owner of the relationship.

The other possible annotation elements that can be used are cascade, fetch and targetEntity, which work exactly as explained for the ManyToOne annotation and the element orphanRemoval which is defaulted to false. The orphanRemoval functionality is intended for entities that are privately owned by the parent entity and will cause a remove operation to be propagated to those child entities without the need to use the cascade type remove to make it so.

Bear in mind that having this side of the relationship with the element cascade as ALL has several implications with the working of the code itself and the management of the entity beans. This will be shown in a bit.

And that is it! This is basically most of what is needed to know about a Bidirectional  One-To-Many Relationship but for more details, specially with concerns about default behaviors and other not so common characteristics please do check the JPA 2 Spec (JSR-317) which is in the references at the end of this tutorial.

Obviously this wouldn't be complete without some testing and demonstration of the topics just discussed here! So lets jump right into that:

Seeing it working

So for starters, all the code for this project can be found at : http://sourceforge.net/projects/syshex/ . If you haven't download it yet, go there, download it (the distribution file should be called _ JPATutorial2-src-v.X.Y.zip_ or tar.bz2 or checkout the source from SVN) and open it with NetBeans (I use NetBeans 6.7 for this). Also, there should be a database configured on your test box, the Schema MySQL Workbench file can be found inside the distribution in a folder called model.

Apply the model to your database, open the NetBeans project and just dive right into the  persistence.xml file. Add the following property line there:

 <property name="eclipselink.jdbc.driver" value="com.mysql.jdbc.Driver"/>
 <property name="eclipselink.jdbc.url" value="jdbc:mysql://localhost:3306/jpatutorial2"/>
 <property name="eclipselink.logging.level" value="FINE" />
 </properties>

This property will help us view what is actually being done at the database level. You could configure the database to log all SQL queries if you would like, I rather do it this way cause I'll also get verbose output from the Entity Manager that actually help solve loads of problems.

Also, adjust the remaining properties of the persistence.xml file to fit the MySQL configuration in use at your box.

Now go for the Test Packages and open the only JUnit file there: OneToManyTesting.java . This file has two tests configured in it but I'm not actually using any asserts there to validate the correctness of the Tests, but instead just looking to see if the operations return exceptions (a Fail) or if all operations on the method execute without exception. While on the IDE with this file focused, to execute the JUnit tests you should press Ctrl-F6 which should open the Test Results tab and the Output tab.

OK lets do it then, run the JUnit tests. Because we have just set the logging level to FINE the Output tab will be filled with logging stuff.  So all went well hopefully.

Lets go ahead and delete testCreateCompany() test method (or just comment the @Test annotation) and run it again. The output of the log should show something like this (I trimmed a bit of the beginning of each line of the log) :

 // ------------------- FIRST BIT -------------------------
 Thread(Thread[main,5,main])--INSERT INTO jpatutorial2.company (address, name) VALUES (?, ?)        bind = [Av. 5 October, Lisbon, JBay Solutions]
 Thread(Thread[main,5,main])--SELECT LAST_INSERT_ID()
 Thread(Thread[main,5,main])--INSERT INTO jpatutorial2.employee (name, phone, company) VALUES (?, ?, ?)
         bind = [Rui Pereira, 23456789, 3]
 Thread(Thread[main,5,main])--SELECT LAST_INSERT_ID()
 // ------------------- SECOND BIT -------------------------
 Thread(Thread[main,5,main])--DELETE FROM jpatutorial2.employee WHERE (idemployee = ?)
         bind = [2]
 Thread(Thread[main,5,main])--DELETE FROM jpatutorial2.company WHERE (idcompany = ?)
         bind = [3]

In the code that we are using the first bit of the log corresponds to :

 em.persist(c);
 em.flush();

While the second bit of the log corresponds to :

 em.remove(c);
 em.getTransaction().commit();

Notice that in relation to the first bit of the log we just persisted one object, a CompanyEntity object that was new (check previous tutorial for Entity Lifecycle). There is another entity bean on the code, an EmployeeEntity object created but never persisted. The reason why in the first bit of logging, corresponding to the em.persist(c) statement, the two entities were persisted on the database is not magic, DOES NOT HAPPEN BY DEFAULT, and is in every way related the following:

1. both objects were made to reference each other (therefore creating a valid relationship).

2. and to the way these two Entities are annotated (cascading)

Creating a valid relationship

Concerning the first bullet point: both objects were made to reference each other (therefore creating a valid relationship) :

 // part 1
 e1.setCompany(c);
 // part 2
 c.getEmployeeCollection().add(e1);

So, in part one we set CompanyEntity c as the company of EmployeeEntity** e1**.

In part two we set a newly created Collection (a Vector) called a, which contains EmployeeEntity e1, as the Employee Collection of Company c.

One could ask: Is it necessary for both the Entity Objects to reference each other, could we not just make one reference the other and be done with it? Well.... you shouldn't. JPA 2 Spec states in page 42 the following:

Note that it is the application that bears responsibility for maintaining the consistency of run-time relationships- for example, for insuring that the “one” and the “many” sides of a bidirectional relationship are consistent with one another when the application updates the relationship at runtime.

Basically, the application should maintain consistency of run-time relationships, not the Entity Manager, and there is good reason for that: If only one side of the bidirectional relationship has a reference to the other side of the relationship then at run-time both Entities tell a different story about their relationship and ... the Entity Manager can't quite figure out what is it supposed to do: believe in one or the other Entity? Well, it believes the one that it is trying to persist which leads to the other entity to be inconsistent and require a refresh(). More on this later.

If for example we were to comment the following line :

   
     //e1.setCompany(c);
 

The log would tell a different story altogether:

 Exception [EclipseLink-4002] (Eclipse Persistence Services - 2.3.0.v20110604-r9504): org.eclipse.persistence.exceptions.DatabaseException
 Internal Exception: com.mysql.jdbc.exceptions.jdbc4.MySQLIntegrityConstraintViolationException: Column 'company' cannot be null
 Error Code: 1048
 Call: INSERT INTO jpatutorial2.employee (name, phone, company) VALUES (?, ?, ?)
         bind = [Rui Pereira, 23456789, null]

So, exception because the field cannot be Null.

Now, if we leave e1.setCompany(c); uncommented (so, undo last change to the code) and now comment the following:

 //c.getEmployeeCollection().add(e1);

And now execute the JUnit test what happens is that only the CompanyEntity c gets created. The Entity Manager em is called to persist c and has no knowledge of e1 being related (because it is only looking at c since it was the object that was requested to be persisted) and does not persist e1 and only persist c.

Now for the interesting bit: What about if we leave everything unchanged (so uncomment c.getEmployeeCollection().add(e1); ) and instead of persisting CompanyEntity c we go all creative and persist EmployeeEntity e1 instead? Well... that leads us to the second point stated above: the way these two Entities are annotated (cascading)

But first let us test it anyway by doing the following changes:

 //em.persist(c);
 em.persist(e1);
 em.flush();

When we run it we get :

 Testcase: testCreateCompanyWithEmployee(com.syshex.tutorials.jpa2.tut2.OneToManyTesting):        Caused an ERROR
 During synchronization a new object was found through a relationship that was not marked cascade PERSIST: com.syshex.tutorials.jpa2.tut2.entity.CompanyEntity@1c286e2.

An Error.

Relationship Cascading

So, as expected, the way the Entities were designed influences a lot of the behavior that we'll get when using them! This is of no surprise I expect. One particular detail of this relationship makes persisting c generate an automatic persistence of e1 and makes persisting e1 fail, that detail the way the Cascades were defined for each side of the relationship:

On the CompanyEntity class we apply CascadeType.ALL to the relationship :

 @OneToMany(cascade = CascadeType.ALL, mappedBy = "company")
 private Collection<EmployeeEntity employeeCollection;

On the EmployeeEntity class we do not define the type of cascade to apply and therefore we default to no cascading:

 @ManyToOne(optional = false)
 @JoinColumn(name = "company", referencedColumnName = "idcompany")
 private CompanyEntity company;

But to validate that our train of though is correct, let us modify the EmployeeEntity class and define, for example, the cascading as CascadeType.PERSIST just like so:

 @ManyToOne(optional = false, cascade=CascadeType.PERSIST)
 @JoinColumn(name = "company", referencedColumnName = "idcompany")
 private CompanyEntity company;

and now we execute again the JUnit test class. What we get is the persistence of both e1 and c on the database, just like expected:

 Thread(Thread[main,5,main])--INSERT INTO jpatutorial2.company (address, name) VALUES (?, ?)
         bind = [Av. 5 October, Lisbon, JBay Solutions]
 Thread(Thread[main,5,main])--SELECT LAST_INSERT_ID()
 Thread(Thread[main,5,main])--INSERT INTO jpatutorial2.employee (name, phone, company) VALUES (?, ?, ?)
         bind = [Rui Pereira, 23456789, 10]
 Thread(Thread[main,5,main])--SELECT LAST_INSERT_ID()
 Thread(Thread[main,5,main])--DELETE FROM jpatutorial2.employee WHERE (idemployee = ?)
         bind = [3]
 Thread(Thread[main,5,main])--DELETE FROM jpatutorial2.company WHERE (idcompany = ?)
         bind = [10]

Now lets get creative and if we set both sides of the relationship with CascadeType.ALL and now do the following :

 /* c.getEmployeeCollection().add(e1); */

 //em.persist(c);
 em.persist(e1);
 em.flush();

So, we only keep the e1.setCompany(c) association because it cannot be null and we persist now from the inverse. Basically we do not keep both sides of the relationship consistent. We execute and we get :

 Thread(Thread[main,5,main])--INSERT INTO jpatutorial2.company (address, name) VALUES (?, ?)
         bind = [Av. 5 October, Lisbon, JBay Solutions]
 Thread(Thread[main,5,main])--SELECT LAST_INSERT_ID()
 Thread(Thread[main,5,main])--INSERT INTO jpatutorial2.employee (name, phone, company) VALUES (?, ?, ?)
         bind = [Rui Pereira, 23456789, 16]
 Thread(Thread[main,5,main])--SELECT LAST_INSERT_ID()
 Thread(Thread[main,5,main])--DELETE FROM jpatutorial2.company WHERE (idcompany = ?)
         bind = [16]
 Thread(Thread[main,5,main])--SELECT 1
 Thread(Thread[main,5,main])--Exception [EclipseLink-4002] (Eclipse Persistence Services - 2.3.0.v20110604-r9504): org.eclipse.persistence.exceptions.DatabaseException
 Internal Exception: com.mysql.jdbc.exceptions.jdbc4.MySQLIntegrityConstraintViolationException: Cannot delete or update a parent row: a foreign key constraint fails (`jpatutorial2/employee`, CONSTRAINT `fk_employee_company` FOREIGN KEY (`company`) REFERENCES `company` (`idcompany`) ON DELETE NO ACTION ON UPDATE NO ACTION)
 Error Code: 1451
 Call: DELETE FROM jpatutorial2.company WHERE (idcompany = ?)
         bind = [16]
 Query: DeleteObjectQuery(com.syshex.tutorials.jpa2.tut2.entity.CompanyEntity@3f96ee)

What happens is: both entries get inserted on the database but now CompanyEntity c is detached and outdated and requires being refreshed so that em.remove(c) can be executed:

 //em.persist(c);
 em.persist(e1);
 em.flush();
 em.refresh(c);

By refreshing the Entity object and making it managed it can now be used on the Entity Manager and the logs produce no errors.

Hope this shared some light on how things work underneath all the code of the One-To-Many/Many-To-One relationships and helps anyone.

References

Java Persistence Api 2 Specification

EclipseLink Properties

At some point I decided that I would write a few tutorials on JPA. Some time has passed since and now I'm actually doing it. Use the comments section for corrections if you find any problems or errors, or if you would just like to leave a kind word!

This is the first tutorial of (what I hope) a series of tutorials that focus on different parts of JPA, Entity Beans and related stuff. A few assumptions are made, like basic knowledge of SQL and relational databases, what an EJB is and where does it run, Unit Testing, an IDE is setup (like NetBeans) , a MySQL database is setup and basic knowledge on how to use it, and stuff like that.

This tutorial will serve as the setup for the following tutorials. It will provide background knowledge of what JPA is, what it does, how to create a basic Entity Beans to interact with the database, how to test these Beans, etc.

Simply understanding some basic stuff that is explained here, such as Entity Lifecycle and Entity Manager contexts, will save a developer a lot of work when trying to write something more advanced!

On the following tutorials more advanced topics such as relationships will be covered.

For this tutorial EclipseLink, JUnit and MySQL are needed, so if you are missing any of these this is the time to go and get them:

• EclipseLink

• MySQL

• JUnit

I'll also be using MySQL WorkBench to visually create the database structure, the IDE used is irrelevant since the tutorial will be more focused on the source code and basic knowledge side of things.

I also created a NetBeans Project with all the source code used on this Tutorial. You can Download it Here but to properly use it you'll need to place the  EclipseLink Jars and MySQL connector Jar and Persistence Jar inside the correct Lib folder inside the project. You'll also have to add these libraries to the Testing Libraries of the project.

The Database

So, lets start the show! The name of the schema to be used in MySQL is "mydb", but if you decide to use a different one just remember to change any reference to mydb in this tutorial to the name of your Schema. First let us start by creating the following table in MySQL:

The SQL for that table is like so :

CREATE TABLE IF NOT EXISTS `mydb`.`company` (
`idcompany` INT NOT NULL AUTO_INCREMENT ,
`name` VARCHAR(45) NOT NULL ,
`country` VARCHAR(45) NOT NULL ,
`privat` TINYINT(1) NOT NULL DEFAULT 0 ,
`ownername` VARCHAR(45) NULL ,
`numberemployees` INT NOT NULL DEFAULT 0 ,
`income` DOUBLE NOT NULL DEFAULT 0.0 ,
PRIMARY KEY (`idcompany`) )
ENGINE = InnoDB;`</blockquote>

This table has and ID column, which is auto incremental, a  few columns that are basic text, a column called privat that is a boolean and some ints and doubles.

The Persistence Unit

Now inside the IDE configure a new project to use J2EE Persistence (JPA) and Enterprise JavaBeans. Inside the META-INF folder there should be a file called persistence.xml, if there is none then create one. It should look like this:

<?xml version="1.0" encoding="UTF-8"?>
<persistence xmlns="http://java.sun.com/xml/ns/persistence" version="2.0">
    <persistence-unit name="testPU" transaction-type="RESOURCE_LOCAL">
        <provider>org.eclipse.persistence.jpa.PersistenceProvider</provider>
        <exclude-unlisted-classes>false</exclude-unlisted-classes>
        <properties>
            <property name="j**avax.persistence.jdbc.driver**" value="com.mysql.jdbc.Driver"/>
            <property name="**javax.persistence.jdbc.url**" value="jdbc:mysql://localhost:3306/mydb"/>
            <property name="**javax.persistence.jdbc.user**" value="root"/>
            <property name="**javax.persistence.jdbc.password**" value="root"/>
        </properties>
    </persistence-unit>
</persistence>

The persistence.xml file indicates that there is only one Persistence Unit, which we called testPU, the transaction type for this PU is RESOURCE_LOCAL. There are two valid types of transaction:

• JTA

• RESOURCE_LOCAL

What these options mean is: If one selects RESOURCELOCAL then the transactions will be managed by the JPA Provider Implementation in use. If JTA is specified then the transactions will be managed by the Application Server the application will run in. Another way of looking at this is that if one only wants to have JPA transactions then RESOURCELOCAL is a good choice. If one would like the transactions to contain other resources other than JPA, like EJBs, JCA or JMS then JTA is the correct choice.

When defining a Persistence Unit a list of Entity Beans to be managed can also be included, or one can simply do : false, which will make all Entity Beans in the archive managed by the PU.

The remaing properties in the PU are pretty straight forward to understand. Make them the configurations of your MySQL database and Schema. Other properties for EclipseLink can be found here: Properties JPA2

The Entity Bean

An Entity Bean is a "lightweight persistent domain object" (JPA Sepc) , what this means is that an Entity object represents a set of attributes of an entry on the database.  It allows a developer to create, access and modify entries on a Database in an Object Oriented fashion like if they were simple POJOs.

The Entity Bean is therefore a Java Object that simply has to follow a few rules that are not that difficult. Our Entity Bean will be called CompanyEntity.Java , and it was created inside the package : com.jbaysolutions.testing.entity . Feel free to change it to a different package.

I've split the file in several sections here so that I can go through and explain what is going in each section. The complete file can be found here.

The first part of the file goes like so :

 package com.jbaysolutions.testing.entity;
 import javax.persistence.*;
 import java.io.Serializable;

 @Entity
 @Table(name = "company")
 public class CompanyEntity implements Serializable {

@Entity

A Java object, to be considered an Entity Bean must have the Entity annotation ( @Entity ) on the class or be denoted on the ejb-jar.xml file. In our example we use the @Entity annotation.  This annotation and the remaining ones that characterise an Entity Bean can be found inside the javax.persistence package.

Also, an Entity Bean must be a top level class, it must not be final, nor the persistent elements that it contains.

@Table

The @Table annotation is used to specify which table, from which catalogue and which schema this Entity Bean is representing. In this case we simply use the name attribute to define the table name.

The Entity Bean can also be Serializable, which is very handy when there is the need to pass this object somewhere else, like for example as the return of a web service method or EJB.

The next bit of the class looks like this :

     @Id
     @GeneratedValue(strategy = GenerationType.IDENTITY)
     @Column(name = "idcompany")
     private Integer idcompany;

@Id

In this section an attribute called idcompany is defined as an Integer object which is the Primary Key of the created table. We use the @Id annotation to identify this attribute as the ID of the Entity Bean. An Entity Bean MUST have an Id, which can be a single attribute or several attributes ( composite primary key). The Id of the Entity Bea MUST be serializable.

So this ID will be used by Entity Manager to uniquely identify the entity in its persistence context. It is also a part of the JPA spec that an Application MUST NOT modify the value of the Primary Key or any of the values of a Composite Primary Key. It states that the behaviour is undefined if this occurs, which basically means that it might work but if the JPA provider is changed then the behaviour might not be the same across all Providers and therefore the application behaviour might change. In other words: Don't do it!

Composite Primary Keys will be explained in a later tutorial.

@GeneratedValue

This annotation provides the strategy to be used for the generation of the Id attributes of the Entity Bean. It is implementation specific and its behaviour is not defined on the specification. There are 4 possible choices :

• auto

• identity

• table

• sequence

For this example we are using IDENTITY due to the fact that MySQL supports identity columns. If we were using Oracle which supports Sequence objects, we would be using the SEQUENCE choice and would define which sequence was to be used for the generation of the Ids. The TABLE option can be used in any kind of database and means that JPA will use another table for the Ids to be used, the new table will have a column of the same type the Id has and each row will correspond to a specific Id on the original table.

Option AUTO will make JPA decide itself what is the best strategy to use, in case of EclipseLink the default choice will be TABLE.

@Column

The @Column annotation informs JPA which column this attribute corresponds to and other constraints of the attribute such has length and precision. If the name of the column is the same as the name of the attribute then there is no need to specify the "name" property of the annotation.

The next section of code is the definition of the remaining columns:

     @Column(name = "name")
     @Basic(optional = false)
     private String name;

     @Column(name = "country")
     @Basic(optional = false)
     private String country;

     @Column(name = "privat")
     @Basic(optional = false)
     private Boolean privat = false;

     @Column(name = "ownername")
     @Basic(optional = true)
     private String ownerName;

     @Column(name = "numberemployees")
     @Basic(optional = false)
     private int numberEmployees = 0;

     @Column(name = "income")
     @Basic(optional = false)
     private double income = 0.0;

@Basic

The Basic annotation can be applied to any persistent attribute of the Entity Bean as long as it is a primitive, a primitive wrapper or Serializable object. It is optional and cannot be used for Id attributes. Through the use of @Basic annotation we can specify the type of fetch to be used and whether the attribute is optional or not.

The next section of code is concerning the Constructors of the Entity Bean:

     public CompanyEntity() {
     }

     public CompanyEntity(String name,
                          String country,
                          Boolean privat,
                          String ownerName,
                          int numberEmployees,
                          double income) {
         this.name = name;
         this.country = country;
         this.privat = privat;
         this.ownerName = ownerName;
         this.numberEmployees = numberEmployees;
         this.income = income;
     }

Entity Bean Constructors

According to the JPA Specification the Entity Bean must have a no-args constructor defined. It can have many other constructors, but the no-args must be defined and must be either Public or Protected. In our example we have two, for no particular reason.

The remaining definition of the Entity Bean is basically following the Javabeans conventions for the getter and setter methods for the attributes.

Testing the Entity Bean

Usually all operations regarding the Entity Beans would be performed inside some EJB that would take care of all the business logic and persistence related parts. That will be covered in the next tutorial. In this one we'll be using JUnit testing, which is a good practice, specially for later once this exercise gets expanded to make use of EJBs.

So by using a JUnit test class all operations can be simulated with the Entity Bean that was just created. The JUnit class that we'll use can be found here and I'll go through it section by section and explain what is happening.

 public class CompanyEntityTest {

     private static EntityManager em = null;

     @BeforeClass
     public static void setUpClass() throws Exception {
         if (em == null) {
             em = (EntityManager) Persistence.
                       createEntityManagerFactory("testPU").
                       createEntityManager();
         }
     }

This first section of the JUnit basically performs the setup of the Entity Manager that will be used for the remaining parts of the Class.  The @BeforeClass annotation basically means that this method will be run once before any of the test methods of the Class. The test methods will be marked with the @Test annotation, as you will see next. More information regarding @BeforeClass can be found Here and it is beyond the scope of this tutorial.

Inside this method the Entity Manager object is created using a Factory. This factory takes as an argument the name of the Persistence Unit that is to be used. Since we only have one created on the persistence.xml file, we'll use that one.

 @Test
 public void testAllOps(){
     // Start a transaction
     em.getTransaction().begin();

     // ------------  Create a Company C1 ---------
     CompanyEntity c1 = new CompanyEntity();
     c1.setCountry("Portugal");
     c1.setIncome(1000000.00);
     c1.setName("JBay");
     c1.setNumberEmployees(200);
     c1.setOwnerName("The Dude");
     c1.setPrivat(true);
     // At this Point the Entity does not have a
     // Persistent Identity and is not associated
     // with a persistent Context
     em.persist(c1); // Persist the Entity
     em.flush();
     // At this point the Entity has a Persistent
     // Identity and is associated with a Persistent
     // context.

     // ------------  Create a Company C2 ---------
     CompanyEntity c2 = new CompanyEntity();
     c2.setCountry("US");
     c2.setIncome(1000000000.00);
     c2.setName("Oracle");
     c2.setNumberEmployees(9000);
     c2.setOwnerName("Who?");
     c2.setPrivat(true);
     em.persist(c2);
     em.flush();

     System.out.println("Company 1 Id : " + c1.getIdcompany());
     System.out.println("Company 2 Id : " + c2.getIdcompany());

The method testAllOps is the one that will be used to test all the operations. It is marked with @Test which means that it will get executed after @BeforeClass which then means that the EntityManager object "em" is already instantiated and ready for usage. Because the Persistence Unit that we are using is using transaction type RESOURCE_LOCAL we begin a transaction first of all, if it was of the type JTA it would throw an exception if we tried to manage the transaction like that.

At this point we should look at the Entity Bean Lifecycle.

Entity Lifecycle - New Entity

We then create a new Instance of the Entity Bean CompanyEntity which we call "c1".  Because when we create this new object c1 it does not contain an identity this Entity Bean is said to be "new".  Object c1 is then given a set of values for its attributes except for the Primary Key attribute.

Entity Lifecycle - Managed Entity

The Entity Manager "em" is then used to persist this object on the database. The method to be used is persist(T). If the method merge(T) would be used it would be incorrect because this method is used for update operations and not create operations. Calling the persist() method makes this Entity Bean c1 "managed" and associated with this persistence context.

The method * flush()* is called simply to synchronise the data of the Entity Bean with the database system. According to the JPA Spec the persistence provider is allowed to sync to the database system at other times other than when flush() is called but calling it ensures that the synchronisation happened at this point.

Entity Lifecycle - Removed Entity

The Entity Manager has a method called remove(T), this method is used to remove the entry related to the Id of that entity from the underlining database system. At this point, after the remove method was called on a Managed Entity Bean, that Entity Bean is said to be "removed".

The state of the object itself is exactly the same as before the remove method was called, with the difference that that entity no longer is associated with the persistence context of the Entity Manager and does not represent any entry on the database.

Entity Lifecycle - Detached Entity

A Detached Entity is an Entity that is not associated with a persistence context. It is a necessary thing for several operations and can happen in several ways, the most common ones being from detaching the entity from the persistence context and from serializing an entity or otherwise passing an entity by value.

To detach an Entity from a persistence context the method  detach() can be used on that Entity. Before doing so one must flush() the entity to ensure that changes are persisted. Associated Entities with the detached Entity are also detached is the relationship is marked with Cascade=DETACH or Cascade=ALL. The Cascade attribute will be addressed on a later tutorial when relationships between entities are covered.

If an Entity is new or already detached invoking detach() with produce no result.

There are several other nuances with Detached entities, specially regarding merging of a detached entity onto an existing persistence context. These are addressed on a later tutorial.

The next section of the JUnit file shows two searchs being performed on the persistence context:

 Query query = em.createQuery("Select c from CompanyEntity c where c.idcompany=:companyid");
 query.setParameter("companyid", c1.getIdcompany());
 CompanyEntity retrieved1 = (CompanyEntity) query.getSingleResult();
 assertSame(c1, retrieved1);

 query.setParameter("companyid", c2.getIdcompany());
 CompanyEntity retrieved2 = (CompanyEntity) query.getSingleResult();
 assertSame(c2,retrieved2);

 assertNotSame(c1,c2);
 assertNotSame(retrieved1,retrieved2);

The Query object on the above example is created using JPQL. There are other ways to create queries such as using a named query, which is a query that is defined on an Entity Bean and also queries can be created using native SQL language. In the example we use JPQL which stands for JPA Query Language, which is considered to be an Object oriented version on SQL. The example query has a Parameter called  :companyid which is set using the setParameter() method of the Query object.

The getSingleResult() method returns the unique object that matches the query. If no result is found a NoResultException is thrown. This exception does not mark the transaction for rollback. If more than one result matches the query then a NonUniqueResultException is thrown. This exception also does not mark the transaction for rollback.

Using the assertSame() method of the JUnit framework we verify that C1 and Retrieved1 are the same and also that C2 and Retrieved2 are the same. It is of crucial importance to understand this! According to the JPA2 Spec:

An EntityManager instance is associated with a persistence context. A persistence context is a set of entity instances in which for any persistent entity identity there is a unique entity instance

What this means is that there is only one copy of an Entity Bean object for each Identity inside a persistence context. So, inside a persistence context if we were to call the getSingleResult() method several times and assign its result to different variables, these would all be references to the exact same object and not different copies of similar objects.

One could test this by simply modifying the CompanyEntity object with :

 @Transient
 int random = new Random().nextInt();

 public int getRandom() {
     return random;
 }

This will generate a random integer for each Entity Object that gets created. Now, performing getSingleResult() for the same query with the same parameters on the JUnit test class assigning the result to different variables and calling getRandom() on all of those references will return the same int value, which shows that the Object is the same or that we got extremely lucky (not likely... but try it a few time to be sure).  This test could also be done by calling the hashCode() method of each object obviously and verifying that they all have the same hashcode but that would prevent the introduction of the @Transient annotation.

@Transient

The @Transient annotation is similar to the transient keyword in Java, in the sense that transient keyword means that an attribute of a class is not to be serializable, the @Transient annotation in JPA means that the Attribute is not to be persisted. Attributes annotated with @Transient are ignored by the Entity Manager and are not persisted on the Database system.

The remaining of the JUnit test class demonstrates the remaining operations already mentioned on this tutorial, such as updating of entries:

 c2.setOwnerName("No One");
 c2.setPrivat(false);
 em.merge(c2);
 em.flush();

 System.out.println("Company 2 Id : " + c2.getIdcompany());
 System.out.println("Company 2 Name : " + c2.getName());
 System.out.println("Company 2 Owner : " + c2.getOwnerName());
 System.out.println("Company 2 Private : " + retrieved2.getPrivat());

And also deleting of entries:

 em.remove(c1);
 em.remove(c2);
 // Both c1 c2 (and obviously retrieved1 and retrieved2) are removed,
 // which will happen upon commit of the Transaction
 em.getTransaction().commit();

References

Java Persistence Api 2 Specification

EclipseLink Properties