Editing JavaJEEJPA (section)

=Introduction=
The Java Persistence API (JPA) originated as part of the work of the [[JavaLanguage#History|JSR]] 220 Expert Group. JPA 2.0 is the work of the JSR 317 Expert Group. The final release date of the JPA 1.0 specification was 11 May 2006. The JPA 2.0 specification was released 10 Dec, 2009. JPA is a replacement for the much criticized EJB 2.0 and EJB 2.1 entity beans.

The easiest way is to use [[JavaJEEJPA#Annotations|annotations]]. To search for entities there is JPQL. The API defines the interface and is no '''persistence provider'''. This is for example JBoss or Glassfish. 

==Implementations==
Hibernate Versions 3.2 and later provide an implementation for the Java Persistence API.

==Entity Manager==
The central instance of the JPA is the '''entity manager''' (persistence manager) (interface javax.persistence.EntityManager), which is provided by the persistence provider. Each EntityManager instance is associated with a '''persistence context''': a set of managed entity instances that exist in a particular data store. A persistence context is more or less a cache of objects. The entitiy manager is similar to a persistence context.

The entity manager is responsible for 
* first '''persist''' of an object
* '''merge''' of an object state with the state in the database, detached objects werden wieder vom entity manager verwaltet
* '''remove''' an object from the database
* '''find''' an enitity by primary key or '''query''' by JPQL
* '''lock''' an entity
* '''flush''' the persistence context
* '''close'''  the entity manager.
The entity manager is accessed via JNDI or in an EJB container by injection (javax.persistence.PeristenceContext).

 EntityManagerFactory emf = Persistence.createEntityManagerFactory(<PersistenceUnitName>);
 EntityManager em = emf.createEntityManager();
 ...
 em.close();

==Entities==
An '''entity''' can have different states:
* '''transient''' (created by new(), no associated row in database)
* '''persistent''' (has an database identity, are associated with a persistence context)
* '''removed''' (by remove())
* '''detached''' (lived on over a transaction)

===Entity Identity===
Using an ORM introduces additional constraints on object identity. Defining the properties that make up an entity’s natural identity can be tricky, but is very important. Using the object’s identity, or the synthetic identity (database generated primary key) identity can introduce unexpected bugs into your application, so you should always ensure you use a natural identity. The identity is defined by [[JavaJEEJPA#javax.persistence.Id|@Id annotation]].  The type should not be native type, but a class, because a null value is by convention used for not stored objects. For instance it could be of type Long.

For composite keys you have three options:
# encapsulate the identifier properties in a separate class and mark it as @Embeddable. Include an attribute of this class in the entity class an mark it with @Id
# encapsulale the identifier properties in a separate class without annotation, include an attribute of this class in the entity class and mark it with @EmbeddedId
# @IdClass

===Entity Implementation===
with Spring Boot and Lombok:
# <code>@Entity</code> annotation at class level
# extend my BaseEntity class (documentation in java file)
# decide if field or property access (by placing the annotations at the fields or at the getters). This a philosophical discussion in the community, but field access seems to be the easiest and appropriate way.
# public or protected no-arg default ctor (e.g. Lombok @NoArgsConstructor)
# <code>implements Serializable</code> 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
# if not using Lombok annotation implement hashCode() and equals() if possible on a business or natural key and not on a generated id. Best solution is a generated UUID (search the web)
# create DB table - iff you let the JPA provider create the DB tables for the entity there is a default mapping of Java types to DB columns. This could be a problem because for example the [[#Default_Mapping_for_Java_types|default mapping]] of String is VARCHAR(255), so strings are truncated to 255 chars. In most cases it is better to create the DB tables by a script. Topics to consider are:
##NOT NULL
##AUTOINCREMENT
##initial value
# attribute names are mapped to db columns
## no capital letters
## capital letters in a string a prefixed with a underscore e.g. targetDate => target_date, isDone => is_done

===Default Mapping for Java types===
* Date -> DATETIME
* Long -> BIGINT(20)
* String -> VARCHAR(255)
* @LOB String -> LONGTEXT

==Manipulating Entities==

===Merge===
Merge creates a new instance of your entity, copies the state from the supplied entity, and makes the new copy managed. The instance you pass in will not be managed (any changes you make will not be part of the transaction - unless you call merge again):
* Find an attached object with the same id and update it.
* If exists update and return the already attached object.
* If doesn't exist insert the new register to the database

===Persist===
Persist takes an entity instance, adds it to the context and makes that instance managed (ie future updates to the entity will be tracked):
* Insert a new register to the database
* Attach the object to the entity manager.

===Remove===
To remove an entity object from the database, make a call to EntityManager.remove(entityObject) method. The entity object that is passed to the remove() must be a managed entity, else the operation will fail.