Difference between revisions of "JPA Diagram Editor Project Tutorial"

From Eclipsepedia

Jump to: navigation, search
m
m (Create Is-A relationship between Mapped Superclass and Entity)
(46 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
== Overview  ==
 
== Overview  ==
  
This tutorial provides the necessary information how the Java Diagram Editor to be used.  
+
This tutorial provides the necessary information on how the Java Diagram Editor can be used.  
  
 
== Prerequisites  ==
 
== Prerequisites  ==
  
This tutorial is based on the Eclipse Helios and JPA 1.0 projects.  
+
This tutorial is based on the Eclipse Juno and JPA 2.0 projects.  
  
 
To install JPA Diagram Editor project follow the steps described in [http://wiki.eclipse.org/JPA_Diagram_Editor_Project#How_to_Install How to Install] section of the JPA Diagram Editor wiki main page.  
 
To install JPA Diagram Editor project follow the steps described in [http://wiki.eclipse.org/JPA_Diagram_Editor_Project#How_to_Install How to Install] section of the JPA Diagram Editor wiki main page.  
Line 11: Line 11:
 
== Open JPA Diagram Editor  ==
 
== Open JPA Diagram Editor  ==
  
In the Eclipse IDE create new JPA 1.0 project.  
+
Open the Eclipse IDE.
 +
 
 +
In the ''Project Explorer'' view with rigth click of the mouse select '''''New -> JPA Project'''''.
 +
 
 +
Enter the name of the project. As a '''JPA version''' select 2.0 and in the ''Configuration'' section select '''''Default Configuration'''''.
 +
 
 +
On the last wizard page '''''JPA Facet''''' select the download button to download the persistence provider library:
 +
 
 +
[[Image:DownloadJunoLibrary.jpg]]
 +
 
 +
On the newly opened dialog select '''''EclipseLink 2.4.1 - Juno''''' and finish the '''''Download Library''''' wizard.
 +
 
 +
[[Image:PersistenceProviderLibraryJuno.jpg]]
  
 
The '''''Open Diagram''''' action is available on two levels:  
 
The '''''Open Diagram''''' action is available on two levels:  
Line 17: Line 29:
 
*On project level: Select the newly created JPA project and from its context menu select '''''JPA Tools -> Open Diagram'''''
 
*On project level: Select the newly created JPA project and from its context menu select '''''JPA Tools -> Open Diagram'''''
  
[[Image:OpenDiagramOnProjectLevel.jpg]]  
+
[[Image:OpenJPADiagramOnProjectLevel.jpg]]  
  
 
*On JPA node level: Expand the newly created JPA project and from the context menu of its JPA node, select '''''Open Diagram'''''
 
*On JPA node level: Expand the newly created JPA project and from the context menu of its JPA node, select '''''Open Diagram'''''
  
[[Image:OpenDiagramOnJPANodeLevel.jpg]]
+
[[Image:OpenDiagram.jpg]]
  
== Create new Entity ==
+
== Create new Entity ==
In the Eclipse IDE create new JPA 1.0 project. Download the persistence provider library and add it into the JPA project's classpath.
+
+
Open the JPA Diagram Editor. For more information how to do this, follow the steps described in the previous section [http://wiki.eclipse.org/JPA_Diagram_Editor_Project_Tutorial#Open_JPA_Diagram_Editor Open JPA Diagram Editor].
+
  
From the right site of the editor, the so called Palette section, select '''''Java Entity''''' and drag&drop it to the diagram. A new entity class org.persistence.Entity1 with default primary key attribute should be created and shown in the diagram:
+
In the Eclipse IDE create new JPA 2.0 project and open the JPA Diagram Editor. For more information on how to do this, follow the steps described in the previous section [http://wiki.eclipse.org/JPA_Diagram_Editor_Project_Tutorial#Open_JPA_Diagram_Editor Open JPA Diagram Editor].
  
[[Image:CreateEntity.jpg]]
+
From the right site of the editor, the so called Palette section, select '''''Java Entity''''' and drag&drop it to the diagram. A new entity class org.persistence.Entity1 with default primary key attribute should be created and shown in the diagram:
  
== Visualize Existing Entities in JPA Diagram Editor ==
+
[[Image:CreateJavaEntity.jpg]]
  
In the Eclipse IDE create new JPA 1.0 project. Download the persistence provider library and add it into the JPA project's classpath.
+
== Visualize Existing Entities in JPA Diagram Editor  ==
  
Create new entity as you select the created JPA project and from its context menu select '''''New -> Entity'''''.
+
In the Eclipse IDE create new JPA 2.0 project. Open the JPA Diagram Editor. For more information on how to do this, follow the steps described in section [http://wiki.eclipse.org/JPA_Diagram_Editor_Project_Tutorial#Open_JPA_Diagram_Editor Open JPA Diagram Editor].  
  
Open the JPA Diagram Editor. For more information how to do this, follow the steps described in section [http://wiki.eclipse.org/JPA_Diagram_Editor_Project_Tutorial#Open_JPA_Diagram_Editor Open JPA Diagram Editor].
+
Create new entity as you select the created JPA project and from its context menu select '''''New -> Entity'''''.  
  
To open existing entity in the JPA Diagram Editor:
+
Open the JPA Diagram Editor. For more information on how to do this, follow the steps described in section [http://wiki.eclipse.org/JPA_Diagram_Editor_Project_Tutorial#Open_JPA_Diagram_Editor Open JPA Diagram Editor].  
* expand the JPA project to entity resource level in the ''Project Explorer'' view, select the created entity and drag&drop it to the diagram.
+
* or in the JPA Diagram Editor with right click of the mouse select '''''Show All Entities'''''.
+
  
== Move Entity ==
+
To open existing entity in the JPA Diagram Editor:
  
Entity can be moved all around in the JPA Editor Diagram. Just select the created entity in the diagram, hold the mouse and move it where you want to place it.
+
*expand the JPA project to entity resource level in the ''Project Explorer'' view, select the created entity and drag&drop it to the diagram.
 +
*or in the JPA Diagram Editor with right click of the mouse select '''''Show All Entities'''''.
  
Exceot that entity resource can be moved from package to package. The default entity package is ''org.persistence''.
+
== Move Entity  ==
Select the entity in the diagram and from its context menu choose '''''Refactor Entity Class -> ... Move''''' and select the package where you want to move the entity resource.
+
  
== Edit Entity ==
+
Entity can be moved all around in the JPA Editor Diagram. Just select the created entity in the diagram, hold the mouse and move it where you want to place it.
  
In the Eclipse IDE create new JPA 1.0 project. Open its diagram editor and create new entity. For more information how to create new entity follow the steps described in the previous section [http://wiki.eclipse.org/JPA_Diagram_Editor_Project_Tutorial#Create_new_Entity Create new Entity].
+
Except that entity resource can be moved from package to package. The default entity package is ''org.persistence''. Select the entity in the diagram and choose '''''Refactor Entity Class -> ... Move'''''from its context menu  and select the package where you want to move the entity resource.
There are two ways to rename entity:
+
* Select entity and click on its header name - this is the so called direct editing
+
  
'''''Note:''''' If you double click on the entity, its source code will be opened.
+
== Edit Entity  ==
  
* Select entity and from its context menu select '''''Refactor Entity Class -> Rename...'''''
+
In the Eclipse IDE create new JPA 2.0 project. Open its diagram editor and create new entity. For more information on how to create new entity follow the steps described in the previous section [http://wiki.eclipse.org/JPA_Diagram_Editor_Project_Tutorial#Create_new_Entity Create new Entity]. There are two ways to rename entity:
  
'''''Note:''''' Entity can be edited using the default '''''JPA Details''''' view. To open it just select the entity and from its context menu choose '''''Open JPA Details View'''''.
+
*Select entity and click on its header name - this is the so called direct editing
  
== Collapse/Expand Entity ==
+
'''''Note:''''' If you double click on the entity, its source code will be opened.
  
In the Eclipse IDE create new JPA 1.0 project. Open its diagram editor and create new entity. For more information how to create new entity follow the steps described in the previous section [http://wiki.eclipse.org/JPA_Diagram_Editor_Project_Tutorial#Create_new_Entity Create new Entity].
+
*Select entity and from its context menu select '''''Refactor Entity Class -> Rename...'''''
  
By default the entity is expanded. To collapse entity, select it in the diagram
+
'''''Note:''''' Entity can be edited using the default '''''JPA Details''''' view. To open it just select the entity and from its context menu choose '''''Open JPA Details View'''''.
  
* and from its context buttons select '''''Collapse''''':
+
== Collapse/Expand Entity  ==
  
[[Image:CollapseEntity.jpg]]
+
In the Eclipse IDE create new JPA 2.0 project. Open its diagram editor and create new entity. For more information on how to create new entity follow the steps described in the previous section [http://wiki.eclipse.org/JPA_Diagram_Editor_Project_Tutorial#Create_new_Entity Create new Entity].
  
* or from its context menu select '''''Collapse JPA Entity'''''.
+
By default the entity is expanded. To collapse entity, select it in the diagram
  
Entity is collapsed:
+
*and from its context buttons select '''''Collapse''''':
  
[[Image:CollapsedEntity.jpg]]
+
[[Image:CollapseEntity.jpg]]  
  
To expand entity, select it in the JPA Diagram Editor
+
*or from its context menu select '''''Collapse JPA Entity'''''.
  
* and from its context menu select '''''Expand''''':
+
Entity is collapsed:  
  
[[Image:ExpandEntity.jpg]]
+
[[Image:CollapsedEntity.jpg]]  
  
* or from its context menu select '''''Expand JPA Entity'''''.
+
To expand entity, select it in the JPA Diagram Editor
  
Entity is expanded:
+
*and from its context menu select '''''Expand''''':
  
[[Image:ExpandedEntity.jpg]]
+
[[Image:ExpandEntity.jpg]]  
  
== Remove Entity ==
+
*or from its context menu select '''''Expand JPA Entity'''''.
  
In the Eclipse IDE create new JPA 1.0 project. Open its diagram editor and create new entity. For more information how to create new entity follow the steps described in the previous section [http://wiki.eclipse.org/JPA_Diagram_Editor_Project_Tutorial#Create_new_Entity Create new Entity].
+
Entity is expanded:  
Entity can me deleted as a resource or removed only from the JPA diagram.
+
  
To delete entity select it and
+
[[Image:ExpandedEntity.jpg]]
* from its context buttons choose '''''Delete''''':
+
  
[[Image:DeleteEntity.jpg]]
+
== Remove Entity  ==
  
* from its context menu select '''''Delete'''''
+
In the Eclipse IDE create new JPA 2.0 project. Open its diagram editor and create new entity. For more information how to create new entity follow the steps described in the previous section [http://wiki.eclipse.org/JPA_Diagram_Editor_Project_Tutorial#Create_new_Entity Create new Entity]. Entity can me deleted as a resource or removed only from the JPA diagram.
  
To remove entity from diagram, select it and
+
To delete entity select it and  
* from its context buttons choose '''''Discard Changes and Remove''''' if you don't want to save the changes that were made if there are any:
+
  
[[Image:DiscardAndRemoveEntity.jpg]]
+
*from its context buttons choose '''''Delete''''':
  
* from its context menu select '''''Remove All Entities From Diagram -> ... and Discard Changes'''''
+
[[Image:DeleteEntity.jpg]]
  
* or from its context buttons choose '''''Save and Remove''''' to save all changes that were made:
+
*from its context menu select '''''Delete'''''
  
[[Image:SaveAndRemoveEntity.jpg]]
+
To remove entity from diagram, select it and
  
* from its context menu select '''''Remove All Entities From Diagram -> ... and Save Changes'''''
+
*from its context buttons choose '''''Discard Changes and Remove''''' if you don't want to save the changes that were made if there are any:
 +
 
 +
[[Image:DiscardAndRemoveEntity.jpg]]
 +
 
 +
*from its context menu select '''''Remove All Entities From Diagram -> ... and Discard Changes'''''
 +
 
 +
*or from its context buttons choose '''''Save and Remove''''' to save all changes that were made:
 +
 
 +
[[Image:SaveAndRemoveEntity.jpg]]
 +
 
 +
*from its context menu select '''''Remove All Entities From Diagram -> ... and Save Changes'''''
  
 
== Add new Attribute  ==
 
== Add new Attribute  ==
  
In the Eclipse IDE create new JPA 1.0 project. Open its diagram editor and create new entity. For more information how to create new entity follow the steps described in the previous section [http://wiki.eclipse.org/JPA_Diagram_Editor_Project_Tutorial#Create_new_Entity Create new Entity]. Select the newly created entity or just place the mouse over it and select from its context buttons '''''Create Attribute''''':  
+
In the Eclipse IDE create new JPA 2.0 project. Open its diagram editor and create new entity. For more information how to create new entity follow the steps described in the previous section [http://wiki.eclipse.org/JPA_Diagram_Editor_Project_Tutorial#Create_new_Entity Create new Entity]. Select the newly created entity or just place the mouse over it and select from its context buttons '''''Create Attribute''''':  
 +
 
 +
[[Image:CreateAttribute.jpg]]
 +
 
 +
A new attribute named ''Attribute1'' should be added under section '''''Other Attributes''''':
 +
 
 +
[[Image:AddAttribute.jpg]]
 +
 
 +
== Edit Attribute  ==
 +
 
 +
In the Eclipse IDE create new JPA 2.0 project. Open its diagram editor and create new entity. Create new attribute. For more information how to create new attribute follow the steps described in the previous section [http://wiki.eclipse.org/JPA_Diagram_Editor_Project_Tutorial#Create_new_Attribute Create new Attribute].
 +
 
 +
Entity's Attribute can be renamed or its type can be changed.
 +
 
 +
To rename the attribute, select it and press the mouse one more time, the editing area should be shown.
 +
 
 +
'''''Note:''''' If you double click on the attribute, the entity's source code will be opened.
 +
 
 +
To edit the attributes type, select it and from its context menu choose '''''Refactor Attribute Type...''''' and change the attribute type.
 +
 
 +
'''''Note:''''' Entity's attributes can be edited using the default '''''JPA Details''''' view. To open it just select the created entity attribute and from its context menu choose '''''Open JPA Details View'''''.
 +
 
 +
== Remove Attribute  ==
 +
 
 +
In the Eclipse IDE create new JPA 2.0 project. Open its diagram editor and create new entity. Create new attribute. For more information how to create new attribute follow the steps described in the previous section [http://wiki.eclipse.org/JPA_Diagram_Editor_Project_Tutorial#Create_new_Attribute Create new Attribute].
 +
 
 +
To remove attribute, select it or just place the mouse over it. Select the only one context button '''''Delete Attribute''''':
 +
 
 +
[[Image:DeleteAttribute.jpg]]
 +
 
 +
== Create Relations between Entities  ==
 +
 
 +
JPA Editor Diagram support all kinds of relations between entities: One-to-One unidirectional and bidirectional, One-to-Many unidirectinal, Many-to-One unidirectional and bidirectional, Many-to-Many unidirectional and bidirectional.
 +
 
 +
In the Eclipse IDE create new JPA 2.0 project. Open its diagram editor and create two entities. For more information how to create new entity follow the steps described in the previous section [http://wiki.eclipse.org/JPA_Diagram_Editor_Project_Tutorial#Create_new_Entity Create new Entity].
 +
 
 +
All kinds of relations are available in the right side of the JPA Diagram Editor, in the so called Palette.
 +
 
 +
Select some kind of relationship from the Palette, for example: One-to-Many unidirectional.
 +
 
 +
Select the entity that will be owner of the relationship and drag&drop the relation to the second entity:
 +
 
 +
[[Image:OneToManyUnidirectional.jpg]]
 +
 
 +
A relation is created, and a new attribute is added under the '''''Relation Attributes''''' section of the owner entity.
 +
 
 +
== Edit Relations between Entities  ==
 +
 
 +
In the Eclipse IDE create new JPA 2.0 project. Open its diagram editor and create two entities. For more information how to create new entity follow the steps described in the previous section [http://wiki.eclipse.org/JPA_Diagram_Editor_Project_Tutorial#Create_new_Entity Create new Entity].
 +
 
 +
Select some kind of relationship from the Palette, for example: Many-to-Many bidirectional.
 +
 
 +
From the one of the entity drag&drop the relation the the other:
 +
 
 +
[[Image:ManyToManyBidirectional.jpg]]
 +
 
 +
A new bidirectional relationship is created and the both entities have an attribute under '''''Relation Attributes''''' section.
 +
 
 +
Select one of the entities and delete its relation attribute. The relationship will be automatically transformed from Many-to-Many bidirectional to Many-to-Many unidirectional:
 +
 
 +
[[Image:ManyToManyUnidirectional.jpg]]
 +
 
 +
'''''Note:''''' To delete relationship between entities, just delete their attributes which are under '''''Relation Attributes''''' section.
 +
 
 +
== Entity Compartments  ==
 +
 
 +
The attributes of one entity can be separated in three groups: primary key, relation attributes and other attributes. That's way the entity is separated in three compartments /groups/ named exactly the same way:
 +
 
 +
[[Image:EntityCompartments.jpg]]
 +
 
 +
Entity's compartments can be collapsed and axpanded too.
 +
 
 +
To collapse some of the compartments either double click on its title or select the title and from its context menu select '''''Collapse Attributes Group''''':
 +
 
 +
[[Image:CollapsedCompartments.jpg]]
 +
 
 +
To expand some of the compartments either double click on already collapse compartment or select it and from its context menu choose '''''Expand Attributes Group''''':
 +
 
 +
[[Image:EntityCompartments.jpg]]
 +
 
 +
'''''Note:''''' Changing the annotation of some attribute, it will be automatically moved in another compartments. For example, open the source code of the entity and delete the '''''@Id''''' annotation of the primary key attributes. It will be moved from '''''Primary Key''''' section to '''''Other Attributes''''' compartment of the entity:
 +
 
 +
[[Image:MoveAttribute.jpg]]
 +
 
 +
== JPA Diagram Editor Preference Page ==
 +
 
 +
There is a preference page from which the default package name, entity access type, default collection type for relation creation and etc. for all projects in the workspace can be changed. To open this preference page go to '''''Window -> Preferences -> General -> Editors -> JPA Diagram Editor '''''
 +
 
 +
== JPA Diagram Editor Properties Page  ==
 +
 
 +
There is a properties page from which the default package name, entity access type, default collection type for relation creation and etc. can be changed on project level. To open this property page just select the created JPA project in the ''Project Explorer'' view and from its context menu select '''''Properties -> Java Persistence -> JPA Diagram Editor'''''.
 +
 
 +
== Create new Mapped Superclass ==
 +
 
 +
In the Eclipse IDE create new JPA 2.0 project and open the JPA Diagram Editor. For more information on how to do this, follow the steps described in the previous section [http://wiki.eclipse.org/JPA_Diagram_Editor_Project_Tutorial#Open_JPA_Diagram_Editor Open JPA Diagram Editor]. 
 +
 
 +
From the right site of the editor, the so called Palette section, select '''''Mapped Superclass''''' and drag&drop it to the diagram. A new mapped superclass org.persistence.MpdSuprcls1 without any attributes should be created and shown in the diagram:
 +
 
 +
[[Image:CreateMappedSuperclass.jpg]]
 +
 
 +
== Create new Inherited Entity ==
 +
 
 +
In the Eclipse IDE create new JPA 2.0 project and open the JPA Diagram Editor. For more information on how to do this, follow the steps described in the previous section [http://wiki.eclipse.org/JPA_Diagram_Editor_Project_Tutorial#Open_JPA_Diagram_Editor Open JPA Diagram Editor].
 +
 
 +
Because an entity can inherit either another entity or mapped superclass, there are two ways to create such an entity in the JPA Diagram Editor.
 +
 
 +
* To create an inherited entity from another entity, create one entity in the JPA Diagram Editor and from the right site of the editor, the so called Palette section, select '''Inhereted Entity''' and from the already created entity drag&drop the connection somewhere in the diagram:
 +
 
 +
[[Image:InheritByEntity.jpg]]
 +
 
 +
* To create an inherited entity from mapped superclass, create one mapped superclass in the JPA Diagram Editor and from the right site of the editor, the so called Palette section, select '''Inhereted Entity''' and from the already created mapped superclass drag&drop the connection somewhere in the diagram:
 +
 
 +
[[Image:InheritByMappedSuperclass.jpg]]
 +
 
 +
== Create Relations between Mapped Superclass and Entity ==
 +
 
 +
JPA Editor Diagram support only the four unidirectional kinds of relations between mapped superclass and an entity: One-to-One, One-to-Many, Many-to-One, Many-to-Many.
 +
 
 +
In the Eclipse IDE create new JPA 2.0 project. Open its diagram editor and create one entity and one mapped superclass. For more information how to create new entity and mapped superclass follow the steps described in the previous sections [http://wiki.eclipse.org/JPA_Diagram_Editor_Project_Tutorial#Create_new_Entity Create new Entity] and [http://wiki.eclipse.org/index.php?title=JPA_Diagram_Editor_Project_Tutorial#Create_new_Mapped_Superclass Create new Mapped Superclass].
 +
 
 +
Select some kind of relationship from the Palette, for example: One-to-One unidirectional.
 +
 
 +
Select the mapped superclass that will be owner of the relationship and drag&drop the relation to the entity:
 +
 
 +
[[Image:OneToOneUnidirectional.jpg]]
  
[[Image:CreateAttribute.jpg]]
+
A relation is created, and a new attribute is added under the '''''Relation Attributes''''' section of the mapped superclass.  
  
A new attribute named ''Attribute1'' should be added under section '''''Other Attributes''''':
+
'''''Note:''''' It is not possible to create a unidirectional relationship from an entity to a mapped superclass, as it is not allowed to create bi-directional relationship from a mapped superclass to an entity and vice versa.
  
[[Image:AddAttribute.jpg]]
+
== Soon in Eclipse Kepler Release ==
  
== Edit Attribute ==
+
The visualization of the embeddables will be part of the Eclipse Kepler. [http://wiki.eclipse.org/Embeddables_and_Mapped_Superclasses_in_JPA_Diagram_Editor Here] can be found a detailed description how the embeddables and mapped superclass shall look like.
  
In the Eclipse IDE create new JPA 1.0 project. Open its diagram editor and create new entity. Create new attribute. For more information how to create new attribute follow the steps described in the previous section [http://wiki.eclipse.org/JPA_Diagram_Editor_Project_Tutorial#Create_new_Attribute Create new Attribute].
+
=== Create new Embeddable ===
  
Entity's Attribute can be renamed or its type can be changed.
+
In the Eclipse IDE create new JPA 2.0 project and open the JPA Diagram Editor. For more information on how to do this, follow the steps described in the previous section [http://wiki.eclipse.org/JPA_Diagram_Editor_Project_Tutorial#Open_JPA_Diagram_Editor Open JPA Diagram Editor]. 
  
To rename the attribute, select it and press the mouse one more time, the editing area should be shown.
+
From the right site of the editor, the so called Palette section, select '''''Embeddable''''' and drag&drop it to the diagram. A new embeddable class org.persistence.Embeddable1 without any attributes should be created and shown in the diagram:
  
'''''Note:''''' If you double click on the attribute, the entity's source code will be opened.
+
[[Image:CreateEmbeddable.jpg]]
  
To edit the attributes type, select it and from its context menu choose '''''Refactor Attribute Type...''''' and change the attribute type.
+
=== Pin an Embeddable to an Entity ===
  
'''''Note:''''' Entity's attributes can be edited using the default '''''JPA Details''''' view. To open it just select the created entity attribute and from its context menu choose '''''Open JPA Details View'''''.
+
In the Eclipse IDE create new JPA 2.0 project and open the JPA Diagram Editor. For more information on how to do this, follow the steps described in the previous section [http://wiki.eclipse.org/JPA_Diagram_Editor_Project_Tutorial#Open_JPA_Diagram_Editor Open JPA Diagram Editor].
  
== Remove Attribute ==
+
In the JPA Diagram Editor create one entity and one embeddable. Since JPA 2.0 the entity can have either a reference to a single instance of the embeddable or to a collection of instances of that embeddable:
  
In the Eclipse IDE create new JPA 1.0 project. Open its diagram editor and create new entity. Create new attribute. For more information how to create new attribute follow the steps described in the previous section [http://wiki.eclipse.org/JPA_Diagram_Editor_Project_Tutorial#Create_new_Attribute Create new Attribute].
+
* To embed a single instance of the previously created embeddable, from the right site of the editor, the so called Palette, select '''Embed Single Object'''. Select the entity and drag&drop the connection to the embeddable:
  
To remove attribute, select it or just place the mouse over it. Select the only one context button '''''Delete Attribute''''':
+
[[Image:EmbedSingleObject.jpg]]
  
[[Image:DeleteAttribute.jpg]]
+
A connection is created, and a new attribute is added under the '''''Other Attributes''''' section of the entity.
  
== Create Relations between Entities ==
+
* To embed a collection of instances of the previously created embeddable, from the right site of the editor, the so called Palette, select '''Embed Collection of Objects'''. Select the entity and drag&drop the connection to the embeddable:
  
JPA Editor Diagram support all kinds of relations between entities: One-to-One unidirectional and bidirectional, One-to-Many unidirectinal, Many-to-One unidirectional and bidirectional, Many-to-Many unidirectional and bidirectional.
+
[[Image:EmbedCollectionOfObjects.jpg]]
  
In the Eclipse IDE create new JPA 1.0 project. Open its diagram editor and create two entities. For more information how to create new entity follow the steps described in the previous section [http://wiki.eclipse.org/JPA_Diagram_Editor_Project_Tutorial#Create_new_Entity Create new Entity].
+
A connection is created, and a new attribute is added under the '''''Other Attributes''''' section of the entity.
  
All kinds of relations are available in the right side of the JPA Diagram Editor, in the so called Palette.
+
'''''Note:''''' Instead of entity, the embeddable could be embedded into another embeddable.
  
Select some kind of relationship from the Palette, for example: One-to-Many unidirectional.
+
=== Create Relations between Embeddable and Entity ===
  
Select the entity that will be owner of the relationship and drag&drop the relation to the second entity:
+
JPA Editor Diagram support all kinds of relations from an embeddable to entity, but not vice versa: One-to-One unidirectional and bidirectional, One-to-Many unidirectinal, Many-to-One unidirectional and bidirectional, Many-to-Many unidirectional and bidirectional.
  
[[Image:OneToManyUnidirectional.jpg]]
+
In the Eclipse IDE create new JPA 2.0 project. Open its diagram editor and create two entities and one embeddable. For more information how to create new entity and embeddable follow the steps described in the previous sections [http://wiki.eclipse.org/JPA_Diagram_Editor_Project_Tutorial#Create_new_Entity Create new Entity] and [http://wiki.eclipse.org/index.php?title=JPA_Diagram_Editor_Project_Tutorial#Create_new_Embeddable Create new Embeddable].
  
A relation is created, and a new attribute is added under the '''''Relation Attributes''''' section of the owner entity.
+
All kinds of relations are available in the right side of the JPA Diagram Editor, in the so called Palette.  
  
== Edit Relations between Entities ==
+
Select some kind of relationship from the Palette, for example: One-to-Many unidirectional.
  
In the Eclipse IDE create new JPA 1.0 project. Open its diagram editor and create two entities. For more information how to create new entity follow the steps described in the previous section [http://wiki.eclipse.org/JPA_Diagram_Editor_Project_Tutorial#Create_new_Entity Create new Entity].
+
Select the embeddable that will be owner of the relationship and drag&drop the relation to the second entity:  
  
Select some kind of relationship from the Palette, for example: Many-to-Many bidirectional.
+
[[Image:OneToManyUnidirectionalWithEmb.jpg]]
  
From the one of the entity drag&drop the relation the the other:
+
A relation is created, and a new attribute is added under the '''''Relation Attributes''''' section of the embeddable.
  
[[Image:ManyToManyBidirectional.jpg]]
+
'''''Note:''''' To be able to create any type kind of relationship, the embeddable must be pinned to an entity.
  
A new bidirectional relationship is created and the both entities have an attribute under '''''Relation Attributes''''' section.
+
'''''Note:''''' In case of bidirectional relationship, the embeddable must be pinned to exactly one entity.
  
Select one of the entities and delete its relation attribute. The relationship will be automatically transformed from Many-to-Many bidirectional to Many-to-Many unidirectional:
+
'''''Note:''''' In case an entity has a reference to a collection of instances of an embeddable, the only two possible kind of relationships are '''One-to-one''' and '''Many-to-one'''.
  
[[Image:ManyToManyUnidirectional.jpg]]
+
'''Note:''' Because it is hard to remember, which relationships are allowed and which not, in Eclipse Kepler, the elements in the JPA Diagram Editor, that couldn't be involved in the concrete relation, will be marked as disabled and will be colored gray.
  
'''''Note:''''' To delete relationship between entities, just delete their attributes which are under '''''Relation Attributes''''' section.
+
=== Create Is-A Relationship between Mapped Superclass and Entity ===
  
== Entity Compartments ==
+
In the Eclipse IDE create new JPA 2.0 project. Open its diagram editor and create one entity and one mapped superclass. For more information how to create new entity and mapped superclass follow the steps described in the previous sections [http://wiki.eclipse.org/JPA_Diagram_Editor_Project_Tutorial#Create_new_Entity Create new Entity] and [http://wiki.eclipse.org/index.php?title=JPA_Diagram_Editor_Project_Tutorial#Create_new_Mapped_Superclass Create new Mapped Superclass].
  
The attributes of one entity can be separated in three groups: primary key, relation attributes and other attributes. That's way the entity is separated in three compartments /groups/ named exactly the same way:
+
From the right site of the editor, the so called Palette section, select '''Inherit Persistent Type'''. Select the mapped superclass and drag&drop the connection to the entity:
  
[[Image:EntityCompartments.jpg]]
+
[[Image:InheritByMappedSuperclass.jpg]]
  
Entity's compartments can be collapsed and axpanded too.
+
'''Note:''' Such an "Is-A" relationship can be created between two entities.
  
To collapse some of the compartments either double click on its title or select the title and from its context menu select '''''Collapse Attributes Group''''':
+
'''Note:''' Such an "Is-A" relationship can be deleted by selecting the connection and pressing either the '''''Delete''''' button or using the '''''Delete''''' context menu.
  
[[Image:CollapsedCompartments.jpg]]
+
=== Using Derived Identifiers ===
  
To expand some of the compartments either double click on already collapse compartment or select it and from its context menu choose '''''Expand Attributes Group''''':
+
In the Eclipse IDE create new JPA 2.0 project. Open its diagram editor and create two entities. For more information how to create new entity follow the steps described in the previous sections [http://wiki.eclipse.org/JPA_Diagram_Editor_Project_Tutorial#Create_new_Entity Create new Entity].
  
[[Image:EntityCompartments.jpg]]
+
From the rifght site of the editor, the so called Palette, select '''One-to-One''' unidirectional feature, under '''''Derived Identifiers''''' section. Click on the first entity (the dependent entity) and drag&drop the connection to the second entity (the parent entity). Following some of the rules, described in the wiki [http://wiki.eclipse.org/Editing_Derived_Ids_in_JPA_Diagram_Editor Editing Derived Identifiers in JPA Diagram Editor], a new one-to-one unidirectional relationship will be created, in which the owner attribute will be mapped as primary key:
  
'''''Note:''''' Changing the annotation of some attribute, it will be automatically moved in another compartments. For example, open the source code of the entity and delete the '''''@Id''''' annotation of the primary key attributes. It will be moved from '''''Primary Key''''' section to '''''Other Attributes''''' compartment of the entity:
+
[[Image:SimpleOneToOneDerivedId.jpg‎]]
  
[[Image:MoveAttribute.jpg]]
+
'''''Note:''''' When the connection is deleted, if the dependent entity has a composite primary key, the helper attribute, that is added during creation of the relation, is deleted too, if it is not used by any other entity.
  
== JPA Diagram Editor Properties Page ==
+
== Additional Information  ==
  
There is a properties page from which the default package name, entity access type and etc. can be changed. To open this property page just select the created JPA project in the ''Project Explorer'' view and from its context menu select '''''Properties -> Java Persistence -> JPA DIagram Editor'''''.
+
For more detailed information about the usage of the JPA Editor watch the [http://www.youtube.com/watch?v=xZf6pOHX178 JPA Diagram Editor Demo].

Revision as of 10:50, 7 January 2013

Contents

Overview

This tutorial provides the necessary information on how the Java Diagram Editor can be used.

Prerequisites

This tutorial is based on the Eclipse Juno and JPA 2.0 projects.

To install JPA Diagram Editor project follow the steps described in How to Install section of the JPA Diagram Editor wiki main page.

Open JPA Diagram Editor

Open the Eclipse IDE.

In the Project Explorer view with rigth click of the mouse select New -> JPA Project.

Enter the name of the project. As a JPA version select 2.0 and in the Configuration section select Default Configuration.

On the last wizard page JPA Facet select the download button to download the persistence provider library:

DownloadJunoLibrary.jpg

On the newly opened dialog select EclipseLink 2.4.1 - Juno and finish the Download Library wizard.

PersistenceProviderLibraryJuno.jpg

The Open Diagram action is available on two levels:

  • On project level: Select the newly created JPA project and from its context menu select JPA Tools -> Open Diagram

OpenJPADiagramOnProjectLevel.jpg

  • On JPA node level: Expand the newly created JPA project and from the context menu of its JPA node, select Open Diagram

OpenDiagram.jpg

Create new Entity

In the Eclipse IDE create new JPA 2.0 project and open the JPA Diagram Editor. For more information on how to do this, follow the steps described in the previous section Open JPA Diagram Editor.

From the right site of the editor, the so called Palette section, select Java Entity and drag&drop it to the diagram. A new entity class org.persistence.Entity1 with default primary key attribute should be created and shown in the diagram:

CreateJavaEntity.jpg

Visualize Existing Entities in JPA Diagram Editor

In the Eclipse IDE create new JPA 2.0 project. Open the JPA Diagram Editor. For more information on how to do this, follow the steps described in section Open JPA Diagram Editor.

Create new entity as you select the created JPA project and from its context menu select New -> Entity.

Open the JPA Diagram Editor. For more information on how to do this, follow the steps described in section Open JPA Diagram Editor.

To open existing entity in the JPA Diagram Editor:

  • expand the JPA project to entity resource level in the Project Explorer view, select the created entity and drag&drop it to the diagram.
  • or in the JPA Diagram Editor with right click of the mouse select Show All Entities.

Move Entity

Entity can be moved all around in the JPA Editor Diagram. Just select the created entity in the diagram, hold the mouse and move it where you want to place it.

Except that entity resource can be moved from package to package. The default entity package is org.persistence. Select the entity in the diagram and choose Refactor Entity Class -> ... Movefrom its context menu  and select the package where you want to move the entity resource.

Edit Entity

In the Eclipse IDE create new JPA 2.0 project. Open its diagram editor and create new entity. For more information on how to create new entity follow the steps described in the previous section Create new Entity. There are two ways to rename entity:

  • Select entity and click on its header name - this is the so called direct editing

Note: If you double click on the entity, its source code will be opened.

  • Select entity and from its context menu select Refactor Entity Class -> Rename...

Note: Entity can be edited using the default JPA Details view. To open it just select the entity and from its context menu choose Open JPA Details View.

Collapse/Expand Entity

In the Eclipse IDE create new JPA 2.0 project. Open its diagram editor and create new entity. For more information on how to create new entity follow the steps described in the previous section Create new Entity.

By default the entity is expanded. To collapse entity, select it in the diagram

  • and from its context buttons select Collapse:

CollapseEntity.jpg

  • or from its context menu select Collapse JPA Entity.

Entity is collapsed:

CollapsedEntity.jpg

To expand entity, select it in the JPA Diagram Editor

  • and from its context menu select Expand:

ExpandEntity.jpg

  • or from its context menu select Expand JPA Entity.

Entity is expanded:

ExpandedEntity.jpg

Remove Entity

In the Eclipse IDE create new JPA 2.0 project. Open its diagram editor and create new entity. For more information how to create new entity follow the steps described in the previous section Create new Entity. Entity can me deleted as a resource or removed only from the JPA diagram.

To delete entity select it and

  • from its context buttons choose Delete:

DeleteEntity.jpg

  • from its context menu select Delete

To remove entity from diagram, select it and

  • from its context buttons choose Discard Changes and Remove if you don't want to save the changes that were made if there are any:

DiscardAndRemoveEntity.jpg

  • from its context menu select Remove All Entities From Diagram -> ... and Discard Changes
  • or from its context buttons choose Save and Remove to save all changes that were made:

SaveAndRemoveEntity.jpg

  • from its context menu select Remove All Entities From Diagram -> ... and Save Changes

Add new Attribute

In the Eclipse IDE create new JPA 2.0 project. Open its diagram editor and create new entity. For more information how to create new entity follow the steps described in the previous section Create new Entity. Select the newly created entity or just place the mouse over it and select from its context buttons Create Attribute:

CreateAttribute.jpg

A new attribute named Attribute1 should be added under section Other Attributes:

AddAttribute.jpg

Edit Attribute

In the Eclipse IDE create new JPA 2.0 project. Open its diagram editor and create new entity. Create new attribute. For more information how to create new attribute follow the steps described in the previous section Create new Attribute.

Entity's Attribute can be renamed or its type can be changed.

To rename the attribute, select it and press the mouse one more time, the editing area should be shown.

Note: If you double click on the attribute, the entity's source code will be opened.

To edit the attributes type, select it and from its context menu choose Refactor Attribute Type... and change the attribute type.

Note: Entity's attributes can be edited using the default JPA Details view. To open it just select the created entity attribute and from its context menu choose Open JPA Details View.

Remove Attribute

In the Eclipse IDE create new JPA 2.0 project. Open its diagram editor and create new entity. Create new attribute. For more information how to create new attribute follow the steps described in the previous section Create new Attribute.

To remove attribute, select it or just place the mouse over it. Select the only one context button Delete Attribute:

DeleteAttribute.jpg

Create Relations between Entities

JPA Editor Diagram support all kinds of relations between entities: One-to-One unidirectional and bidirectional, One-to-Many unidirectinal, Many-to-One unidirectional and bidirectional, Many-to-Many unidirectional and bidirectional.

In the Eclipse IDE create new JPA 2.0 project. Open its diagram editor and create two entities. For more information how to create new entity follow the steps described in the previous section Create new Entity.

All kinds of relations are available in the right side of the JPA Diagram Editor, in the so called Palette.

Select some kind of relationship from the Palette, for example: One-to-Many unidirectional.

Select the entity that will be owner of the relationship and drag&drop the relation to the second entity:

OneToManyUnidirectional.jpg

A relation is created, and a new attribute is added under the Relation Attributes section of the owner entity.

Edit Relations between Entities

In the Eclipse IDE create new JPA 2.0 project. Open its diagram editor and create two entities. For more information how to create new entity follow the steps described in the previous section Create new Entity.

Select some kind of relationship from the Palette, for example: Many-to-Many bidirectional.

From the one of the entity drag&drop the relation the the other:

ManyToManyBidirectional.jpg

A new bidirectional relationship is created and the both entities have an attribute under Relation Attributes section.

Select one of the entities and delete its relation attribute. The relationship will be automatically transformed from Many-to-Many bidirectional to Many-to-Many unidirectional:

ManyToManyUnidirectional.jpg

Note: To delete relationship between entities, just delete their attributes which are under Relation Attributes section.

Entity Compartments

The attributes of one entity can be separated in three groups: primary key, relation attributes and other attributes. That's way the entity is separated in three compartments /groups/ named exactly the same way:

EntityCompartments.jpg

Entity's compartments can be collapsed and axpanded too.

To collapse some of the compartments either double click on its title or select the title and from its context menu select Collapse Attributes Group:

CollapsedCompartments.jpg

To expand some of the compartments either double click on already collapse compartment or select it and from its context menu choose Expand Attributes Group:

EntityCompartments.jpg

Note: Changing the annotation of some attribute, it will be automatically moved in another compartments. For example, open the source code of the entity and delete the @Id annotation of the primary key attributes. It will be moved from Primary Key section to Other Attributes compartment of the entity:

MoveAttribute.jpg

JPA Diagram Editor Preference Page

There is a preference page from which the default package name, entity access type, default collection type for relation creation and etc. for all projects in the workspace can be changed. To open this preference page go to Window -> Preferences -> General -> Editors -> JPA Diagram Editor

JPA Diagram Editor Properties Page

There is a properties page from which the default package name, entity access type, default collection type for relation creation and etc. can be changed on project level. To open this property page just select the created JPA project in the Project Explorer view and from its context menu select Properties -> Java Persistence -> JPA Diagram Editor.

Create new Mapped Superclass

In the Eclipse IDE create new JPA 2.0 project and open the JPA Diagram Editor. For more information on how to do this, follow the steps described in the previous section Open JPA Diagram Editor.

From the right site of the editor, the so called Palette section, select Mapped Superclass and drag&drop it to the diagram. A new mapped superclass org.persistence.MpdSuprcls1 without any attributes should be created and shown in the diagram:

CreateMappedSuperclass.jpg

Create new Inherited Entity

In the Eclipse IDE create new JPA 2.0 project and open the JPA Diagram Editor. For more information on how to do this, follow the steps described in the previous section Open JPA Diagram Editor.

Because an entity can inherit either another entity or mapped superclass, there are two ways to create such an entity in the JPA Diagram Editor.

  • To create an inherited entity from another entity, create one entity in the JPA Diagram Editor and from the right site of the editor, the so called Palette section, select Inhereted Entity and from the already created entity drag&drop the connection somewhere in the diagram:

InheritByEntity.jpg

  • To create an inherited entity from mapped superclass, create one mapped superclass in the JPA Diagram Editor and from the right site of the editor, the so called Palette section, select Inhereted Entity and from the already created mapped superclass drag&drop the connection somewhere in the diagram:

InheritByMappedSuperclass.jpg

Create Relations between Mapped Superclass and Entity

JPA Editor Diagram support only the four unidirectional kinds of relations between mapped superclass and an entity: One-to-One, One-to-Many, Many-to-One, Many-to-Many.

In the Eclipse IDE create new JPA 2.0 project. Open its diagram editor and create one entity and one mapped superclass. For more information how to create new entity and mapped superclass follow the steps described in the previous sections Create new Entity and Create new Mapped Superclass.

Select some kind of relationship from the Palette, for example: One-to-One unidirectional.

Select the mapped superclass that will be owner of the relationship and drag&drop the relation to the entity:

OneToOneUnidirectional.jpg

A relation is created, and a new attribute is added under the Relation Attributes section of the mapped superclass.

Note: It is not possible to create a unidirectional relationship from an entity to a mapped superclass, as it is not allowed to create bi-directional relationship from a mapped superclass to an entity and vice versa.

Soon in Eclipse Kepler Release

The visualization of the embeddables will be part of the Eclipse Kepler. Here can be found a detailed description how the embeddables and mapped superclass shall look like.

Create new Embeddable

In the Eclipse IDE create new JPA 2.0 project and open the JPA Diagram Editor. For more information on how to do this, follow the steps described in the previous section Open JPA Diagram Editor.

From the right site of the editor, the so called Palette section, select Embeddable and drag&drop it to the diagram. A new embeddable class org.persistence.Embeddable1 without any attributes should be created and shown in the diagram:

CreateEmbeddable.jpg

Pin an Embeddable to an Entity

In the Eclipse IDE create new JPA 2.0 project and open the JPA Diagram Editor. For more information on how to do this, follow the steps described in the previous section Open JPA Diagram Editor.

In the JPA Diagram Editor create one entity and one embeddable. Since JPA 2.0 the entity can have either a reference to a single instance of the embeddable or to a collection of instances of that embeddable:

  • To embed a single instance of the previously created embeddable, from the right site of the editor, the so called Palette, select Embed Single Object. Select the entity and drag&drop the connection to the embeddable:

EmbedSingleObject.jpg

A connection is created, and a new attribute is added under the Other Attributes section of the entity.

  • To embed a collection of instances of the previously created embeddable, from the right site of the editor, the so called Palette, select Embed Collection of Objects. Select the entity and drag&drop the connection to the embeddable:

EmbedCollectionOfObjects.jpg

A connection is created, and a new attribute is added under the Other Attributes section of the entity.

Note: Instead of entity, the embeddable could be embedded into another embeddable.

Create Relations between Embeddable and Entity

JPA Editor Diagram support all kinds of relations from an embeddable to entity, but not vice versa: One-to-One unidirectional and bidirectional, One-to-Many unidirectinal, Many-to-One unidirectional and bidirectional, Many-to-Many unidirectional and bidirectional.

In the Eclipse IDE create new JPA 2.0 project. Open its diagram editor and create two entities and one embeddable. For more information how to create new entity and embeddable follow the steps described in the previous sections Create new Entity and Create new Embeddable.

All kinds of relations are available in the right side of the JPA Diagram Editor, in the so called Palette.

Select some kind of relationship from the Palette, for example: One-to-Many unidirectional.

Select the embeddable that will be owner of the relationship and drag&drop the relation to the second entity:

OneToManyUnidirectionalWithEmb.jpg

A relation is created, and a new attribute is added under the Relation Attributes section of the embeddable.

Note: To be able to create any type kind of relationship, the embeddable must be pinned to an entity.

Note: In case of bidirectional relationship, the embeddable must be pinned to exactly one entity.

Note: In case an entity has a reference to a collection of instances of an embeddable, the only two possible kind of relationships are One-to-one and Many-to-one.

Note: Because it is hard to remember, which relationships are allowed and which not, in Eclipse Kepler, the elements in the JPA Diagram Editor, that couldn't be involved in the concrete relation, will be marked as disabled and will be colored gray.

Create Is-A Relationship between Mapped Superclass and Entity

In the Eclipse IDE create new JPA 2.0 project. Open its diagram editor and create one entity and one mapped superclass. For more information how to create new entity and mapped superclass follow the steps described in the previous sections Create new Entity and Create new Mapped Superclass.

From the right site of the editor, the so called Palette section, select Inherit Persistent Type. Select the mapped superclass and drag&drop the connection to the entity:

InheritByMappedSuperclass.jpg

Note: Such an "Is-A" relationship can be created between two entities.

Note: Such an "Is-A" relationship can be deleted by selecting the connection and pressing either the Delete button or using the Delete context menu.

Using Derived Identifiers

In the Eclipse IDE create new JPA 2.0 project. Open its diagram editor and create two entities. For more information how to create new entity follow the steps described in the previous sections Create new Entity.

From the rifght site of the editor, the so called Palette, select One-to-One unidirectional feature, under Derived Identifiers section. Click on the first entity (the dependent entity) and drag&drop the connection to the second entity (the parent entity). Following some of the rules, described in the wiki Editing Derived Identifiers in JPA Diagram Editor, a new one-to-one unidirectional relationship will be created, in which the owner attribute will be mapped as primary key:

SimpleOneToOneDerivedId.jpg

Note: When the connection is deleted, if the dependent entity has a composite primary key, the helper attribute, that is added during creation of the relation, is deleted too, if it is not used by any other entity.

Additional Information

For more detailed information about the usage of the JPA Editor watch the JPA Diagram Editor Demo.