EJB 3 Entities. Course Multi Tier Business Applications with Java EE. Prof. Dr. Eric Dubuis Berner Fachhochschule Biel. Berner Fachhochschule

Transcription

1 Berner Fachhochschule Technik und Informatik EJB 3 Entities Course Multi Tier Business Applications with Java EE Prof. Dr. Eric Dubuis Berner Fachhochschule Biel

2 Content Characteristics of entities Programming aspects Primary keys An example The entity manager and persistence unit Entities' life cycle Embeddable classes April 25, 2008 MTA with Java EE / Stateless Session Beans 2

3 What Are EJB 3.0 Entities? An EJB 3.0 entity is a lightweight persistent domain object, programmed as POJO. Properties: entities are long-lived Think of an object that represents a row in a table of a relational database. The columns' cells corresponds to instance variables of the object. entities survive server restarts1 entities survive server failures entities are a view into a database/a persistent store entities instances can be pooled entities can be created, removed, or found EJB entities are based on the Java Persistence API which can be used outside of a container, too. These notes handle inside-container usage only. April 25, 2008 MTA with Java EE / Stateless Session Beans 3

4 What are Entities Used For? Entities are used for: To denote durable things (domain objects) such as: Customer Account Order Resources such as cabins,... etc. Note: An EJB container must support also the heavy-weight EJB 2.x entity beans. (not discussed) April 25, 2008 MTA with Java EE / Stateless Session Beans 4

5 Requirements on the Entity Class [EJB Persistence, 2.1ff] The entity class must be annotated with annotation (or denoted in the XML descriptor as an public class CustomerEntity { // optional: may implement // business interface... The entity class must have a no-arg constructor. The entity class may have other constructors as well. The no-arg constructor must be public or protected. Class must not be final, no interface, and no enum. If an entity instance is to be passed by value as a detached object (e.g., through a remote interface), the entity class must implement the Serializable interface. import javax.persistence.entity import public class CustomerEntity implements Serializeable {... April 25, 2008 MTA with Java EE / Stateless Session Beans 5

6 Requirements on the Entity Class (continued) Entities support inheritance, polymorphic associations, and polymorphic queries. Instance variables must be private, protected, or package visible (<== state). Both, abstract and concrete classes can be entities. Entities may extend non-entity classes as well as entity classes, and non-entity classes may extend entity classes. The state of the entity is available to clients only through the entity s accessor methods (getter/setter methods) or other business methods. «entity» P «entity» Q «entity» A {abstract «entity» B * 1 «entity» Z queries: return Q's, too association: Q's are associated with Z's, too «class» C {abstract «entity» D April 25, 2008 MTA with Java EE / Stateless Session Beans 6

7 Definition Entity { String name() default ""; The name annotation element defaults to the unqualified name of the entity class. This name is used to refer to the entity in queries. The name must not be a reserved literal (key word) in EJB QL. EJB QL (or JPQL): query language of the Java Persistence API. April 25, 2008 MTA with Java EE / Stateless Session Beans 7

8 Definition of the Access Type The persistent state is accessed by the persistence provider runtime via: Field access: For public class CustomerEntity... private int id; Property access: For public class CustomerEntity... { private int public Object getid() { return this.id; public void setid(object id) { this.id = id; A single access type (field or property access) applies to an entity hierarchy. April 25, 2008 MTA with Java EE / Stateless Session Beans 8

9 Properties of Persistent Fields The persistent fields or properties of an entity may be of the following types: Java primitive types; java.lang.string; other Java serializable types (including wrappers of the primitive types, java.math.biginteger, java.math.bigdecimal, java.util.date, java.util.calendar, java.sql.date, java.sql.time, java.sql.timestamp, user-defined serializable types, byte[], Byte[], char[], and Character[]); enum's; entity types and/or collections of entity types; and embeddable classes (see [EJB Persistence, 2.1.5]). Can pass entities / collections of entities from container to client or vice versa... April 25, 2008 MTA with Java EE / Stateless Session Beans 9

10 Properties of Persistent Fields (continued) The persistent state of an entity is accessed by the persistence provider runtime either via JavaBeans style property accessors or via instance variables. If the entity has field-based access, the persistence provider runtime accesses instance variables directly. All non-transient instance variables that are not annotated with annotation are persistent. When field-based access is used, the object/relational mapping annotations for the entity class annotate the instance variables. If the entity has property-based access, the persistence provider runtime accesses persistent state via the property accessor methods. All properties not annotated with annotation are persistent. The property accessor methods must be public or protected. When property-based access is used, the object/relational mapping annotations for the entity class annotate the getter property accessors. April 25, 2008 MTA with Java EE / Stateless Session Beans 10

11 Properties of Persistent Fields (continued) Method signatures for single-valued properties: T getproperty() void setproperty(t t) Collection-valued persistent fields and properties must be defined by the following Java Collection Framework interfaces (for example: Set<Order>): java.util.collection java.util.set java.util.list java.util.map For an ordering of members, see [EJB Core, p.19, footnote 4]. April 25, 2008 MTA with Java EE / Stateless Session Beans 11

12 Primary Keys Every entity must have a primary key. A simple primary key corresponds to a single persistent field or property. A composite primary key corresponds to: (==> implies primary key class) either to a single persistent field or property or a set of fields or properties. A primary key (or field or property of a composite primary key) must be: a Java primitive type; any primitive wrapper type; java.lang.string or java.util.date or java.sql.date Note 1: Approximate numeric (floating point types such as double) must not be used. Note 2: Primary key classes: not discussed, see [EJB Persistence 2.1.4]. April 25, 2008 MTA with Java EE / Stateless Session Beans 12

13 Primary Annotation annotation selects the identifier property an entity root Id { public class private int id; // getter only: public Object getid() { return this.id; autoboxing April 25, 2008 MTA with Java EE / Stateless Session Beans 13

14 Id Generation Strategy I You can specify the Id generation strategy. public enum GenerationType { TABLE, SEQUENCE, IDENTITY, AUTO GeneratedValue { GenerationType strategy() default AUTO; String generator() default ""; April 25, 2008 MTA with Java EE / Stateless Session Beans 14

15 Id Generation Strategy Type Name Description Default GenerationType strategy String (Optional) The primary key generation strategy that the persistence provider must use to generate the annotated entity primary key. generator (Optional) The name of the primary key generator to use as specified in the SequenceGenerator or TableGenerator annotation. GenerationType.AUTO Default id generator supplied by persistence provider Some Notes on the Primary Key Generation Use GenerationType.TABLE when using entity bean inheritance. For more informations, see [EJB Persistence, 9.1.9] April 25, 2008 MTA with Java EE / Stateless Session Beans 15

16 A First Entity Example: = "EJB3_SALES_CUSTOMER") // Default: Bean class name public class CustomerEntity implements Customer, Serializable // field access // GenerationType.AUTO will be used private int id; private String firstname; private String lastname; public CustomerEntity() { // public no-arg constructor public CustomerEntity(String firstname, String lastname) { this.firstname = firstname; this.lastname = lastname; // continued... April 25, 2008 MTA with Java EE / Stateless Session Beans 16

17 A First Entity Example: A Customer (continued) // Needed by application itself: public int getid() { return this.id; public String getfirstname() { return this.firstname; public void setfirstname(string firstname) { this.firstname = firstname; // other setters and getters omitted... April 25, 2008 MTA with Java EE / Stateless Session Beans 17

18 A First Entity Example: Remarks An entity class may implement the business interface. An entity class must have a public (or protected) no-arg constructor. An entity class may have other constructors as well. An entity class may implement the Serializable interface; if so, instances of that class can be detached and passed to remote clients. An instance of an entity class is created via the new operator, see below. When first created, the entity bean is not yet persistent. An entity instance becomes persistent by means of the entity manager, see below. April 25, 2008 MTA with Java EE / Stateless Session Beans 18

19 A Stateless Session Bean as Customer Manager Let's introduce a stateless session bean to manage (create, list, and update) Customer beans. The manager's remote (business) interface import public interface CustomerManager { public Object createcustomer(customer customer); public Customer getcustomerbyid(object id); public ValueListHandler<Customer> getcustomerlisthandler(string pattern); // *) public void updatecustomer(customer customer); public void deletecustomer(object id); *) See the Value List Handler Java EE pattern at: April 25, 2008 MTA with Java EE / Stateless Session Beans 19

20 A Stateless Session Bean as Customer Manager (cont'd) The Bean Class import java.util.*; import javax.ejb.stateless; import javax.persistence.entitymanager; import javax.persistence.persistencecontext; import javax.persistence.query; injected by the public class CustomerManagerBean implements CustomerManager private EntityManager manager; // business methods shown on next slide. April 25, 2008 MTA with Java EE / Stateless Session Beans 20

21 A Stateless Session Bean as Customer Manager (con'd) instance of type The Bean Class (continued) CustomerEntity is given // in class CustomerManagerBean: public Object createcustomer(customer customer) { this.manager.persist(customer); return customer.getid(); public ValueListHandler<Customer> getcustomerlisthandler(string pattern) { // See exercise. return valuelisthandler; public void updatecustomer(customer customer) { this.manager.merge(customer); merge() is not void public void deletecustomer(object id) { Customer c = this.manager.find(customerentity.class, id); this.manager.remove(c); April 25, 2008 MTA with Java EE / Stateless Session Beans 21

22 Excerpt of a Client A client creates, lists, and modifies Customer entities with the help of the CustomerManager instance: public class SalesClient { private EntityFactory factory =...; { // in some method: CustomerManager cm = getservicelocator().getcustomermanager(); factory Customer customer = shields factory.createcustomer("hans", "..:",...); technology cm.createcustomer(customer); service locator is used here // list customers, update, and delete customers... April 25, 2008 MTA with Java EE / Stateless Session Beans 22

23 The Entity Manager [EJB Persistence, 3ff.] Purpose: The entity manager manages the entity instance life cycle. Persistence context: [...] A set of entity instances in which for any entity identity there is a unique entity instance. The entity manager defines methods to interact with the persistence context. April 25, 2008 MTA with Java EE / Stateless Session Beans 23

24 Entity Manager API (Excerpt) package javax.persistence; persist(): for creating new entities merge(): for updating public interface EntityManager { public void persist(object entity); public <T> T merge(t entity); public void remove(object entity); public <T> T find(class<t> entityclass, Object existing entities primarykey);... public void flush(); public void refresh(object entity); public boolean contains(object entity); public Query createquery(string ejbqlstring); public Query createnamedquery(string name); Will be treated later April 25, 2008 MTA with Java EE / Stateless Session Beans 24

25 What is the Persistence Provider? A mechanism to transfer entity information back and forth between the Java object (POJO1) and the database. Most often: relational database, but could also be an object database. A concrete persistence provider must implement the Persistence Provider SPI (SPI: service provider interface) It's the duty of the persistence provider to worry about the proper time to load, store, and refresh the data of the entity. April 25, 2008 MTA with Java EE / Stateless Session Beans 25

26 Accessing the Persistence Context Use annotation to declare an EntityManager instance variable of a session bean. The EJB container injects the/a persistence context. By default, entities stay managed within the scope of a single transaction: // in a stateless session private EntityManager manager; public void transfer(int acno1, int acno2, double amount) { Account account1 = this.manager.find(account.class, acno1); Account account2 = this.manager.find(account.class, acno2); account1.withdraw(amount); account2.deposit(amount); April 25, 2008 MTA with Java EE / Stateless Session Beans 26

27 Accessing the Persistence Context (cont'd) To keep an entity managed during the span of several transactions, you'll use an extended persistence context: // in a stateful session = PersistenceContextType.EXTENDED) private EntityManager manager; Account managed during several private Account account = null; method calls public void open(int num) { this.account = this.manager.find(account.class, num); public void deposit(double amount) { if (this.account == null) throw new IllegalStateException("..."); this.account.deposit(amount); April 25, 2008 MTA with Java EE / Stateless Session Beans 27

28 Defining a Persistence Unit A persistence unit must be defined in the XML file persistence.xml the JAR's META-INF directory. It can be as simple as: <?xml version="1.0" encoding="utf-8"?> <persistence> <persistence-unit name="sales"> <jta-data-source>java:/defaultds</jta-data-source> <properties> <property </properties> </persistence-unit> </persistence> name="hibernate.hbm2ddl.auto" value="create-drop"/> JNDI name of data source appserver specific April 25, 2008 MTA with Java EE / Stateless Session Beans 28

29 Entities' Life Cycle An entity is in one of the following states: new persist New Managed remove persist Removed merge persistence context ends Detached April 25, 2008 MTA with Java EE / Stateless Session Beans 29

30 Embeddable Classes [EJB Persistence, 2.1.5] An entity may use a fine-grained class. For example, entity Customer may use an Address instance, but this instance exists only as embedded object of the entity to which it belongs. Embeddable classes: are ordinary POJOs implement java.io.serializable cannot be shared among entities access type is determined by the enclosing entity class Embeddable classes are Embeddable { AccessType access() default PROPERTY; April 25, 2008 MTA with Java EE / Stateless Session Beans 30

31 Example Class Address: import public class Address implements Serializable { private String street; // other instance variables... public Address() { // no-arg constructor required public Address(String street, String place, String country) { // initialize instance variables... // public getters // (setters can be omitted if access type // of enclosing entity is FIELD) April 25, 2008 MTA with Java EE / Stateless Session Beans 31

32 Embeddable Class: How It Is Used You use and embeddable class in an entity class = "EJB3_SALES_CUSTOMER") public class CustomerEntity implements Customer, private int id; private String private Address address; public Customer() { // public no-arg constructor public Customer(String firstname, String lastname, Address address) {... this.address = address; // getters and setters as before, and... (next slide) April 25, 2008 MTA with Java EE / Stateless Session Beans 32

33 Embeddable Class: How It Is Used (cont'd)... public Address getaddress() { return this.address; public void setaddress(address address) { this.address = address; By default the fields of the Address class will be mapped onto columns of the Customer bean table April 25, 2008 MTA with Java EE / Stateless Session Beans 33

34 References [EJB] JSR 220: Enterprise JavaBeans, Version 3.0 EJB 3.0 Simplified API [EJB Core] JSR 220: Enterprise JavaBeans, Version 3.0 EJB Core Contracts and Requirements [EJB Persistence] JSR 220: Enterprise JavaBeansTM,Version 3.0 Java Persistence API April 25, 2008 MTA with Java EE / Stateless Session Beans 34