We’ve been providing several examples so far, most of the examples are being provided weren’t use complex persistent entity states; we are using a primitive data types such (int, String, BigDecimal, Date and etc ..).

But what’s happened if you we’ve created an entity whose persistent states are other types (classes). No doubt that it should make the developed applications more easier rather enclose the entity states to be only primitive types. Such that situation is happened frequently, so the JPA specifier takes in its consideration in that cases.

This tutorial will cover @Embeddable, @Embedded and @EmbeddedId, in that the @Embeddable annotation is used to specify a class whose instances are stored as an intrinsic part of an owning entity and share the identity of the entity. Also, @Embedded is used to specify a persistent field or property of an entity whose value is an instance of an embeddable class. And finally the @EmbeddedId is applied to a persistent field or property of an entity class or mapped superclass to denote the composite primary key that is an embeddable class.

Let’s start discussing the @Embeddable, cause it’s the entry point for understanding the new concept.

@Embeddable

As we’ve mentioned before and from the definition of the @Embeddable, it is used to specify or define a class (Type) whose instances are stored as an intrinsic part of an owning entity and share the identity of the entity. So the @Embeddable annotation has never been used with the properties or attributes.

Anatomy of @Embeddable Annoation

The specification of the @Embeddable is:

[code lang=”java”]
@Target({TYPE}) @Retention (Runtime)
public @interface Embeddable {}
[/code]

• Target: Types
• Uses: @Embeddable
• Arguments: No argument provided

Classes Design

If you’ve read through the previous examples that provided before (See EclipseLink – JPA Tutorial), you’ll find an Employee entity, by adding a new property (not an association or relation; just a property) into Employee entity called (employeePeriod) which contains startDate and endDate as a primitive types. See Figure 1.0 that depict what should Employee and EmployeePeriod entities looks like.

Figure 1.0

• Employee entity does composite an EmployeePeriod type.
• EmployeePeriod type is used to declare the employeePeriod property within an Employee.

Employee Table

See Figure 1.2 that shows you the impact of adding an EmployeePeriod into Employee Table.

Figure 1.2

• A new EmployeeStartDate and EmployeeEndDate columns are added into Employee Table.
• The new columns are added into Employee Table, because of the Embeddable class (Type) persistent states are persisted into the owning entity.

EmployeePeriod Class (Type)

As you’ve noted at the classes design, the EmployeePeriod is an attribute defined within an Employee entity, so when Entity Manager comes to persist an Employee, it should take care of EmployeePeriod.

EmployeePeriod.java

[code lang=”java”]
package net.javabeat.eclipselink.data;

import java.util.Date;

import javax.persistence.Column;
import javax.persistence.Embeddable;
import javax.persistence.Temporal;
import javax.persistence.TemporalType;

@Embeddable
public class EmployeePeriod {
@Column(name="EmployeeStartDate")
@Temporal(TemporalType.DATE)
private Date startDate;

@Column(name="EmployeeEndDate")
@Temporal(TemporalType.DATE)
private Date endDate;

public Date getStartDate() {
return startDate;
}
public void setStartDate(Date startDate) {
this.startDate = startDate;
}
public Date getEndDate() {
return endDate;
}
public void setEndDate(Date endDate) {
this.endDate = endDate;
}

}
[/code]

• The @Embeddable class (type) isn’t specify a Table, cause the the Embeddable class (type) should depends on the owning entity when it comes to persist.
• The properties that defined in the EmployeePeriod embeddable class (type) defines their mapping information and the columns that should be referred to using @Column.
• As defined properties are Date, so it is important to specify the @Temporal annotation.

Employee Entity With @Embedded

Employee.java

[code lang=”java”]
package net.javabeat.eclipselink.data;

import java.util.List;

import javax.persistence.Basic;
import javax.persistence.CascadeType;
import javax.persistence.DiscriminatorColumn;
import javax.persistence.DiscriminatorValue;
import javax.persistence.Embedded;
import javax.persistence.Entity;
import javax.persistence.Id;
import javax.persistence.Inheritance;
import javax.persistence.InheritanceType;
import javax.persistence.JoinColumn;
import javax.persistence.JoinTable;
import javax.persistence.ManyToMany;
import javax.persistence.OneToMany;
import javax.persistence.OneToOne;

@Entity
@Inheritance(strategy=InheritanceType.SINGLE_TABLE)
@DiscriminatorColumn(name="EmployeeType")
@DiscriminatorValue(value="EMP")
public class Employee {

@Id
private int employeeId;

@Basic(optional=false)
private String employeeName;

@Embedded
private EmployeePeriod employeePeriod;

@OneToMany(mappedBy="employee", cascade=CascadeType.ALL)
private List<Phone> phones;

@ManyToMany(cascade=CascadeType.ALL)
@JoinTable(
joinColumns={@JoinColumn(name="employeeId")},
inverseJoinColumns={@JoinColumn(table="project",name="projectId"),@JoinColumn(table="localproject",name="projectId"),@JoinColumn(table="globalproject",name="projectId")}
)
private List<Project> projects;

@OneToOne(cascade=CascadeType.ALL)
@JoinColumn(name="AddressId")
private Address address;

public Address getAddress() {
return address;
}

public void setAddress(Address address) {
this.address = address;
}

public int getEmployeeId() {
return employeeId;
}

public void setEmployeeId(int employeeId) {
this.employeeId = employeeId;
}

public String getEmployeeName() {
return employeeName;
}

public void setEmployeeName(String employeeName) {
this.employeeName = employeeName;
}

public List<Phone> getPhones() {
return phones;
}

public void setPhones(List<Phone> phones) {
this.phones = phones;
}

public List<Project> getProjects() {
return projects;
}

public void setProjects(List<Project> projects) {
this.projects = projects;
}

public EmployeePeriod getEmployeePeriod() {
return employeePeriod;
}

public void setEmployeePeriod(EmployeePeriod employeePeriod) {
this.employeePeriod = employeePeriod;
}

}
[/code]

• The Employee defines a new property named (employeePeriod) that’s embeddable type.
• The properties of employeePeriod depend on Employee entity for specifying the table that they are going to persist into.
• The JPA doesn’t know if you were using an Embeddable class (type) or not, except if you were specifying the @Embedded.
• The Embedded notify the JPA implementation that, it has an Embeddable class (Type), so consider the mapping information in the Embeddable class in the context of the owning (Employee) entity.

Persistence Configuration Changes Required

Nothing needs a change, except the adding of new EmployeePeriod class (type) in the Persistence Context. For the detailed configuration, please read our previous tutorials.

[code lang=”xml”]
<class>net.javabeat.eclipselink.data.EmployeePeriod</class>
[/code]

Executable Application

JPAImpl.java

[code lang=”java”]
package net.javabeat.eclipselink;

import java.math.BigDecimal;
import java.util.ArrayList;
import java.util.Date;
import java.util.List;

import javax.persistence.EntityManager;
import javax.persistence.EntityManagerFactory;
import javax.persistence.Persistence;

import net.javabeat.eclipselink.data.Address;
import net.javabeat.eclipselink.data.ContractDeveloper;
import net.javabeat.eclipselink.data.Developer;
import net.javabeat.eclipselink.data.DriverLicense;
import net.javabeat.eclipselink.data.Employee;
import net.javabeat.eclipselink.data.EmployeePeriod;
import net.javabeat.eclipselink.data.FreelanceDeveloper;
import net.javabeat.eclipselink.data.GlobalProject;
import net.javabeat.eclipselink.data.ICDLComputerLicense;
import net.javabeat.eclipselink.data.LocalProject;
import net.javabeat.eclipselink.data.Phone;
import net.javabeat.eclipselink.data.Project;

public class JPAImpl {
static EntityManagerFactory factory = null;
static EntityManager em = null;
static {
factory = Persistence.createEntityManagerFactory("EclipseLink-JPA-Installation");
em = factory.createEntityManager();
}

public static void main(String [] args){
// Begin a Transaction
em.getTransaction().begin();
createEmployee();
// Commit
em.getTransaction().commit();
}

public static void createEmployee(){
// Create an address entity
Address address = new Address();
address.setAddressId(2);
address.setAddressCountry("United Kingdom");
address.setAddressCity("London");
// Create an employee entity
Employee employee = new Employee();
employee.setEmployeeId(2);
employee.setEmployeeName("John Smith");

// Create an Employee Period Instance
EmployeePeriod period = new EmployeePeriod();
period.setStartDate(new Date());
period.setEndDate(new Date());

employee.setEmployeePeriod(period);

// Associate the address with the employee
employee.setAddress(address);
// Create a Phone entity
Phone firstPhone = new Phone();
firstPhone.setPhoneId(3);
firstPhone.setPhoneNumber("+221 4050 615");
firstPhone.setEmployee(employee);
// Create a new phone entity
Phone secondPhone = new Phone();
secondPhone.setPhoneId(4);
secondPhone.setPhoneNumber("+221 4050 619");
// Use the old employee entity
secondPhone.setEmployee(employee);
// Create a list of phone
List<Phone> phones = new ArrayList<Phone>();
phones.add(firstPhone);
phones.add(secondPhone);

// Create a list of projects
List<Project> projects = new ArrayList<Project>();

// Set the project into employee
employee.setProjects(projects);
// Set the phones into your employee
employee.setPhones(phones);

// Persist the employee

em.persist(employee);
}

}
[/code]

• If the Embeddable class (Type) is used within an Employee, so no overrides required on the mapping information that provided by the EmployeePeriod properties. But in case you’ve needed to use the EmployeePeriod in an entities rather Employee and these entities reference a different column names, so you should use an @OverrideAttributes annotation.
• Let’s assume that we’ve considered a columns that differ from the mapping information that’s provided in the EmplyeePeriod Embeddable class (type), in that you have to consider the @OverrideAttributes change the take place inside Employee entity. See the following snippet of code.

[code lang=”java”]
@Embedded
@AttributesOverride({
@AttributeOverride(name="startDate",column=@Column(name="EMP_START")),
@AttributeOverride(name="endDate",column=@Column(name="EMP_END"))
})
private EmployeePeriod employeePeriod; // employeePeriod property
[/code]

@EmbeddedId

• The EmbeddedId isn’t vary differs as a concept from the previous concepts that discussed before about Embedded and Embeddable, except it is covering a composite primary key point.
• The EmbeddedId annotation is applied to a persistent field or property of an entity class or mapped superclass to denote a composite primary key that is an embeddable class.
• Let’s assume that we’ve a new Embeddable class (Type) named (AddressPK), that’s should determine the primary key of the Address entity.(See previous examples that depict the Address entity by referring the eclipselink jpa tutorial).

AddressPK.java

[code lang=”java”]

package net.javabeat.eclipselink.data;

import java.io.Serializable;

import javax.persistence.Column;
import javax.persistence.Embeddable;

@Embeddable
public class AddressPK implements Serializable{
@Column(name="AddressCountryId")
private int addressCountryId;
@Column(name="AddressCityId")
private int addressCityId;
@Column(name="AddressId")
private int addressId;
public int getAddressCountryId() {
return addressCountryId;
}
public void setAddressCountryId(int addressCountryId) {
this.addressCountryId = addressCountryId;
}
public int getAddressCityId() {
return addressCityId;
}
public void setAddressCityId(int addressCityId) {
this.addressCityId = addressCityId;
}
public int getAddressId() {
return addressId;
}
public void setAddressId(int addressId) {
this.addressId = addressId;
}

public boolean equals(Object obj){
if(obj instanceof AddressPK){
AddressPK addPK = (AddressPK) obj;
if(this.addressId == addPK.getAddressId() &&
this.addressCountryId == addPK.getAddressCountryId() &&
this.addressCityId == addPK.getAddressCityId()){
return true;
}
}
else {
return false;
}
return false;
}

public int hashCode(){
return super.hashCode();
}

}

[/code]

• The AddressPK Embeddable class (Type) defines three properties and they are addressId, addressCountryId and addressCityId, so the Adress entities should be identified by the group of properties rather one addressId property.
• When the developer uses the Embeddable class (Type) for primary key, he should override equals and hashCode(). The JPA itself doesn’t accept the Embeddable class if it was used as primary key unless it ensure that the two methods are overridden.
• The AddressPK should implement the Serializable.
• By using AddressPK, we have been using a new version of primary key that could depend on to identify the Address entities. But if you’ve reviewed the eclipselink jpa previous examples, you should be realized that the Employee entity related to the Address entity by OneToOne association. Let’s see the required changes that should take place once the primary key of the Address has been changed.

Employee.java

[code lang=”java”]

package net.javabeat.eclipselink.data;

import java.util.List;

import javax.persistence.Basic;
import javax.persistence.CascadeType;
import javax.persistence.DiscriminatorColumn;
import javax.persistence.DiscriminatorValue;
import javax.persistence.Embedded;
import javax.persistence.Entity;
import javax.persistence.Id;
import javax.persistence.Inheritance;
import javax.persistence.InheritanceType;
import javax.persistence.JoinColumn;
import javax.persistence.JoinColumns;
import javax.persistence.JoinTable;
import javax.persistence.ManyToMany;
import javax.persistence.OneToMany;
import javax.persistence.OneToOne;

@Entity
@Inheritance(strategy=InheritanceType.SINGLE_TABLE)
@DiscriminatorColumn(name="EmployeeType")
@DiscriminatorValue(value="EMP")
public class Employee {

@Id
private int employeeId;

@Basic(optional=false)
private String employeeName;

@Embedded
private EmployeePeriod employeePeriod;

@OneToMany(mappedBy="employee", cascade=CascadeType.ALL)
private List<Phone> phones;

@ManyToMany(cascade=CascadeType.ALL)
@JoinTable(
joinColumns={@JoinColumn(name="employeeId")},
inverseJoinColumns={@JoinColumn(table="project",name="projectId"),@JoinColumn(table="localproject",name="projectId"),@JoinColumn(table="globalproject",name="projectId")}
)
private List<Project> projects;

// Updated Mapping information that took a consideration for changing the Address’s primary key

@OneToOne(cascade=CascadeType.ALL)
@JoinColumns({
@JoinColumn(name="AddressId",referencedColumnName="AddressId"),
@JoinColumn(name="EmployeeAddressCountryId",referencedColumnName="AddressCountryId"),
@JoinColumn(name="EmployeeAddressCityId",referencedColumnName="AddressCityId")}
)
private Address address;

public Address getAddress() {
return address;
}

public void setAddress(Address address) {
this.address = address;
}

public int getEmployeeId() {
return employeeId;
}

public void setEmployeeId(int employeeId) {
this.employeeId = employeeId;
}

public String getEmployeeName() {
return employeeName;
}

public void setEmployeeName(String employeeName) {
this.employeeName = employeeName;
}

public List<Phone> getPhones() {
return phones;
}

public void setPhones(List<Phone> phones) {
this.phones = phones;
}

public List<Project> getProjects() {
return projects;
}

public void setProjects(List<Project> projects) {
this.projects = projects;
}

public EmployeePeriod getEmployeePeriod() {
return employeePeriod;
}

public void setEmployeePeriod(EmployeePeriod employeePeriod) {
this.employeePeriod = employeePeriod;
}

}

[/code]

• The Employee defines a new mapping information cause the Address entity primary key has been changed.
• The Employee references three columns at the Address Table. (In the next section, you could see the Employee Table is also has been changed by adding a new two columns).
• The referencedColumnName isn’t mandatory when we are going to use the @JoinColumns.It does define the name of the column referenced by the foreign keys column defined in the Employee table. Employee Table has (AddressId, AddressCountryId, AddressCityId) as foreign keys.

Database Design

Figure 1.3 shows you the changes that made on the Employee and Address Table.

Figure 1.3

• Address Table add a new two columns (AddressCountryId and AddressCityId).
• Employee Table does reference the new columns that was added into Address Table.

Executable Application

[code lang=”java”]

package net.javabeat.eclipselink;

import java.math.BigDecimal;
import java.util.ArrayList;
import java.util.Date;
import java.util.List;

import javax.persistence.EntityManager;
import javax.persistence.EntityManagerFactory;
import javax.persistence.Persistence;

import net.javabeat.eclipselink.data.Address;
import net.javabeat.eclipselink.data.AddressPK;
import net.javabeat.eclipselink.data.ContractDeveloper;
import net.javabeat.eclipselink.data.Developer;
import net.javabeat.eclipselink.data.DriverLicense;
import net.javabeat.eclipselink.data.Employee;
import net.javabeat.eclipselink.data.EmployeePeriod;
import net.javabeat.eclipselink.data.FreelanceDeveloper;
import net.javabeat.eclipselink.data.GlobalProject;
import net.javabeat.eclipselink.data.ICDLComputerLicense;
import net.javabeat.eclipselink.data.LocalProject;
import net.javabeat.eclipselink.data.Phone;
import net.javabeat.eclipselink.data.Project;

public class JPAImpl {
static EntityManagerFactory factory = null;
static EntityManager em = null;
static {
factory = Persistence.createEntityManagerFactory("EclipseLink-JPA-Installation");
em = factory.createEntityManager();
}

public static void main(String [] args){
// Begin a Transaction
em.getTransaction().begin();
createEmployee();
// Commit
em.getTransaction().commit();
}

public static void createEmployee(){
// Create an address entity
Address address = new Address();

// Address Embeddable class (Type) instantiation
AddressPK addressPK = new AddressPK();
addressPK.setAddressId(1);
addressPK.setAddressCountryId(1);
addressPK.setAddressCityId(1);
address.setAddressId(addressPK);
address.setAddressCountry("United Kingdom");
address.setAddressCity("London");
// Create an employee entity
Employee employee = new Employee();
employee.setEmployeeId(2);
employee.setEmployeeName("John Smith");

// Create an Employee Period Instance
EmployeePeriod period = new EmployeePeriod();
period.setStartDate(new Date());
period.setEndDate(new Date());

employee.setEmployeePeriod(period);

// Associate the address with the employee
employee.setAddress(address);
// Create a Phone entity
Phone firstPhone = new Phone();
firstPhone.setPhoneId(3);
firstPhone.setPhoneNumber("+221 4050 615");
firstPhone.setEmployee(employee);
// Create a new phone entity
Phone secondPhone = new Phone();
secondPhone.setPhoneId(4);
secondPhone.setPhoneNumber("+221 4050 619");
// Use the old employee entity
secondPhone.setEmployee(employee);
// Create a list of phone
List<Phone> phones = new ArrayList<Phone>();
phones.add(firstPhone);
phones.add(secondPhone);

// Create a list of projects
List<Project> projects = new ArrayList<Project>();

// Set the project into employee
employee.setProjects(projects);
// Set the phones into your employee
employee.setPhones(phones);

// Persist the employee

em.persist(employee);
}

}

[/code]

Database Records That Are Persisted Using a New Primary Key

Figure 1.4 shows the results in of the executable application.

Summary

This tutorial experiment using of Embeddedable, Embedded and EmbeddedId annotations. In general the Embeddable annotation should define a new class (Type) that’s going to be persisted with the owning entity. The JPA implementation requires the developer to mention those properties that considered as an Embeddable class (Type). The EmbeddedId works at the same kind as the Embedded except the EmbeddedId defines an Embeddable primary key.

When we’ve discussed the inheritance and mapped superclasses concepts in the previous tutorials, we are avoiding concepts that could confuse the readers or makes misunderstanding for them.

Most of the clarified examples didn’t provide an Abstract Entity as a target entities that can be managed by the entity manager. On the contrary an Abstract Entity was only used in the tutorial of mapped superclass (See MappedSuperclass tutorial) in that the mapped superclass provides its children capability to inherit both of persistent entity states and the mapping information that belongs to. However, this isn’t the only concept that we would to discuss at this tutorial, but also we are going to discuss a non-entity class lies at the middle of the inheritance hierarchy for managed entities.

These relations might cause a confusion if they were coming in the middle of explanation. In this tutorial concepts like Abstract Entity, non-Entity class and Entity class will be used intensively.

Managed Entity

A managed entity instance is an instance with a persistent identity that’s currently associated with a persistent context. Meaning of managed entity is the contrary of Detached Entity, detached entity instance is an instance with a persistent identity that’s not (or no longer) associated with the persistent context. It is the basic term often used with the persistence technologies.

When an entity is being managed ?

In a brief we can define that, an entity is being managed by entity manager when it’s persisted to the database via an EntityManager’s persist method, which must be invoked within an active transaction. Also Entity objects retrieved from the database by an entity manager are also in the managed state, and if a managed entity instance is modified within an active transaction the changes that’s happened at that instance will be persisted into database once the transaction has been committed. for more information follow this link EntityManager.

Abstract Entity

An abstract entity can be specified as an entity, an abstract entity differs from a concrete entity only in that it cannot be directly instantiated. An abstract entity is mapped as an entity and can be the target of the queries (which will operate over and/or retrieve of its concrete sub-classes).

By returning to previous inheritance examples that implemented before, and by changing the Project entity from a normal entity into Abstract Entity. See Figure 1.1 that shows you the classes design for the whole system that’s being implemented.

Note : The examples in this tutorials are continued from the previous tutorials. For the better understanding of whole code, please read the previous tutorials (EclipseLink Tutorials).

Figure 1.1

• The Project class displayed in an italic form. UML Design shows a class name by using an italic form if it was an abstract.
• The GlobalProject and LocalProject are classes inherit from Project abstract entity.
• Project is an abstract class, so it cannot be instantiated anymore.
• The database can contains two types of Project instances, one for GlobalProject and the second for LocalProject. So no way to have a managed entity instance of type Project and consequently, the Project instance couldn’t be used for query results.

Anatomy of Project Abstract Entities Inheritance Hierarchy

Project.java

[code lang=”java”]
package net.javabeat.eclipselink.data;

import java.util.List;

import javax.persistence.CascadeType;
import javax.persistence.Entity;
import javax.persistence.Id;
import javax.persistence.Inheritance;
import javax.persistence.InheritanceType;
import javax.persistence.ManyToMany;

@Entity(name="Project")
@Inheritance(strategy=InheritanceType.TABLE_PER_CLASS) // The same inheritance strategy that is used
public abstract class Project {
@Id
private int projectId;

private String projectName;

@ManyToMany(mappedBy="projects",cascade=CascadeType.ALL)
private List<Employee> employees;

public int getProjectId() {
return projectId;
}

public void setProjectId(int projectId) {
this.projectId = projectId;
}

public String getProjectName() {
return projectName;
}

public void setProjectName(String projectName) {
this.projectName = projectName;
}

public List<Employee> getEmployees() {
return employees;
}

public void setEmployees(List<Employee> employees) {
this.employees = employees;
}
}
[/code]

GlobalProject.java

[code lang=”java”]

package net.javabeat.eclipselink.data;

import java.math.BigDecimal;

import javax.persistence.Entity;

@Entity
public class GlobalProject extends Project {
private String projectCountry;
private BigDecimal projectBudget;
public String getProjectCountry() {
return projectCountry;
}
public void setProjectCountry(String projectCountry) {
this.projectCountry = projectCountry;
}
public BigDecimal getProjectBudget() {
return projectBudget;
}
public void setProjectBudget(BigDecimal projectBudget) {
this.projectBudget = projectBudget;
}
}

[/code]

LocalProject.java

[code lang=”java”]

package net.javabeat.eclipselink.data;

import java.math.BigDecimal;

import javax.persistence.Entity;

@Entity
public class LocalProject extends Project {
private BigDecimal projectBudget;

public BigDecimal getProjectBudget() {
return projectBudget;
}

public void setProjectBudget(BigDecimal projectBudget) {
this.projectBudget = projectBudget;
}

}

[/code]

• Although Project class is an abstract entity, but it contains an persistent entity states and mapping information.
• The LocalPorject and GlobalProject are sub-classes from Project and they are inherit the persistent entity states and mapping information.
• The strategy used for achieving the inheritance is Table Per Concrete Strategy.

Required Persistence Configuration

[code lang=”xml”]

<?xml version="1.0" encoding="UTF-8"?>
<persistence version="2.1" xmlns="http://xmlns.jcp.org/xml/ns/persistence" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/persistence http://xmlns.jcp.org/xml/ns/persistence/persistence_2_1.xsd">
<persistence-unit name="EclipseLink-JPA-Installation" transaction-type="RESOURCE_LOCAL">
<class>net.javabeat.eclipselink.data.Employee</class>
<class>net.javabeat.eclipselink.data.Developer</class>
<class>net.javabeat.eclipselink.data.Address</class>
<class>net.javabeat.eclipselink.data.Phone</class>

<!– Project Inheritance Hierarchy Entities–>
<class>net.javabeat.eclipselink.data.Project</class>
<class>net.javabeat.eclipselink.data.GlobalProject</class>
<class>net.javabeat.eclipselink.data.LocalProject</class>

<!– End –>
<class>net.javabeat.eclipselink.data.License</class>
<class>net.javabeat.eclipselink.data.DriverLicense</class>
<class>net.javabeat.eclipselink.data.ICDLComputerLicense</class>
<properties>
<property name="javax.persistence.jdbc.url" value="jdbc:mysql://localhost:3306/JavaBeat"/>
<property name="javax.persistence.jdbc.user" value="root"/>
<property name="javax.persistence.jdbc.driver" value="com.mysql.jdbc.Driver"/>
<property name="javax.persistence.jdbc.password" value="root"/>
<property name="eclipselink.logging.level" value="FINEST"/>
</properties>
</persistence-unit>
</persistence>

[/code]

Executable Application

The following JPAImpl class should show you how can we achieve a persistent operation for Project inheritance hierarchy.

JPAImp.java

[code lang=”java”]

package net.javabeat.eclipselink;

import java.math.BigDecimal;
import java.util.ArrayList;
import java.util.Date;
import java.util.List;

import javax.persistence.EntityManager;
import javax.persistence.EntityManagerFactory;
import javax.persistence.Persistence;

import net.javabeat.eclipselink.data.Address;
import net.javabeat.eclipselink.data.Developer;
import net.javabeat.eclipselink.data.DriverLicense;
import net.javabeat.eclipselink.data.Employee;
import net.javabeat.eclipselink.data.GlobalProject;
import net.javabeat.eclipselink.data.ICDLComputerLicense;
import net.javabeat.eclipselink.data.LocalProject;
import net.javabeat.eclipselink.data.Phone;
import net.javabeat.eclipselink.data.Project;

public class JPAImpl {
static EntityManagerFactory factory = null;
static EntityManager em = null;
static {
factory = Persistence.createEntityManagerFactory("EclipseLink-JPA-Installation");
em = factory.createEntityManager();
}
public static void main(String [] args){
// Begin a Transaction
em.getTransaction().begin();
// Create Employee
createDeveloper();
// Commit
em.getTransaction().commit();

}</pre>
public static void createDeveloper(){
// Create an address entity
Address address = new Address();
address.setAddressId(1);
address.setAddressCountry("United Kingdom");
address.setAddressCity("London");
// Create an employee entity
Developer developer = new Developer();
developer.setEmployeeId(1);
developer.setEmployeeName("John Smith");
developer.setTitle("Senior Java Developer");
// Associate the address with the employee
developer.setAddress(address);
// Create a Phone entity
Phone firstPhone = new Phone();
firstPhone.setPhoneId(1);
firstPhone.setPhoneNumber("+221 4050 615");
firstPhone.setEmployee(developer);

// Create a list of phone
List<Phone> phones = new ArrayList<Phone>();
phones.add(firstPhone);

// Project is an abstract entity class, no way to instantiate it
// Project project = new Project(); // That’s getting compiler error

// Create a Global Project
GlobalProject globalProject = new GlobalProject();
globalProject.setProjectId(2);
globalProject.setProjectName("Global Project");
globalProject.setProjectCountry("Brazil");
globalProject.setProjectBudget(new BigDecimal(150000));

// Create a Local Project
LocalProject localProject = new LocalProject();
localProject.setProjectId(3);
localProject.setProjectName("Local Project");
localProject.setProjectBudget(new BigDecimal(50000));

// Create a list of projects
List<Project> projects = new ArrayList<Project>();

projects.add(globalProject);
projects.add(localProject);

// Set the project into employee
developer.setProjects(projects);
// Set the phones into your employee
developer.setPhones(phones);

// Persist the employee
em.persist(developer);

}

}

[/code]

Database Persisted Records

The Figure 1.2 shows you, that how the project abstract entity sub-classes are persisted at the database, although the Project itself isn’t persisted.

Figure 1.2

• The Project abstract entity does provides a persistent entity states and mapping information and it’s capable of inherit them into its sub-classes.
• No records has been persisted for project abstract entity into database, although the GlobalProject and localProject are inserted.
• The Table Per Concrete Strategy provide separate table for every sub-class of Project.
• In case, we are using Single Table Strategy or Joined Table, the project database will contains those common attributes that shared between Project and its sub-classes.

Non-Entity Inherit from Entity & Entity Inherit from Non-Entity

Let’s have the a new additional classes added to our classes design listed above, in that the Employee is a root of inheritance tree. A Developer is a direct sub-class for Employee. Meanwhile the Developer has two sub-classes (ContractDeveloper and FreelanceDeveloper).

Employee is an entity, but Developer isn’t, the Developer is a mapped superclass (Not managed at all). ContractDeveloper and FreelanceDeveloper are another entities.

Developer.java

[code lang=”java”]

package net.javabeat.eclipselink.data;

import javax.persistence.MappedSuperclass;

// Developer extends Employee entity, but it’s annotated using @MappedSuperclass
@MappedSuperclass
public class Developer extends Employee{

private String title;

public String getTitle() {
return title;
}

public void setTitle(String title) {
this.title = title;
}

}

[/code]

ContractDeveloper.java

[code lang=”java”]

package net.javabeat.eclipselink.data;

import javax.persistence.DiscriminatorValue;
import javax.persistence.Entity;

@Entity
@DiscriminatorValue(value="CDEV")
public class ContractDeveloper extends Developer {

}

[/code]

FreelanceDeveloper.java

[code lang=”java”]

package net.javabeat.eclipselink.data;

import javax.persistence.DiscriminatorValue;
import javax.persistence.Entity;

@Entity
@DiscriminatorValue(value="FDEV")
public class FreelanceDeveloper extends Developer {

}

[/code]

• You should add the ContractDeveloper and FreelanceDeveloper into above persistence.xml file.
• The Developer is a mappedSuperclass, so it’s just a way to share the persistent entity states and mapping information that inherit them from the Employee plus those added inside it to its sub-classes.

Executable Application for persisting new Sub-classes

[code lang=”java”]

package net.javabeat.eclipselink;

import java.math.BigDecimal;
import java.util.ArrayList;
import java.util.Date;
import java.util.List;

import javax.persistence.EntityManager;
import javax.persistence.EntityManagerFactory;
import javax.persistence.Persistence;

import net.javabeat.eclipselink.data.Address;
import net.javabeat.eclipselink.data.ContractDeveloper;
import net.javabeat.eclipselink.data.Developer;
import net.javabeat.eclipselink.data.DriverLicense;
import net.javabeat.eclipselink.data.Employee;
import net.javabeat.eclipselink.data.FreelanceDeveloper;
import net.javabeat.eclipselink.data.GlobalProject;
import net.javabeat.eclipselink.data.ICDLComputerLicense;
import net.javabeat.eclipselink.data.LocalProject;
import net.javabeat.eclipselink.data.Phone;
import net.javabeat.eclipselink.data.Project;

public class JPAImpl {
static EntityManagerFactory factory = null;
static EntityManager em = null;
static {
factory = Persistence.createEntityManagerFactory("EclipseLink-JPA-Installation");
em = factory.createEntityManager();
}
public static void main(String [] args){
// Begin a Transaction
em.getTransaction().begin();
// Create Freelance Developer
createFreelanceDeveloper();
// create Contract Developer
createContractDeveloper();
// Commit
em.getTransaction().commit();

}

public static void createFreelanceDeveloper(){
// Create an address entity
Address address = new Address();
address.setAddressId(1);
address.setAddressCountry("United Kingdom");
address.setAddressCity("London");
// Create an employee entity
Developer developer = new FreelanceDeveloper();
developer.setEmployeeId(1);
developer.setEmployeeName("John Smith");
developer.setTitle("Senior Java Developer");
// Associate the address with the employee
developer.setAddress(address);
// Create a Phone entity
Phone firstPhone = new Phone();
firstPhone.setPhoneId(1);
firstPhone.setPhoneNumber("+221 4050 615");
firstPhone.setEmployee(developer);

// Create a list of phone
List<Phone> phones = new ArrayList<Phone>();
phones.add(firstPhone);

// Create a Global Project
GlobalProject globalProject = new GlobalProject();
globalProject.setProjectId(1);
globalProject.setProjectName("Global Project");
globalProject.setProjectCountry("Brazil");
globalProject.setProjectBudget(new BigDecimal(150000));

// Create a Local Project
LocalProject localProject = new LocalProject();
localProject.setProjectId(2);
localProject.setProjectName("Local Project");
localProject.setProjectBudget(new BigDecimal(50000));

// Create a list of projects
List<Project> projects = new ArrayList<Project>();

projects.add(globalProject);
projects.add(localProject);

// Set the project into employee
developer.setProjects(projects);
// Set the phones into your employee
developer.setPhones(phones);

// Persist the employee
em.persist(developer);

}

public static void createContractDeveloper(){
// Create an address entity
Address address = new Address();
address.setAddressId(2);
address.setAddressCountry("United Kingdom");
address.setAddressCity("London");
// Create an employee entity
Developer developer = new ContractDeveloper();
developer.setEmployeeId(2);
developer.setEmployeeName("John Smith");
developer.setTitle("Senior Java Developer");
// Associate the address with the employee
developer.setAddress(address);
// Create a Phone entity
Phone firstPhone = new Phone();
firstPhone.setPhoneId(2);
firstPhone.setPhoneNumber("+221 4050 615");
firstPhone.setEmployee(developer);

// Create a list of phone
List<Phone> phones = new ArrayList<Phone>();
phones.add(firstPhone);

// Create a Global Project
GlobalProject globalProject = new GlobalProject();
globalProject.setProjectId(3);
globalProject.setProjectName("Global Project");
globalProject.setProjectCountry("Brazil");
globalProject.setProjectBudget(new BigDecimal(150000));

// Create a Local Project
LocalProject localProject = new LocalProject();
localProject.setProjectId(4);
localProject.setProjectName("Local Project");
localProject.setProjectBudget(new BigDecimal(50000));

// Create a list of projects
List<Project> projects = new ArrayList<Project>();

projects.add(globalProject);
projects.add(localProject);

// Set the project into employee
developer.setProjects(projects);
// Set the phones into your employee
developer.setPhones(phones);

// Persist the employee
em.persist(developer);

}

}

[/code]

• If you’ve been trying to persist a Developer instance, you are almost getting an exception tells you that the Developer isn’t a known entity even it’s not an abstract.
• The ContractDeveloper and FreelanceDeveloper is the only developer instances that could persisted.
• The ContractorDeveloper and FreelanceDeveloper should provide their discriminator values.

Database Persisted Records

Figure 1.3 depicts you the records that inserted.

Figure 1.3

• The Freelance and contractor developer has been inserted by using the persistent entity states which inherited from the Developer. However, the Developer mapped superclass by its turn inherit some persistent states and mapping information from the Employee.

What’s happened if we’ve created a Simple Developer class?

Let’s create a simple Developer class (i.e. not mapped superclass).

Developer.java

[code lang=”java”]

package net.javabeat.eclipselink.data;
public class Developer extends Employee{
private String title;
public String getTitle() {
return title;
}
public void setTitle(String title) {
this.title = title;
}
}

[/code]

• The executable application mentioned above executes successfully.

Impact of using Entity and non-Entity on The Entity Manager for Querying

What’s heppened if you’ve used a sample query code like

[code lang=”java”]
em.createQuery("select d from Developer d"); // Developer non-entity
em.createQuery("select p from Project p"); // Project Entity
[/code]

• The first query that used in the sample would be thrown an exception, cause the Developer isn’t an entity even if we’ve replaced the normal class to be mapped superclass. The Developer isn’t queryable and cannot be passed as an argument to EntityManager, also it couldn’t be a target of a persistent relationship.
• The second query should executed successfully cause the Project is an entity, so it’s queryable and can be passed into EntityManager and it could be a target for persistent relationship.

Summary

What we should do if we have different type of classes in the same inheritance hierarchy? is JPA support that’s illusion between those entities and non-entities? This tutorial summarizes a different scenarios that could happen in the inheritance hierarchy, you’ve seen how can non-entity class inherit from an entity and vice versa. Also if you’ve decided to avoid the mapped superclass you are able to complete your inheritance hierarchy. Also, this tutorial gives you an examples of how we could differentiate between entity and non-entity once we are coming to make a query. The entity is queryable rather using of mappedsuper class or normal class.