Sample Project

About the sample project provided: it is a Maven project, we do not require an App Server at this point and the database used is a MySQL database. Check the JPA2 Tutorials page for links of recommended software.

You can get the project at GitHub.

What is and Why use JPQL?

Before going into what is JPQL, lets talk about SQL. SQL is a query language used for managing data in a relational database. It an ANSI and ISO standard, but if you try running a medium to high complexity SQL query in two different relational databases from two different vendors, you are in for a big surprise. Why is that? Because some vendors create specific dialects of the SQL language.

Now imagine for a second you have a big application that you just developed and deployed, which is using a specific relational database, and for some reason you decide to migrate your data to another relational database from a different vendor. Well, if you wrote your queries in SQL, you are well advised to go and double check all of your queries for correctness against the new dialect.

JPQL to the rescue. JPQL is a query language, much like SQL (syntax wise and all that), but instead of querying over a relational database, it queries over the persistent schema of entities and relationships (which is almost the same thing, but not quite!). What this means is that, if the relational model of the new database is still represented by the schema of entities and relationships you have on your project, then your JPQL queries will be portable and will work as expected. Emphasys on Portability.

Select Statements

For our tutorial we'll use the model created for the One-To-Many Tutorial but we will extend it a bit more:

You can get the MySQL Workbench file for this from the model folder of the sample project. Along with the Workbench file there is a SQL script that creates the model and adds a few entries to it so we can test our queries:

INSERT INTO `jpa2tut-queries`.`company` (`name`, `address`, `created_year`) VALUES ('JBay Solutions', 'Somewhere in Portugal', 2009);
INSERT INTO `jpa2tut-queries`.`company` (`name`, `address`, `created_year`) VALUES ('JetBrains', 'Somewhere in Prague', 2000);
INSERT INTO `jpa2tut-queries`.`company` (`name`, `address`, `created_year`) VALUES ('Google', 'Somewhere in the US', 1998);
INSERT INTO `jpa2tut-queries`.`company` (`name`, `address`, `created_year`) VALUES ('Yahoo', 'Somewhere in the US',1994);
INSERT INTO `jpa2tut-queries`.`company` (`name`, `address`, `created_year`) VALUES ('MySQL', 'Somewhere in an Oracle Office', 1995);

Also, check the src/main/java folder of the project in order to check the Entity Objects we have. An understanding of these objects is core to understanding the JPQL code we will write next.

A Simple Select

As you can see from the previous SQL bits, we have a few entries on the company table. Lets query for the list of those entries:

SELECT c FROM CompanyEntity AS c

At this point you should be going like: Wait a second please... I understand this language!. Like said before, JPQL is very much like the regular SQL, except that we perform queries on the persistent schema of entities and relationships.

Lets run this in Java. Check the files inside the src/test/java folder of the sample project. You should be looking for the QueryTesting.java file at the method testSimpleQuery:

Query query = em.createQuery("SELECT c FROM CompanyEntity AS c");
for ( CompanyEntity ce : (List<CompanyEntity>)query.getResultList()) {
    System.out.println(" -> Company : " + ce.getName() );
}

We give it a run:

[...]
[EL Info]: connection: 2014-10-14 16:41:13.476 --ServerSession(1563886825)--file:/home/rui/projects/jpa2tut-queries/target/test-classes/_jpa2tut-test login successful
 -> Company : JBay Solutions
 -> Company : JetBrains
 -> Company : Google
 -> Company : Yahoo
 -> Company : MySQL

Simple, yes? We create a Query Object with the JPQL query and we call em.getResultList(); . We cast the result to List<CompanyEntity> , because we know that getResultList() returns a List (it does) and we also know that the query we created returns objects of CompanyEntity type.

We can also restrict the number of results being returned from the Query, by modifying the JPQL query used. Imagine we want to return all the companies that are called "JBay Solutions":

SELECT c FROM CompanyEntity AS c WHERE c.name='JBay Solutions'

And the code being (testSimpleQueryWhere method) :

Query query = em.createQuery("SELECT c FROM CompanyEntity AS c WHERE c.name='JBay Solutions'");
for ( CompanyEntity ce : (List<CompanyEntity>)query.getResultList()) {
    System.out.println(" -> Company : " + ce.getName() );
}

Give it a quick spin:

[EL Info]: connection: 2014-10-14 16:54:56.972--ServerSession(1861307614)--file:/home/rui/projects/jpa2tut-queries/target/test-classes/_jpa2tut-test login successful
 -> Company : JBay Solutions

Process finished with exit code 0

At this point one should be able to make pretty simple, but very useful queries, but some issues stand out:

• We must be constantly casting the results
• All our queries until now allow no input

Enter TypedQuery

In JPA2 a new type of Query object was introduced. The TypedQuery, which allows us to make a Query that is Typed. That is it, TypedQuery extends Query, allowing one to define straight away what is to be returned and avoid continuously Casting every single result.

Looking at our previous examples, we can modify them to use TypedQuery instead of Query by using an overloaded createQuery method from the EntityManager that also takes as a parameter the Type of the query result:

TypedQuery<CompanyEntity> query = em.createQuery("SELECT c FROM CompanyEntity AS c", CompanyEntity.class);

TypedQuery<CompanyEntity> query = em.createQuery("SELECT c FROM CompanyEntity AS c WHERE c.name='JBay Solutions'", CompanyEntity.class);

to perform the iteration now we do:

for (CompanyEntity ce : query.getResultList()) {
    System.out.println(" -> Company : " + ce.getName());
}

No casting, no nothing. For the complete code check both testSimpleTypedQuery and testSimpleTypedQueryWhere methods of the QueryTesting.java file on the test sources.

We still have the no input issue to work on.

Passing Input to the Queries

In a way, some examples we shown before could be easily modified in a way to allow inputs to be passed onto them. Check this out:

String inputName = "JBay Solutions"; 
TypedQuery<CompanyEntity> query = em.createQuery("SELECT c FROM CompanyEntity AS c WHERE c.name='" + inputName + "'", CompanyEntity.class);

Can you spot the problem with this? Well, simple, if you want to perform this query several times with different inputs, then you need to continuously re-create a new Query object. Not counting the performance impact it will have, it also leads to the JPQL not being readable at all. Imagine a query like the one presented but with several conditional expressions on the WHERE clause. What a nightmare.

To avoid these situations we have in JPQL:

• Named Parameters
• Positional Paramenters

Constructing a Query with any of these types of dynamic parameters allows a Query to be reused (and therefore avoid constant instantiation of Query objects) and makes the JPQL query much more readable.

Named Parameters

Lets look at the following example (from testSimpleTypedQueryWhereInputNamed method):

em.createQuery("SELECT c FROM CompanyEntity AS c WHERE c.name=:nameParam", CompanyEntity.class);
query.setParameter("nameParam", "JBay Solutions");

So, a named parameter is a parameter that is called out by name. It is defined using the :< param_name > notation:

• They are defined using the ":" prefix
• They are Case Sensitive
• $ and _ chars are allowed,
• ? is not allowed.
• They can be used more than once on the Query string
• They must be SET to something on execution
• There is a list of reserved identifiers that cannot be used. Some of these reserved identifiers are : SELECT , WHERE, GROUP, TRUE, and many more, but you get the gist. These reserved identifiers are case insensitive, and non can be used as a named parameter.

The named parameters are then set on the Query using the setParameter method of the Query instance:

query.setParameter("nameParam", "JBay Solutions");
for (CompanyEntity ce : query.getResultList()) {
    System.out.println(" -> Company : " + ce.getName());
}
query.setParameter("nameParam", "Google");
for (CompanyEntity ce : query.getResultList()) {
    System.out.println(" -> Company : " + ce.getName());
}

What happens if you don't set one of the parameters? You get an IllegalStateException:

[...]
[EL Info]: connection: 2014-10-14 18:30:02.302--ServerSession(822392390)--file:/home/rui/projects/jpa2tut-queries/target/test-classes/_jpa2tut-test login successful

java.lang.IllegalStateException: Query argument nameParam not found in the list of parameters provided during query execution.
    at org.eclipse.persistence.internal.jpa.QueryImpl.processParameters(QueryImpl.java:498)
    [...]

Positional Parameter

Lets look at the following example (from testSimpleTypedQueryWhereInputNumbered method):

em.createQuery("SELECT c FROM CompanyEntity AS c WHERE c.name=?1", CompanyEntity.class);
query.setParameter(1, "JBay Solutions");

A positional parameter is defined using the ?< int > notation:

• The parameters are numbered starting with 1
• Positional parameter can appear more than once in the Query string.
• The order by which they are set is irrelevant

So:

query.setParameter(1, "JBay Solutions");
query.setParameter(2, "Google");

will return the same as:

query.setParameter(2, "Google");
query.setParameter(1, "JBay Solutions");

Using Multiple Entities

Right, making JPQL queries that take into account several Entities is the next logical step. For that, take into account the following SQL script (that is part of the create-and-populate.sql file of the sample project):

INSERT INTO `jpa2tut-queries`.`employee` (`name`, `address`, `idcompany`, `birthday`) VALUES ('Rui Pereira', 'Lisbon',1 , '1981-06-27' );
INSERT INTO `jpa2tut-queries`.`employee` (`name`, `address`, `idcompany`, `birthday`) VALUES ('Gustavo Santo', 'Peniche',1, '1979-12-19');
INSERT INTO `jpa2tut-queries`.`employee` (`name`, `address`, `idcompany`, `birthday`) VALUES ('Maxim Shafirov', 'St.Petersburg, Russia',2, '1970-06-01');
INSERT INTO `jpa2tut-queries`.`employee` (`name`, `address`, `idcompany`, `birthday`) VALUES ('Valentin Kipiatkov', 'St.Petersburg, Russia',2, '1975-06-01');
[... many more entries]

This simply adds a few Employees to the previously created Companies. Now we have JBay Solutions with two employees and JetBrains with also two employees, and the remaining companies with also two employess (check file for the remaining entries).

Lets create a JPQL query that returns the employees of a particular company:

TypedQuery<EmployeeEntity> query =
    em.createQuery("SELECT employee FROM CompanyEntity AS company, EmployeeEntity as employee " +
    "WHERE company.name=:name " +
    "AND employee.company = company", EmployeeEntity.class);

Pretty simple, yes?

• On the FROM clause we define two Entities with two Identifiers
• we make use of a named parameter
• we make use of the AND logical operator

Remember we said that JPQL perform queries on the persistent schema of entities and relationships. EmployeeEntity has a ManyToOne Relationship defined to CompanyEntity, and therefore we can use that relationship in our JPQL queries. The relationship is defined like this:

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

Therefore when we in JPQL do something like employee.company = SOMETHING, we call employee.company a Path Expression, and the result for this case should be pretty obvious, because the relationship maps to only one other Entity. We'll talk a bit more about Path Expressions in a bit.

Lets give a run at testMultipleEntities1 method on the QueryTesting.java, which runs this query like this:

query.setParameter("name", "JBay Solutions");
for (EmployeeEntity client : query.getResultList()) {
    System.out.println(" -> Q1 : " + client.getName());
}

query.setParameter("name", "JetBrains");
for (EmployeeEntity client : query.getResultList()) {
    System.out.println(" -> Q2 : " + client.getName());
}

And check the results:

[EL Info]: connection: 2014-10-14 20:58:59.383--ServerSession(1268465323)--file:/home/rui/projects/jpa2tut-queries/target/test-classes/_jpa2tut-test login successful
 -> Q1 : Rui Pereira
 -> Q1 : Gustavo Santo
 -> Q2 : Maxim Shafirov
 -> Q2 : Valentin Kipiatkov

Perfect!

Now, on the other side of the relationship, we'll have a OneToMany Relationship, like this:

@OneToMany(mappedBy = "company")
private Collection<EmployeeEntity> employeeCollection;

And using that collection there on a JPQL query is also possible, but not as shown before. When we write something like this AND employee.company = company , the employee.company part as we said before is called a Path Expression, and one of the rules of Path Expressions is that it cannot be created from another Path Expression that evaluates to a collection. Lost you all there? In order words, check this next example.

Take this bit of code FROM EmployeeEntity as employee , we could create these Path Expressions :

• employee.name : Evaluates to a String
• employee.id : Evaluates to an int
• employee.address : Evaluates to a String
• employee.company : Evaluates to a Company object
• employee.company.id : Evaluates to an int
• employee.company.name : Evaluates to a String
• employee.company.address : Evaluates to a String
• employee.company.employeeCollection : Evaluates to a Collection

So you see, we created Path Expressions from other path expression in the way that employee.company.id is created from the employee.company Path Expression.

Since we have that rule of not being able to create from Path Expressions that evaluate to Collections, we can't do the following :

• employee.company.employeeCollection.id : Illegal
• employee.company.employeeCollection.name : Illegal
• employee.company.employeeCollection.address : Illegal
• employee.company.employeeCollection.company : Illegal

But Path Expressions that evaluate to Collections can be very useful in other ways. Lets give it another try at writting a JPQL query that makes use of this to achieve that same goal as the previous one:

TypedQuery<EmployeeEntity> query =
    em.createQuery("SELECT employee FROM CompanyEntity AS company, EmployeeEntity as employee " +
    "WHERE company.name=:name " +
    "AND employee MEMBER OF company.employeeCollection ", EmployeeEntity.class);

See what we did there?

• we made use of the MEMBER OF comparison operator
• and we have a working knowledge of what is a Path Expression

There are a few more rules regarding Path Expressions, but a working knowledge is quite enough. If you feel you must know these right now, please check the JPA 2 Final Spec, which can be found at the bottom of this post in the References section.

About the MEMBER OF comparison operator, there are quite a few comparison operators, like BETWEEN, IN , EMPTY, EXISTS, LIKE, IS NULL and your well known = , >, <, <>, <=, and >= .

The MEMBER OF operator

The MEMBER OF operator is used to match or NOT the existence of something in a Collection. An example if we may :

employee MEMBER OF company.employeeCollection

The employee section is a path expression that evaluates to an entity. It could evaluate to a simple value (like for example employee.id does) or an object (like employee.company), these are allowed.

The company.employeeCollection section is a path expression that will evaluate to a Collection of Employees. That is it.

To match the inexistence of something inside a Collection, we can use the NOT MEMBER OF, like this:

employee NOT MEMBER OF company.employeeCollection

The NOT is a constant in the remaing comparison operators, like we will see next.

The BETWEEN operator

Lets shift our focus now to the Company table and CompanyEntity bean. There is a field there that stores the year the Company was created. It is mapped as an Integer and cannot be Null.

For our next task we will write a JPQL query that will return the Companies that were created in 1995 or after and in 2005 or before:

em.createQuery("SELECT company FROM CompanyEntity AS company " +
"WHERE company.createdYear >= 1995 " +
"AND company.createdYear <= 2005<="" b=""> ", CompanyEntity.class);

Easy, yes? But we could use the BETWEEN operator in the following way:

"WHERE company.createdYear BETWEEN 1995 AND 2005 "

Which will return the exact same result.
Expanding on what we already know, we could actually just replace both the MIN and MAX arguments of the BETWEEN operator with named parameters and allow for them to be defined dynamically:

query = em.createQuery("SELECT company FROM CompanyEntity AS company"+
"WHERE company.createdYear BETWEEN :minimum AND :maximum ", CompanyEntity.class);
query.setParameter("minimum", 1995);
query.setParameter("maximum", 2000);

But BETWEEN can be used with other types of parameters, like Dates. Lets write a JPQL query that returns now all the Employees of any company that were born between 1979-01-01 and today:

TypedQuery query =
    em.createQuery("SELECT employee FROM EmployeeEntity AS employee"+
    "WHERE employee.birthday BETWEEN :minimum AND :maximum ", EmployeeEntity.class);
query.setParameter("minimum", "1979-01-01");
query.setParameter("maximum", new Date());

To get the exclusion of those dates, you use the NOT :

"WHERE employee.birthday NOT BETWEEN :minimum AND :maximum ", EmployeeEntity.class);

Moving on.

The LIKE operator

We know how to compare Strings, we have the regular = and <> comparison operators. Lets try them out in writing a JPQL query that returns all the companies that are named Google:

SELECT company FROM CompanyEntity AS company WHERE  company.name = 'Google'

But what about if on our database, that company was named "google" and not "Google"? Well, that query would fail, that's what.

And what if we want to return all the Companies that have "oo" (two 'o's) in their name? Well then we have to write a pattern and check which entries match that pattern.

For that we use the LIKE operator.

The LIKE works like this : on the left hand side you place a String or a path expression that evaluates to a String. On the right hand side you place a String that has a pattern to be matched.

So, if we do:

WHERE  company.name LIKE 'google'

We would get a match for companies named:

• google
• Google
• GOOGLE
• GoOgLe

In order words: 5 letter words that have the same letters in that order, but are case insensitive.

Lets write a JPQL that matches all Companies with "oo" in their name, no matter where in their name:

WHERE company.name LIKE '%oo%' 

Here we go. Now we will match :

• Google
• Yahoo
• oo.org
• Boo

The % character is a wildcard character that matches any sequence of characters, including an emply one. The other wildcard charater we have is the underscore _ which matches exactly one character.

So, if we were to write:

WHERE company.name LIKE '%oo_'

We would only match companies named like this:

• Gooa
• Goob
• oox
• ooy
• yahooa

Why? Because the _ wildcard must match exactly 1 character, whatever character it is, but it must be 1!

As with the precious operator, if we want to get all the company names that don't match that pattern, we use the NOT :

WHERE  company.name NOT LIKE '%oo%' 

And we get pretty much any company whose name doesn't have exactly two 'o's together.

The EMPTY operator

The EMPTY operator simply evaluates if Collection expressed by a path expression is empty, or NOT EMPTY.

Lets write a JPQL query that returns all the companies that have no employees:

SELECT company FROM CompanyEntity AS company WHERE company.employeeCollection IS EMPTY

The company.employeeCollection poins to a Collection of Employees. If we run this query against our test database, we get no returns, because all the companies on our DB have employees. So instead lets have a query that returns all the companies that have employees:

SELECT company FROM CompanyEntity AS company WHERE company.employeeCollection IS NOT EMPTY

And now if we run that query we get returned all the Companies in our test DB.

The NULL operator

Not that any of the operators are difficult to understand, but NULL is by far the easiest one. IS NULL is used to test if a give path expression or parameter is a NULL value , or NOT.

For completeness' sake lets write a JPQL query that returns all Employees that have their address NULL:

SELECT employee FROM EmployeeEntity AS employee WHERE  employee.address IS NULL

And now, a query that returns all the Employees that don't have their address NULL:

SELECT employee FROM EmployeeEntity AS employee WHERE  employee.address IS NOT NULL

In case you are wondering, a path expression that evaluates to a Collection cannot be NULL. It can however be EMPTY or NOT EMPTY. So, if you try something like this:

SELECT company FROM CompanyEntity AS company WHERE  company.employeeCollection IS NULL

Well... that just isn't going to work.

But there is more!

What about Subqueries? Any more comparision operators? And Update and Delete statements? What about the Criteria API?

We'll take a break here, because this post is getting big and we'll continue on the next post! We'll update this one with a link as soon as the next post comes out.

References

JPA 2 Final Spec

A reader asked : "How would one create manyToMany relationship with the same entity. Entity user can have friends (user), and can be friend to other users. With note that junction table has to have some additional columns besides user keys. How can that be achieved?"  (Thanks Felix for the feedback and question!)

So, to start of let us be clear that to follow this Tutorial you should :

1. Have a basic understanding of JPA2 , enough to create a few entities etc

2. Know how to create a Many to many relationship between two related Entities

If you have been following the Tutorials till now, then you can go right ahead and start this one. If you haven't been following but know the stuff that is fine as well. If you want to go and check them out : JPA2 Tutorials .

You'll need EclipseLink, JUnit and MySQL, so if you are missing any of these this is the time to go and get them:

• EclipseLink

• MySQL

• JUnit

Source Code for all of this can be found at Sourceforge

Lets get started

In the previous tutorial we have discussed about the* Join Table*, which is a table that has one only purpose, which is to allow the creation of a many to many relationship between two tables. This is not entirely correct, as it was pointed out by simply reading the question that was posed. The two tables can in fact be the same table, and in that case the Join Table is mapping a many to many relationship between elements of the same type.  The following diagram exemplifies:

Let us start by creating a database with these two tables. The SQL should look something like this :

 CREATE TABLE IF NOT EXISTS `jpatutorial3u1`.`person` (
  `idperson` INT NOT NULL AUTO_INCREMENT ,
  `name` VARCHAR(45) NOT NULL ,
  `phonenumber` VARCHAR(45) NULL ,
  PRIMARY KEY (`idperson`) )
 ENGINE = InnoDB;
 CREATE TABLE IF NOT EXISTS `jpatutorial3u1`.`business` (
  `seller` INT NOT NULL ,
  `buyer` INT NOT NULL ,
  PRIMARY KEY (`seller`, `buyer`) ,
  INDEX `fk_person_has_person_person1_idx` (`buyer` ASC) ,
  INDEX `fk_person_has_person_person_idx` (`seller` ASC) ,
  CONSTRAINT `fk_person_has_person_person`
  FOREIGN KEY (`seller` )
  REFERENCES `jpatutorial3u1`.`person` (`idperson` )
  ON DELETE NO ACTION
  ON UPDATE NO ACTION,
  CONSTRAINT `fk_person_has_person_person1`
  FOREIGN KEY (`buyer` )
  REFERENCES `jpatutorial3u1`.`person` (`idperson` )
  ON DELETE NO ACTION
  ON UPDATE NO ACTION)
 ENGINE = InnoDB;  

As for the Entity Bean, let us create one Entity called PersonEntity, and add the existing columns to it, just the columns for now. The main bits of the PersonEntity class should look somewhat like this:

@Entity
@Table(name = "person", catalog = "jpatutorial3u1", schema = "")
public class PersonEntity implements Serializable {
 private static final long serialVersionUID = 1L;
 @Id
 @GeneratedValue(strategy = GenerationType.IDENTITY)
 @Column(name = "idperson", nullable = false)
 private Integer idperson;

 @Basic(optional = false)
 @Column(name = "name", nullable = false, length = 45)
 private String name;

 @Basic(optional = true)
 @Column(name = "phonenumber", length = 45)
 private String phonenumber;

Create now the Getters and Setters for these fields. While we are at it, lets go and take a look at the Test Packages folder and check the MemSelfTest JUnit class. For those not following the source code, the relevant bit is :

@Test
public void testMemSelf(){
        // Start a transaction
        em.getTransaction().begin();
        // ------------
       PersonEntity c = new PersonEntity();
        c.setName("Rui");
        em.persist(c);
        em.flush();

        Object result = em.find(PersonEntity.class, c.getIdperson());
        assertEquals(c, result);

        em.remove(c);
        em.flush();

        // Commit the Transaction
        em.getTransaction().commit();
}

It doesn't really do much except for creating a Person, searching for it, and removing it.... just to make sure everything is working fine and we can proceed.

The basic stuff is now done, lets move on to the mapping of the relationship

Who Sold To Who?

Lets start with editing the PersonEntity class by adding the following bit:

 @JoinTable(name = "business", joinColumns = {
 @JoinColumn(name = "seller", referencedColumnName = "idperson", nullable = false)}, inverseJoinColumns = {
 @JoinColumn(name = "buyer", referencedColumnName = "idperson", nullable = false)})
 @ManyToMany
 private Collection<PersonEntity>soldToCollection;

and, as per usual, add the Setters and Getters for soldToCollection.

If you are a bit lost right now with the notation used and the way it was used, then you should probably give a read to  JPA 2 Tutorial – Relationships – Many To Many , but I'll recap a bit here.

The @JoinTable annoration is used on the Owning Entity side of the relationship, which is in fact the PersonEntity class (both the owning and the inverse to be honest, but it will depend on the context it is being used).  The Join Table is specify as "friend" , which is the name of the Join Table and then we do the JoinColumns bit, in which we specify the Fields used to map the relationship. Please do give a read at JPA 2 Tutorial – Relationships – Many To Many if nothing seems to make sense at this point!

Let us modify the M2mSelfTest JUnit class now. First let us create another few users :

PersonEntity c = new PersonEntity();
c.setName("Rui");
PersonEntity f1 = new PersonEntity();
f1.setName("Felix");
PersonEntity f2 = new PersonEntity();
f2.setName("Gusy");
em.persist(c);
em.persist(f1);
em.persist(f2);
em.flush();

Now we got a few PersonEntity objects to play about with. After the assertEquals that we have created previously, add the following bit as well:

    assertEquals(c.getSoldToCollection().size(),0);
    c.getSolfToCollection().add(f1);
    em.merge(c);
    em.flush();
    assertEquals(c.getSoldToCollection().size(),1);
    System.out.println(c.getName() + " sold stuff to :");
    for (PersonEntity tempP : c.getSoldToCollection() )
          System.out.println(" - " + tempP.getName() );

and to finish it off , lets delete every object we have created and clean the DB :

em.remove(c);
em.remove(f1);
em.remove(f2);
em.flush();
// Commit the Transaction
em.getTransaction().commit();

Run it and, if it was done right, everything should have work fine:

    
    [EL Info]: 2013-06-06 16:07:42.49--ServerSession(805125680)--EclipseLink, version: Eclipse Persistence Services - 2.3.2.v20111125-r10461
    [EL Info]: 2013-06-06 16:07:42.753--ServerSession(805125680)--file:/home/rui/projects/syshex-code/JPATutorial3.1/trunk/build/classes/_JPATutorial3.1PU login successful
    Rui sold stuff to :
     - Felix

But you know what would be really cool too? For a us to know who he Bought stuff from, yeah?

Who did He Bought From?

First, lets modify the PersonEntity again and add the following:

    
    @ManyToMany(mappedBy = "soldToCollection")
    private Collection<PersonEntity> boughtFromCollection;

Feeling a bit lost? Check out  JPA 2 Tutorial – Relationships – Many To Many where it is explained everything about @ManyToMany and the mappedBy property.

Go ahead and create the Setter and Getter for this new collection, and afterward , lets go to the MemSelfTest JUnit test and modify like so:

    
    System.out.println(c.getName() + " sold stuff to :");
    for (PersonEntity tempP : c.getSoldToCollection() )
         System.out.println(" - " + tempP.getName() );

    System.out.println(c.getName() + " Bought stuff from :");
    for (PersonEntity tempP : c.getBoughtFromCollection())
         System.out.println(" - " + tempP.getName() );

    em.refresh(f1);

    System.out.println(f1.getName() + " sold stuff to :");
    for (PersonEntity tempP : f1.getSoldToCollection() )
        System.out.println(" - " + tempP.getName() );

    System.out.println(f1.getName() + " Bought stuff from :");
    for (PersonEntity tempP : f1.getBoughtFromCollection())
         System.out.println(" - " + tempP.getName() );

Lets run it !

[EL Info]: 2013-06-06 16:18:04.464--ServerSession(745084087)--EclipseLink, version: Eclipse Persistence Services - 2.3.2.v20111125-r10461
[EL Info]: 2013-06-06 16:18:04.73--ServerSession(745084087)--file:/home/rui/projects/syshex-code/JPATutorial3.1/trunk/build/classes/_JPATutorial3.1PU login successful
Rui sold stuff to :
- Felix
Rui Bought stuff from :
Felix sold stuff to :
Felix Bought stuff from :
- Rui

Wicked stuff really.

But, what if.... we need to store some information regarding the relationship?

Storing Info about Relationship

Well, then we would have something like this :

Now, as it was said in the last Tutorial :

The table that you see serving as a connection between the Company table and the Client table is what is called a “Join Table” ,  and its sole purpose in life is to keep track of the relations that exist between Company and Client Entities.

And storing information regarding Money in it will make it have* more the a "sole" purpose. Not that it is wrong to do this, if you need to have information regarding the relationship, but since it has information, it should be an Entity. It could be called  *BusinessEntity, in which money , seller and buyer are in fact information that regard the Business.

In looking at this Business table and an Entity and not as a simple JoinTable, we can deduce that there are One-To-Many relationships to be used instead of the* Many-To-Many*.

So, wrapping it up, in this situation you should see this in a totally different light than a M2M

Hope his helped, and as per usual, leave a comment if you find errors, problems, or for a kind word. And again, thanks for checking out our blog.

Also, check the next tutorial on this series: JPA 2 Tutorial - Queries with JPQL

• Getting Started with JPA 2 Tutorial

• JPA 2 – Relationships – One To Many

For this tutorial it is assumed that you have basic knowledge of SQL and relational databases, in particular MySQL. It is also useful to have a MySQL database installed so that you can actually try out the examples that we will be going through in this tutorial.  Unit Testing with JUnit is also a bit part for this tutorial aswell, You'll need to understand what it is, and how it is used. Check the previous Tutorial regarding JPA, they should provide enough information to get you started. An IDE like IntelliJ or Netbeans is also recommended is case you want to try out the source code provided. You don't need special powers, if you know basic SQL, JUnit and you have read and understood the previous tutorials you should be fine. The source code used for this tutorial can be found here : https://github.com/jbaysolutions/jpa2tut-many2many .

Many-To-Many, lets start!

Of the 4 types of relationships that exist, we have already talked about the One-to-Many and Many-to-One and most of the background information regarding how a relationship works, and the difference between Unidirectional and Bidirectional relationship. The Many-to-Many relationship isn't much different to the One-To-Many relationship, except for the fact that now we have an extra middle table around there....

The Join Table

Expanding on the example given on the previous tutorial, we had two Entities : Company and Employee. We now delete the Employee table and create a new Entity which is called Client and we say:

• a Company can have several Clients and

• a Client can have various Companies

When we say this we have a Many to Many relationship between Companies and Clients, and can be represented on a data model like so:

The SQL to create this is like so:

CREATE TABLE IF NOT EXISTS `jpatutorial3`.`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 `jpatutorial3`.`client` (
 `idclient` INT NOT NULL AUTO_INCREMENT ,
 `name` VARCHAR(45) NOT NULL ,
 `address` VARCHAR(45) NULL ,
 PRIMARY KEY (`idclient`) )
ENGINE = InnoDB;
CREATE TABLE IF NOT EXISTS `jpatutorial3`.`company_client` (
 `company_idcompany` INT NOT NULL ,
 `client_idclient` INT NOT NULL ,
 PRIMARY KEY (`company_idcompany`, `client_idclient`) ,
 INDEX `fk_company_has_client_client1` (`client_idclient` ASC) ,
 INDEX `fk_company_has_client_company1` (`company_idcompany` ASC) ,
 CONSTRAINT `fk_company_has_client_company1`
 FOREIGN KEY (`company_idcompany` )
 REFERENCES `jpatutorial3`.`company` (`idcompany` )
 ON DELETE NO ACTION
 ON UPDATE NO ACTION,
 CONSTRAINT `fk_company_has_client_client1`
 FOREIGN KEY (`client_idclient` )
 REFERENCES `jpatutorial3`.`client` (`idclient` )
 ON DELETE NO ACTION
 ON UPDATE NO ACTION)
ENGINE = InnoDB;

The table that you see serving as a connection between the Company table and the Client table is what is called a "Join Table" ,  and its sole purpose in life is to keep track of the relations that exist between Company and Client Entities.

The normal notation for a Join Table is to use a single underscore between the name of the two tables that are part of the relation. In our example the expected name of the Join Table would have been companyclient . The Entity that is the Owner of the relationship (you remember what the Owner is, yes?) is placed on the left side of the "".

From this point onwards, when we talk about the Join Table, you know exactly what it is.

Putting it to work

Continuing as we were, expanding from the previous tutorial, we have a CompanyEntity bean that already has a relation with EmployeeEntity, this is a OneToMany relation. We'll leave that as it is for now and proceed to create the ClientEntity bean that is missing, because it was not present on the previous tutorial.  If you follow the previous tutorial, it should be pretty easy to get the ClientEntity bean done, but here is a snippet of what you should be aiming for at this moment:

@Entity
@Table(name = "client")
public class ClientEntity implements Serializable {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    @Column(name = "idclient")
    private Integer idclient;

    @Column(name = "name")
    private String name;

    @Column(name = "address")
    private String address;

And now, we define the new relation that we created by adding the following lines to the CompanyEntity bean:

@ManyToMany
private Collection<ClientEntity> client;

And while we are at it, lets go to the ClientEntity bean and add the following:

@ManyToMany(mappedBy = "clientCollection")
private Collection<CompanyEntity> company;

Create in both beans the respective Getters and _Setters _for the collections.

So, what is new so far on these Entities that we haven't seen before on the other tutorials?

@ManyToMany

The ManyToMany annotation works pretty much like the other annotations we have see thus far, the only different is a couple of assumptions that are made because of the Join Table that was created to support the relationship. But lets start from the beginning: Every many to many relationship has obviously two sides: a Owning side and the Inverse side (which is... non-owning).

As you can see, on one of the @ManyToMany annotations that we wrote a minute ago we have a mappedBy element. This mappedBy element is mandatory and must be placed on the Inverse side of the relationship in case we are mapping a Bidirectional. If we are mapping a Unidirectional relationship then the Inverse side would have no_ @ManyToMany annotation and therefore no _mappedBy element. In a second I'll get back to this!

The other possible elements of the @ManyToMany annotation are targetEntity, cascade and fetch, which we have already seen on the previous tutorials. I'll just give a kick overview of the targetEntity element to say that it is optional if the collection is defined using generics, otherwise you have to put it in, example:

@ManyToMany(targetEntity=ClientEntity.class) 
private Collection client;

So returning to the mappedBy element, it points out the field (that must exist on the Target Entity, which is known either through the use of generics or through the use of the targetEntity element) that owns the relationship.

Now that we have a better understanding of what was inserted on the Entity bean, lets see how it works.

Working it

In the source code provided with this tutorial there is a Class called ManyToManyTesting, in it we have this method called testCompanyWithClient1 which is annotated with @Test, in it, we have the following:

CompanyEntity c = createTestCompany();
ClientEntity client = createTestClient();
em.persist(c);
em.persist(client);
em.flush();
c.getClientCollection().add(client);
em.merge(c);
em.flush();

Both methods createTestCompany and createTestClient simply create its corresponding Entity Bean with some test data inserted. Nothing is set in relation to relationships on those methods.... they just save us some work when writing the test cases.

So, running this test case we get a successful execution, right? Perfect.

The reason why this was a successful and easy bit of code is because we based all of our previous code on the expected JPA defaults, and because of that all worked wonderfully. Now, in real life:

• you might not have a change to decide on the names of the tables and all of that.

• you might not want to have the name of the field in a particular way, just to be inline with the defaults

In fact.... this was the first time ever that I personally had a ManyToMany relationship that works based on the defaults.... So, imagine this scenario, instead of having a* Join Table* named companyclient , our Join Table is now called companyhas_client:

The SQL for this new version of the join table is like so:

CREATE TABLE IF NOT EXISTS `jpatutorial3`.`company_has_client` (
 `company_idcompany` INT NOT NULL ,
 `client_idclient` INT NOT NULL ,
 PRIMARY KEY (`company_idcompany`, `client_idclient`) ,
 INDEX `fk_company_has_client_client1` (`client_idclient` ASC) ,
 INDEX `fk_company_has_client_company1` (`company_idcompany` ASC) ,
 CONSTRAINT `fk_company_has_client_company1`
 FOREIGN KEY (`company_idcompany` )
 REFERENCES `jpatutorial3`.`company` (`idcompany` )
 ON DELETE NO ACTION
 ON UPDATE NO ACTION,
 CONSTRAINT `fk_company_has_client_client1`
 FOREIGN KEY (`client_idclient` )
 REFERENCES `jpatutorial3`.`client` (`idclient` )
 ON DELETE NO ACTION
 ON UPDATE NO ACTION)
ENGINE = InnoDB;

Lets try to run the same test case again and see what happens:

Internal Exception: com.mysql.jdbc.exceptions.jdbc4.MySQLSyntaxErrorException: Table 'jpatutorial3.company_client' doesn't exist
Error Code: 1146
Call: INSERT INTO company_client (client_idclient, company_idcompany) VALUES (?, ?)

So, our Join Table is actually "companyhasclient" and not "companyclient" as the persistency manager was expecting. The reason why this is looking for the "companyclient" table comes down to the defaults.

Default Join Table

If we were to have the Join Table called "companyclient" instead of "companyhasclient" this would have worked fine, as you have seen, but now it just isn't working and the persistence manager cannot figure out how to work with these Entities. Because we have only placed the minimum amount of data onto the _ManyToMany annotation, and in fact have only used that annotation to represent the existing relationship on the database, we heavily depend on the defaults of JPA to figure out what the names of the columns and tables are. For the two Entities we have: CompanyEntity and ClientEntity, we have annotated them with** @Table and the name of the table they represent. A Join Table between these two entities, by default, is expected to be the name of the table on the annotation @Table of the Owning side Entity, underscore, name of the table on the annotation @Table** of the Inverse side Entity. Some readers might be lost now, so look at the following example:

@Table(name = "store")
public class StoreEntity

and

@Table(name = "product")
public class ProductEntity

The default expected Join Table, if StoreEntity was the Owning side and ProductEntity the Inverse side,  would be : store_product To use the a non default, unexpected join table there is this other annotation, which is very conveniently called: @JoinTable

@JoinTable

The @JoinTable annoration is used on the Owning Entity side of the relationship and is used to describe to the entity manager where to look for the Join Table and what to expect once it needs to use it. Lets jump on it and modify now our owning entity CompanyEntity like so:

@JoinTable(name="company_has_client")
@ManyToMany
private Collection<ClientEntity> client;

Now, lets run again the unit test and Bang: Success again! Simple, yes? But wait.... There is more! As per usual, an explanation of this new annotation and a description of all possible elements will follow, but lets go for it while we perform some more changes, ok? Let us now change the name of the field of our Owning side Entity CompanyEntity like this:

@JoinTable(name="company_has_client")
@ManyToMany
private Collection<ClientEntity<strong>clientCollection</strong>;

Modify the getters and setters accordingly please. Also go to ClientEntity and modify it like so:

    
    @ManyToMany(mappedBy = "clientCollection")
    private Collection<CompanyEntity> company;

So that it is referencing an existing field on the Owning side Entity. Lets run the unit test one more time:

  
    Internal Exception: com.mysql.jdbc.exceptions.jdbc4.MySQLSyntaxErrorException:
    Unknown column 'clientCollection_idclient' in 'field list'
    Error Code: 1054
    Call: INSERT INTO company_has_client (clientCollection_idclient, company_idcompany) VALUES (?, ?)
     bind =[2 parameters bound]

We get an exception and I've also made a particular point of putting in Bold the interesting bit about this exception. Basically, you can see that the generated SQL is referencing a column that does not exist, it is called clientidclient and not** clientCollectionidclient. The reason it is looking for a column in the Join Table** that is called clientCollection_idclient is once again due to the defaults. The name of the column that is in bold was created by using the name of the field on the Entity bean : "clientCollection" , underscore, and the column name of the _@Id _field on the specified target entity:

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    @Basic(optional = false)
    @Column(name = "idclient")
    private Integer idclient;

So, we have to expand our example now to take into account that we are using names of columns that are not what the manager is not expecting. To do this we look a bit further into the @JoinTable annotation.

@JoinTable expanded

As you have seen before the @JoinTable is used to map associations through the use of a Join Table, and by specifying the particularities of such table. We have seen how to specify a Join Table that does not follow the expected naming convention that is used by the persistency manager, but this is not all that can be done with it. For the JoinTable annotation one can specify the name of the join table by using the name element. the name of the schema that table belongs to through the use of the schema element, and the name of the catalog through the use of the catalog element. This is the easy bit, and almost self explanatory. The new'ish bit is specifying the join columns through the use of the following elements:

• joinColumns : The mapping of the join columns  whose field is defined on the Inverse Entity.

• inverseJoinColumns : the mapping of the join columns whose field if defined on the Owning Entity.

Both these elements are JoinColumn arrays. For our example we have modified the name of the field client to clientCollection. This field is specified on the Owning side Entity but is referent to the Inverse side Entity. Yes? Recapping:

    @JoinTable(name="company_has_client")
    @ManyToMany
    private Collection<ClientEntity>  clientCollection;

This bit exists on the Owning side (CompanyEntity) and the field clientCollection references the Inverse side (ClientEntity), correct? Because of this, we use the inverseJoinColumns element to define the join columns whose name does not match the default generated as explained before. Modify the CompanyEntity bit that was written before this this version now:

    
    @JoinTable (name = "company_has_client", 
        inverseJoinColumns { 
            @JoinColumn(name = "client_idclient", referencedColumnName = "idclient")
            }
     )

    @ManyToMany
    private Collection<ClientEntity> clientCollection;

Run the test again and as you can see everything works fine now! The inverseJoinColumns element is an array of @JoinColumn annotations, which we have already seen in a previous tutorial, but still, it should be pretty self explanatory as for the elements used in our scenario. But lets go ahead and modify our example a little bit more and modify now the ClientEntity class with the following:

@ManyToMany(mappedBy = "clientCollection")
private Collection<CompanyEntity> companyCollection;

So, we are changing the name of the field on the Inverse side that references the Owning side. Please modify the Getters and Setter methods and Getters and Setter methods and run the unit test again.

    Internal Exception: com.mysql.jdbc.exceptions.jdbc4.MySQLSyntaxErrorException:
    Unknown column 'companyCollection_idcompany' in 'field list'
    Error Code: 1054
    Call: INSERT INTO company_has_client (client_idclient, companyCollection_idcompany) VALUES (?, ?)
     bind =[2 parameters bound]

As expected, the same problem as before, and to fix it we now use the joinColumns element because this field is specified on the Inverse side but references the Owning Entity. Modify the** @JoinTable** annotation to look like so:

    @JoinTable(name = "company_has_client", 
            joinColumns { 
                   @JoinColumn(name = "company_idcompany", referencedColumnName = "idcompany")
            }, 
            inverseJoinColumns = { 
                   @JoinColumn(name = "client_idclient", referencedColumnName = "idclient")
            }
     )
     @ManyToMany
     private Collection<ClientEntity> clientCollection;

Run the unit test again and get a fully successful running test unit! And, to close  off this tutorial, I'll just mention the remaing element of the** @JoinTable annotation, which is the uniqueConstraints element. The uniqueConstraints element is an array of @UniqueConstrain** and is used to specify the constraints that are to be placed on the table, but just if table generation is being used, which is not the case here.

Finishing off....

Hope you enjoyed and this tutorial was of use to you. As per usual, if you find that this article is incorrect in anyway or if you have any comment to give, either good or bad, drop a comment over here.

Follow Up

JPA 2 Tutorial – Many To Many with Self

References

Java Persistence Api 2 Specification

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