JPA Modeler

@NamedEntityGraph in Action

2015-12-21T05:57:00.000-08:00

Table of Content :

Introduction
Entity Graph
Create the JPA Diagram
Create the Entities
Create the @NamedEntityGraph
Named sub graph
Entity Graph types
Generate Source Code
Obtain EntityGraph Instance
Entity Graphs in Query Operation
Download Source Code
Conclusion

Introduction :

The Java Persistence API provides a powerful interface for object-relational mapping. Its usage is straightforward for simple models, but complex models require care and expertise to achieve good performance. JPA loading strategies are a key factor for better performance.

JPA 2.1 introduced a new feature :

Entity Graphs - as a means to address the long standing problem of fetching to different depths in the Entity graph for different use cases.

JPA 2.1 entity graphs are a better solution to specify the path and boundaries for find operations or queries. The definition of an entity graph is independent of the query and defines which attributes to fetch from the database.
This blog post describes how we can create named entity graph by using JPA Modeler and explains how fetch settings and entity graphs in JPA 2.1 can be used to implement various loading strategies.

Entity Graph:

When an object is retrieved from the datastore by JPA typically not all fields are retrieved immediately. This is because for efficiency purposes only particular field types are retrieved in the initial access of the object, and then any other objects are retrieved when accessed (lazy loading). The group of fields that are loaded is called an entity graph. There are 3 types of "entity graphs" to consider

Default Entity Graph: implicitly defined in all JPA specs, specifying the fetch setting for each field/property (LAZY/EAGER).
Named Entity Graphs: a new feature in JPA 2.1 allowing the user to define Named Entity Graphs in metadata, via annotations @NamedEntityGraph or deployment descriptor.
Unnamed Entity Graphs (Dynamic): a new feature in JPA 2.1 allowing the user to define Entity Graphs via the createEntityGraph() method of EntityManager API at runtime.

Lets have a look how to define and use an entity graph in JPA Modeler.

Create the JPA Diagram :

Goto File menu > New File > Persistence category.

Select JPA Diagram
From the Persistence , select JPA Diagram and click Next.
Type SampleDiagram for the diagram name.
Type com.jpamodeler.entitygraph for the Package.
Click Finish.

When you click Finish, the IDE creates the JPA Diagram and opens the diagram in the designer window.

Create the Entities:

Drag & Drop the Entities from the Palette window to designer.

Palette
Double click on the Entity and rename to Movie.
To create basic attribute, click on the Movie Entity , then click on the expand button > basic property.
To create relation attribute, click on the Movie Entity .

Add relation property
Now, drag OneToMany attribute to MovieActor Entity class.

Relation property

Final design

Create the @NamedEntityGrpah :

NamedEntityGraph defines a unique name and a list of attributes ( the attributeNodes ) that have be loaded.

Click on the entity > Properties.

From the properties, select Named Entity Graphs Property.

Open Entity Graph Panel

Click on the Add button to create new named entity graph.

Create Entity Grpah

In this panel , you may view entity attributes with check-box in the tree structure.

Entity Graph editor

Select the attribute from the tree to add the fields to the entity graph which will be part of attributeNodes element of @NamedEntityGraph with a javax.persistence.NamedAttributeNode annotation and then, type the entity graph name.

select attributes

In this example, the name of the named entity graph is movieWithActorsAndAwards and include the movieActors field.

Click on the save button to save named entity graph.

Created Entity Graph

Named sub graph :

The definition of a named sub graph is similar to the definition of an named entity graph and can be referenced as an attributeNode.

We used the entity graph to define the fetch operation of the Movie entity. If we want to do the same for the MovieActor entity, we can do this with an entity sub graph.
Now, we will edit the entity graph, expand the movieActors attribute and then select the movieActorAwards attribute.

design Sub Entity Graph

The following code snippets shows the definition of a sub graph to load the MovieActorAward of each MovieActor. The defined entity graph will fetch an Movie with all MovieActors and their MovieActorAwards.

View the Entity Graph based on Graph Type :

An entity graph can be used as a fetch or a load graph.

To check the final view of entity graph based on the graph type on the View button, after selection of attribute.

If a fetch graph is used, only the attributes specified by the entity graph will be treated as FetchType.EAGER and all other attributes will be lazy.

Fetch Graph
If a load graph is used, all attributes that are not specified by the entity graph will keep their default fetch type.

Load Graph

Entity graphs have attributes that correspond to the fields that will be eagerly fetched during a find or query operation. The primary key and version fields of the entity class are always fetched and do not need to be explicitly added to an entity graph.

Generate the entity classes :

Right click on the diagram > Generate Source Code.

Generate Source Code
Click on the Movie entity class to view source code.

Obtaining EntityGraph Instances from Named Entity Graphs:

Use the EntityManager.getEntityGraph method, passing in the named entity graph name, to obtain EntityGraph instances:

EntityGraph eg = em.getEntityGraph("movieWithActorsAndAwards");

You can use an entity graph with the EntityManager.find method or as part of a JPQL or Criteria API query by specifying the entity graph as a hint to the operation or query.

Using Entity Graphs in Query Operations:

Now that we have defined the entity graph, we can use it in a query. To specify entity graphs for both typed and untyped queries, call the setHint method on the query object and specify either javax.persistence.loadgraph or javax.persistence.fetchgraph as the property name and an EntityGraph instance as the value.
The following code snippet shows how to use a named entity graph as a fetch graph in a find statement :

In this example, the movieWithActorsAndAwards is used for the Movie.findAll named query and we provide this graph as a hint to the entity manager, to fetch the movies and all their actors in one query.

Download Source Code :

Github - Named Entity Graph

Conclusion:

The Entity Graph overrides the default loading strategy, and provides flexibility of loading the association & attributes of an Entity and helps to improve the performance of application. The usage and definition of the entity graph does not depends on query and we can fetch a graph of multiple entities with only one select query, so the main drawbacks of the JPA 2.0 are solved.
The Above example shows a very simple entity graph and you will probably be using more complex graphs in a real application which may have more annotations than actual code and that would make the code harder to read, so the JPA Modeler assist the developer to design & manage the entity graph and generate & reverse-engineering the annotation by modeler.

Sponsor

2015-11-30T17:23:00.000-08:00

If your company needs a particular feature or changes added to JPA Modeler, wants to obtain priority support for JPA Modeler, or just would like to help make sure JPA Modeler thrives through continued enhancements, email Shiwani Gupta to find out about rates for JPA Modeler-related services.

@Embeddable Classes in Action

2015-11-30T02:21:00.000-08:00

Introduction :

JPA allows the persistence of fields as embedded typically into the same table as the "owning" class using @Embedded objects, which allow you to pull out attributes of an entity into another class, and embed that class back into the entity. The result is a Java object that might look a little more logical, but doesn’t actually change the database structure since the embedded object’s fields are still on the first object.

To illustrate this, imagine we have a Person object who has an Address.

Person Entity with address fields

It might make sense to pull out the address into another class, but maybe for speed or legacy reasons we have to keep a denormalized table structure. Using an Embeddable class (with the @Embeddable annotation), we can still do this on the JPA end of things. It would look like this:

Person Entity and Address Embeddable

Instances of embeddable classes are always embedded in other entity objects and do not require separate space allocation and separate store and retrieval operations. Therefore, using embeddable classes can save space in the database and improve efficiency.

Create the JPA Diagram :

Goto File menu > New File > Persistence category .

Create JPA Diagram
From the Persistence , select JPA Diagram and click Next.
Type SmapleERD for the diagram name.
Type com.jpamodeler.embeddable for the Package.
Click Finish.

When we click Finish, the NetBeans IDE creates the JPA Diagram and opens the diagram in the designer window.

Create the Embedded Property:

The @Embedded annotation is used to specify a persistent field or property of an entity whose value is an instance of an embeddable class. A class is declared as embeddable by marking it with the @Embeddable annotation.

Drag & Drop the Entity and Embeddable from the Palette window to designer.

Palette
Double click on the Entity and Embeddable and rename to Person and Address .
To create basic attribute, click on the Person Entity , then click on the expand button > basic property.
To create embedded attribute, click on the Person Entity , then click on the composition button.

Add embedded property
Now, drag embedded attribute to Address Embeddable class.

Embedded property
Right click on the diagram > Generate Source Code.

Generate Source Code
Click on the Person entity and Address embeddable class to view generated source code.
Now, deploy the project and view the database table.

Database

JPA will just treat all of the attributes of Address as attributes of Person, and it all works out. JPQL queries should change, but for the most part all of your Java code looks a lot more logical. None of your queries will have any joins.

Nested Embeddable Classes :

A nested embeddable is a relationship to an embeddable object from another embeddable.

Drag & Drop the Embeddable from the Palette window to designer.
To create nested embedded property.Click on the Address Embeddable , then click on the composition button.

Add nested embedded property
Now, drag embedded attribute to ZipCode Embeddable class.

Nested embedded property
Right click on the diagram > Generate Source Code.

Generate Source Code
Click on the Address and ZipCode embeddable class to view generated source code.
Now, deploy the project and view the database table.

Database

Shared Embeddable :

An embeddable object can be shared between multiple classes or within class. By default, column definitions specified in the @Embeddable class apply to the table of the owning entity but you can override them using @AttributeOverride.

Consider Person has property home address and office address of type Address. If Entity have the same embeddable object type twice, then default column name will not work, at least one of the columns will have to be explicit. To support this, @AttributeOverride can be applied to an embedded field or property to override mapping defined by the embeddable class (or embeddable class of one of its attributes).

First rename the address property to homeAddress by double click on it.
Drag embedded attribute to Address Embeddable class , to add one more embedded property named officeAddress.

homeAddress and officeAddress property
Right click on the diagram > Generate Source Code.

Generate Source Code
Click on the Person entity class to view generated source code.
Now, deploy the project and see the server log .

The person table has two attributes (homeAddress.street and officeAddress.street) that both have the same column name (“street”). We have to define different column names for homeAddress and officeAddress attributes. To do that, use @AttributeOverride (and if our embedded object has a relationship to another entity, use @AssociationOverride).

Add AttributeOverride Annotation :

Open the diagram and click on the Person Entity
Now, open the JPA Override View panel from Menu > Window > JPA Modeler > Override View.

JPA Override View Panel
In this panel, you may view all of the attribute on which Attribute Override and Association Override annotation can be applied.

Change column name of homeAddress.street
Click on the attribute and change their column name from property panel.

Change column name of officeAddress.street
Generate the source code and view Person entity class .
Now, deploy the project and view the database table .

Database

Restriction :

Embeddable classes, however, do not have an identity (primary key) of their own which leads to some limitations :

Embeddable instances cannot be shared by different entity objects.
Embeddable objects cannot be directly persisted, it can only be persisted or queried in the context of their parent.
Embeddable objects does not have an id or table.

So a decision whether to declare a class as an entity or embeddable requires case by case consideration.

Download Source Code :

Github - Embeddable Classes

@NamedStoredProcedureQuery in Action

2015-11-25T03:46:00.001-08:00

Table of Content :

Introduction
Create the JPA Diagram
Create the Stored Procedure
Generate the entity classes
Existing Database
Create tester to call Named Stored Procedure
Deploy the EJB Module
Output
Source Code

Introduction :

In this tutorial we will go through the basic execution of stored procedure using JPA Modeler .

JPA 2.1 supports :

Named stored procedures calls defined in @NamedStoredProcedureQuery annotation and created through EntityManager.createNamedStoredProcedureQuery() .
Dynamic stored procedure calls created through EntityManager.createStoredProcedureQuery().

StoredProcedureQuery is a JPA Query that provides additional API for setting the stored procedure parameters, and for accessing output parameters and multiple result sets. A StoredProcedureQuery can return entity objects, or data, similar to native SQL queries. A ResultSetMapping can be used to map the returned fields to the entity columns.

Create the JPA Diagram :

Goto File menu > New File > Persistence category
From the Persistence , select JPA Diagram from Database ( or create new JPA Diagram ) and click Next.

Select JPA Diagram
Select table and add to import entity from DB .

Select Tables
Type SmapleERD for the diagram name.
Type com.jpamodeler.nsp for the Package.
Click Finish.

Create JPA Diagram

When we click Finish, the IDE creates the JPA Diagram and opens the diagram in the designer window.

Create the Stored Procedure :

Click on the entity > Properties .

From the properties , select Named Stored Procedure Query Property.

Open Stored Procedure Query Panel

Click on the Add button to create new named stored procedure .

Create Stored Procedure

In this panel , first select the Database connection.

It will fetch the existing stored procedure list from the DB.

Now select the Stored Procedure and it will fetch existing stored procedure parameter list from the DB.

Select Database Connection to fetch SP

Click on the Result Set Tab to add result classes or resultset mappings.

Select Result Classes

Click on the save button to save named stored procedure.

Created Stored Procedure

Generate the entity classes :

Right click on the diagram > Generate Source Code

Generate Source Code

Click on the Student entity class to view source code.

Existing Database :

Click on the Services window > Databases

Database existing table and data

I have used MySQL as backend database, however PostgreSQL , MS SQL Server or Oracle can also be used. As the schema I have used a simple table to store student’s data.

Student Table SQL Query :

CREATE TABLE student (`SID` INT NOT NULL, `FNAME` VARCHAR(10) NOT NULL, `LNAME` VARCHAR(10), `DEPT` VARCHAR(10), `BATCH` INT, `EMAIL` VARCHAR(30), PRIMARY KEY (`SID`));

INSERT INTO sample_db.student (`SID`, `FNAME`, `LNAME`, `DEPT`, `BATCH`, `EMAIL`) VALUES (1, 'Shiwani', 'Gupta', 'CSE', 2015, 'jShiwanGupta@gmail.com');

INSERT INTO sample_db.student (`SID`, `FNAME`, `LNAME`, `DEPT`, `BATCH`, `EMAIL`) VALUES (2, 'Gaurav', 'Gupta', 'IT', 2012, 'gaurav.gupta.jc@gmail.com');

Stored Procedure (MySQL) :

DELIMITER @@
DROP PROCEDURE studentAll @@
CREATE PROCEDURE sample_db.studentAll
(
 IN BATCH_NO INT
)
BEGIN
  SELECT * FROM STUDENT WHERE BATCH = BATCH_NO;
END @@ 
DELIMITER ;

Create tester to call Named Stored Procedure :

In this exercise we will create a simple startup singleton bean to esecute the store procedure and fetch the student by batch :

Right-click the EJB module and choose File > New File wizard .
In the New File wizard, expand the Enterprises JavaBeans and select Session Beans as shown in the figure below.

Create Tester
Now , we have to specify the EJB Name and the Package Location in the appropriate text fields and then click Finish.
When we click Finish, the class Tester.java opens in the Source Editor.

Deploy the EJB Module :

We can now build and deploy the EJB module. Right-click the StoredProceduresModule module and choose Deploy. When we click Deploy, the IDE builds the ejb module and deploys the JAR archive to the server. In the Services window, if we expand the Applications node of GlassFish Server, we can see that StoredProceduresModule was deployed.

After we have defined the @NamedStoredProcedureQuery, we can use the createNamedStoredProcedureQuery(String name) method of the EntityManager to create a StoredProcedureQuery object. This provides the required methods to set the input parameter, call the stored procedure and get the result.

Output :

INFO: com.jpamodeler.nsp.Student actually got transformed 
INFO: EclipseLink, version: Eclipse Persistence Services - 2.5.0.v20130507-3faac2b 
INFO: file:/G:/jShiwaniGupta/NetBeans_Projects/StoredProceduresModule/build/classes/_DEFAULT_PU login successful 
INFO: EJB5181:Portable JNDI names for EJB Tester: [java:global/StoredProceduresModule/Tester, java:global/StoredProceduresModule/Tester!com.jpamodeler.nsp.Tester] 
INFO: Executing Stored Procedure Query ................ 
INFO: Student : Shiwani Gupta 
INFO: StoredProceduresModule was successfully deployed in 1,185 milliseconds.

Download Source Code :

Github - Named Stored Procedure

JPA Modeler

@NamedEntityGraph in Action

Table of Content :

Introduction :

Entity Graph:

Create the JPA Diagram :

Create the Entities:

Create the @NamedEntityGrpah :

Named sub graph :

View the Entity Graph based on Graph Type :

Generate the entity classes :

Obtaining EntityGraph Instances from Named Entity Graphs:

Using Entity Graphs in Query Operations:

Download Source Code :

Conclusion:

Sponsor

@Embeddable Classes in Action

Table of Content :

Introduction :

Create the JPA Diagram :

Create the Embedded Property:

Nested Embeddable Classes :

Shared Embeddable :

Add AttributeOverride Annotation :

Restriction :

Download Source Code :

@NamedStoredProcedureQuery in Action

Table of Content :

Introduction :

Create the JPA Diagram :

Create the Stored Procedure :

Generate the entity classes :

Existing Database :

Student Table SQL Query :

Stored Procedure (MySQL) :

DELIMITER @@ DROP PROCEDURE studentAll @@ CREATE PROCEDURE sample_db.studentAll ( IN BATCH_NO INT ) BEGIN SELECT * FROM STUDENT WHERE BATCH = BATCH_NO; END @@ DELIMITER ;

Create tester to call Named Stored Procedure :

Deploy the EJB Module :

Output :

Download Source Code :