JBoss.orgCommunity Documentation
Errai JPA is deprecated. These features are no longer being updated and will be removed in a future release.
Starting with Errai 2.1, Errai implements a subset of JPA 2.0. With Errai JPA, you can store and retrieve entity objects on the client side, in the browser’s local storage. This allows the reuse of JPA-related code (both entity class definitions and procedural logic that uses the EntityManager) between client and server.
Errai JPA implements the following subset of JPA 2.0:
Errai JPA is a declarative, typesafe interface to the web browser’s localStorage object. As such it is a client-side implementation of JPA. Objects are stored and fetched from the browser’s local storage, not from the JPA provider on the server side.
Checkout the Manual Setup Section for instructions on how to manually add Errai JPA to your project.
Errai ignores META-INF/persistence.xml for purposes of client-side JPA. Instead, Errai scans all Java packages that are part of your GWT modules for classes annotated with @Entity. This allows you the freedom of defining a persistence.xml that includes both shared entity classes that you use on the client and the server, plus server-only entities that are defined in a server-only package.
Classes whose instances can be stored and retrieved by JPA are called entities. To declare a class as a JPA entity, annotate it with @Entity.
JPA requires that entity classes conform to a set of rules. These are:
Here is an example of a valid entity class with an ID attribute (id) and a String-valued persistent attribute (name):
@Entity
public class Genre {
@Id @GeneratedValue
private int id;
private String name;
// This constructor is used by JPA
public Genre() {}
// This constructor is not used by JPA
public Genre(String name) {
this();
this.name = name;
}
// These getter and Setter methods are optional:
public int getId() { return id; }
public void setId(int id) { this.id = id; }
public String getName() { return name; }
public void setName(String name) { this.name = name; }
}
The state of fields and JavaBeans properties of entities are generally persisted with the entity instance. These persistent things are called attributes.
JPA Attributes are subdivided into two main types: singular and plural. Singular attributes are scalar types like Integer or String. Plural attributes are collection values, such as List<Integer> or Set<String>.
The values of singular attributes (and the elements of plural attributes) can be of any application-defined entity type or a JPA Basic type. The JPA basic types are all of the Java primitive types, all boxed primitives, enums, BigInteger, BigDecimal, String, Date (java.util.Date or java.sql.Date), Time, and Timestamp.
You can direct JPA to read and write your entity’s attributes by direct field access or via JavaBeans property access methods (that is, "getters and setters"). Direct field access is the default. To request property access, annotate the class with @Access(AccessType.PROPERTY). If using direct field access, attribute-specific JPA annotations should be on the fields themselves; when using property access, the attribute-specific annotations should be on the getter method for that property.
Each entity class must have exactly one ID attribute. The value of this attribute together with the fully-qualified class name uniquely identifies an instance to the entity manager.
ID values can be assigned by the application, or they can be generated by the JPA entity manager. To declare a generated identifier, annotate the field with @GeneratedValue. To declare an application-assigned identifier, leave off the @GeneratedValue annotation.
Generated identifier fields must not be initialized or modified by application code. Application-assigned identifier fields must be initialized to a unique value before the entity is persisted by the entity manager, but must not be modified afterward.
By default, every field of a JPA basic type is a persistent attribute. If a basic type field should not be presistent, mark it with transient or annotate it with @Transient.
Single-valued attributes of entity types must be annotated with @OneToOne or @ManyToOne.
Single-valued types that are neither entity types nor JPA Basic types are not presently supported by Errai JPA. Such attributes must be marked transient.
Here is an example of an entity with single-valued basic attributes and a single-valued relation to another entity type:
@Entity
public class Album {
@GeneratedValue
@Id
private Long id;
private String name;
@ManyToOne
private Artist artist;
private Date releaseDate;
private Format format;
public Long getId() { return id; }
public void setId(Long id) { this.id = id; }
public String getName() { return name; }
public void setName(String name) { this.name = name; }
public Artist getArtist() { return artist; }
public void setArtist(Artist artist) { this.artist = artist; }
public Date getReleaseDate() { return releaseDate; }
public void setReleaseDate(Date releaseDate) { this.releaseDate = releaseDate; }
public Format getFormat() { return format; }
public void setFormat(Format format) { this.format = format; }
}
[[sid-54493688_ErraiJPA-Plural%28collectionvalued%29Attributes]]
Collection-valued types Collection<T>, Set<T>, and List<T> are supported. JPA rules require that all access to the collections are done through the collection interface method; never by specific methods on an implementation.
The element type of a collection attribute can be a JPA basic type or an entity type. If it is an entity type, the attribute must be annotated with @OneToMany or @ManyToMany.
Here is an example of an entity with two plural attributes:
@Entity
public class Artist {
@Id
private Long id;
private String name;
// a two-way relationship (albums refer back to artists)
@OneToMany(mappedBy="artist", cascade=CascadeType.ALL)
private Set<Album> albums = new HashSet<Album>();
// a one-way relationship (genres don't reference artists)
@OneToMany(cascade={CascadeType.PERSIST, CascadeType.MERGE})
private Set<Genre> genres = new HashSet<Genre>();
public Long getId() { return id; }
public void setId(Long id) { this.id = id; }
public String getName() { return name; }
public void setName(String name) { this.name = name; }
public Set<Album> getAlbums() { return albums; }
public void setAlbums(Set<Album> albums) { this.albums = albums; }
public Set<Genre> getGenres() { return genres; }
public void setGenres(Set<Genre> genres) { this.genres = genres; }
}
When an entity changes state (more on this later), that state change can be cascaded automatically to related entity instances. By default, no state changes are cascaded to related entities. To request cascading of entity state changes, use the cascade attribute on any of the relationship quantifiers @OneToOne, @ManyToOne, @OneToMany, and @ManyToMany.
| CascadeType value | Description |
|---|---|
PERSIST | Persist the related entity object(s) when this entity is persisted |
MERGE | Merge the attributes of the related entity object(s) when this entity is merged |
REMOVE | Remove the related entity object(s) from persistent storage when this one is removed |
REFRESH | Not applicable in Errai JPA |
DETACH | Detach the related entity object(s) from the entity manager when this object is detached |
ALL | Equivalent to specifying all of the above |
For an example of specifying cascade rules, refer to the Artist example above. In that example, the cascade type on albums is ALL. When a particular Artist is persisted or removed, detached, etc., all of that artist’s albums will also be persisted or removed, or detached correspondingly. However, the cascade rules for genres are different: we only specify PERSIST and MERGE. Because a Genre instance is reusable and potentially shared between many artists, we do not want to remove or detach these when one artist that references them is removed or detached. However, we still want the convenience of automatic cascading persistence in case we persist an Artist which references a new, unmanaged Genre.
The entity manager provides the means for storing, retrieving, removing, and otherwise affecting the lifecycle state of entity instances.
To obtain an instance of EntityManager on the client side, use Errai IoC (or CDI) to inject it into any client-side bean:
@EntryPoint
public class Main {
@Inject EntityManager em;
}
To store an entity object in persistent storage, pass that object to the EntityManager.persist() method. Once this is done, the entity instance transitions from the new state to the managed state.
If the entity references any related entities, these entities must be in the managed state already, or have cascade-on-persist enabled. If neither of these criteria are met, an IllegalStateException will be thrown.
See an example in the following section.
If you know the unique ID of an entity object, you can use the EntityManager.find() method to retrieve it from persistent storage. The object returned from the find() method will be in the managed state.
Example:
// make it
Album album = new Album();
album.setArtist(null);
album.setName("Abbey Road");
album.setReleaseDate(new Date(-8366400000L));
// store it
EntityManager em = getEntityManager();
em.persist(album);
em.flush();
em.detach(album);
assertNotNull(album.getId());
// fetch it
Album fetchedAlbum = em.find(Album.class, album.getId());
assertNotSame(album, fetchedAlbum);
assertEquals(album.toString(), fetchedAlbum.toString());
To remove a persistent managed entity, pass it to the EntityManager.remove() method. As the cascade rules specify, related entities will also be removed recursively.
Once an entity has been removed and the entity manager’s state has been flushed, the entity object is unmanaged and back in the new state.
Errai’s EntityManager class provides a removeAll() method which removes everything from the browser’s persistent store for the domain of the current webpage.
This method is not part of the JPA standard, so you must down-cast your client-side EntityManager instance to ErraiEntityManager. Example:
@EntryPoint
public class Main {
@Inject EntityManager em;
void resetJpaStorage() {
((ErraiEntityManager) em).removeAll();
}
}
For every entity instance in the managed state, changes to the attribute values of that entity are persisted to local storage whenever the entity manager is flushed. To prevent this automatic updating from happening, you can detach an entity from the entity manager. When an instance is detached, it is not deleted. All information about it remains in persistent storage. The next time that entity is retrieved, the entity manager will create a new and separate managed instance for it.
To detach one particular object along with all related objects whose cascade rules say so, call EntityManager.detach() and pass in that object.
To detach all objects from the entity manager at once, call EntityManager.detachAll().
To retrieve one or more entities that match a set of criteria, Errai JPA allows the use of JPA named queries. Named queries are declared in annotations on entity classes.
Queries in JPA are written in the JPQL language. As of Errai 2.1, Errai JPA does not support all JPQL features. Most importantly, implicit and explicit joins in queries are not yet supported. Queries of the following form generally work:
SELECT et FROM EntityType et WHERE [expression with constants, named parameters and attributes of et] ORDER BY et.attr1 [ASC|DESC], et.attr2 [ASC|DESC]
Here is how to declare a JPQL query on an entity:
@NamedQuery(name="selectAlbumByName", query="SELECT a FROM Album a WHERE a.name=:name")
@Entity
public class Album {
... same as before ...
}
To declare more than one query on the same entity, wrap the @NamedQuery annotations in @NamedQueries like this:
@NamedQueries({
@NamedQuery(name="selectAlbumByName", query="SELECT a FROM Album a WHERE a.name = :name"),
@NamedQuery(name="selectAlbumsAfter", query="SELECT a FROM Album a WHERE a.releaseDate >= :startDate")
})
@Entity
public class Album {
... same as before ...
}
To execute a named query, retrieve it by name and result type from the entity manager, set the values of its parameters (if any), and then call one of the execution methods getSingleResult() or getResultList().
Example:
TypedQuery<Album> q = em.createNamedQuery("selectAlbumByName", Album.class);
q.setParameter("name", "Let It Be");
List<Album> fetchedAlbums = q.getResultList();
To receive a notification when an entity instance transitions from one lifecycle state to another, use an entity lifecycle listener.
These annotations can be applied to methods in order to receive notifications at certain points in an entity’s lifecycle. These events are delivered for direct operations initiated on the EntityManager as well as operations that happen due to cascade rules.
| Annotation | Meaning |
|---|---|
@PrePersist | The entity is about to be persisted or merged into the entity manager. |
@PostPersist | The entity has just been persisted or merged into the entity manager. |
@PreUpdate | The entity’s state is about to be captured into the browser’s localStorage. |
@PostUpdate | The entity’s state has just been captured into the browser’s localStorage. |
@PreRemove | The entity is about to be removed from persistent storage. |
@PostRemove | The entity has just been removed from persistent storage. |
@PostLoad | The entity’s state has just been retrieved from the browser’s localStorage. |
JPA lifecycle event annotations can be placed on methods in the entity type itself, or on a method of any type with a public no-args constructor.
To receive lifecycle event notifications directly on the affected entity instance, create a no-args method on the entity class and annotate it with one or more of the lifecycle annotations in the above table.
For example, here is a variant of the Album class where instances receive notification right after they are loaded from persistent storage:
@Entity
public class Album {
... same as before ...
@PostLoad
public void postLoad() {
System.out.println("Album " + getName() + " was just loaded into the entity manager");
}
}
To receive lifecycle methods in a different class, declare a method that takes one parameter of the entity type and annotate it with the desired lifecycle annotations. Then name that class in the @EntityListeners annotation on the entity type.
The following example produces the same results as the previous example:
@Entity
@EntityListeners(StandaloneLifecycleListener.class)
public class Album {
... same as always ...
}
public class StandaloneLifecycleListener {
@PostLoad
public void albumLoaded(Album a) {
public void postLoad() {
System.out.println("Album " + a.getName() + " was just loaded into the entity manager");
}
}
Errai captures structural information about entity types at compile time and makes them available in the GWT runtime environment. The JPA metamodel includes methods for enumerating all known entity types and enumerating the singular and plural attributes of those types. Errai extends the JPA 2.0 Metamodel by providing methods that can create new instances of entity classes, and read and write attribute values of existing entity instances.
As an example of what is possible, this functionality could be used to create a reusable UI widget that can present an editable table of any JPA entity type.
To access the JPA Metamodel, call the EntityManager.getMetamodel() method. For details on what can be done with the stock JPA metamodel, see the API’s javadoc or consult the JPA specification.
Wherever you obtain an instance of SingularAttribute from the metamodel API, you can down-cast it to ErraiSingularAttribute. Likewise, you can down-cast any PluralAttribute to ErraiPluralAttribute.
In either case, you can read the value of an arbitrary attribute by calling ErraiAttribute.get() and passing in the entity instance. You can set any attribute’s value by calling ErraiAttribute.set(), passing in the entity instance and the new value.
In addition to get() and set(), ErraiPluralAttribute also has the createEmptyCollection() method, which creates an empty collection of the correct interface type for the given attribute.
The following features are not yet implemented, but could conceivably be implemented in a future Errai JPA release:
The following may never be implemented due to limitations and restrictions in the GWT client-side environment:
Traditional JPA implementations allow you to store and retrieve entity objects on the server side. Errai’s JPA implementation allows you to store and retrieve entity objects in the web browser using the same APIs. All that’s missing is the ability to synchronize the stored data between the server side and the client side.
This is where Errai JPA Data Sync comes in: it provides an easy mechanism for two-way synchronization of data sets between the client and the server.
Checkout the Manual Setup Section for instructions on how to manually add Errai JPA Datasync to your project.
For the rest of this chapter, we will refer to the following Entity classes, which are defined in a shared package that’s visible to client and server code:
@Portable
@Entity
@NamedQuery(name = "allUsers", query = "SELECT u FROM User u")
public class User {
@Id
@GeneratedValue
private long id;
private String name;
// getters and setters omitted
}
@Portable
@Entity
@NamedQuery(name = "groceryListsForUser", query = "SELECT gl FROM GroceryList gl WHERE gl.owner=:user")
public class GroceryList {
@Id
@GeneratedValue
private long id;
@ManyToOne
private User owner;
@OneToMany(cascade = { CascadeType.PERSIST, CascadeType.MERGE, CascadeType.REFRESH })
private List<Item> items = new ArrayList<Item>();
// getters and setters omitted
}
@Portable
@Entity
@NamedQuery(name = "allItems", query = "SELECT i FROM Item i")
public class Item {
@Id
@GeneratedValue
private long id;
private String name;
private String department;
private String comment;
private Date addedOn;
@ManyToOne(cascade = { CascadeType.PERSIST, CascadeType.MERGE, CascadeType.REFRESH })
private User addedBy;
// getters and setters omitted
}
To summarize: there are three entity types: User, GroceryList, and Item. Each GroceryList belongs to a User and has a list of Item objects.
All the entities involved in the data synchronization request must be marshallable via Errai Marshalling. This is normally accomplished by adding the @Portable annotation to each JPA entity class, but it is also acceptable to list them in ErraiApp.properties. See the Marshalling section for more details.
Now let’s say we want to synchronize the data for all of a user’s grocery lists. This will make them available for offline use through Errai JPA, and at the same time it will update the server with the latest changes made on the client. Ultimately, the sync operation is accomplished via an annotated method or an asynchronous call into ClientSyncManager, but first we have to prepare a few things on the client and the server.
[[sid-71467090_ErraiJPADataSync-ServerSide%E2%80%93DataSyncServiceImpl]]
A data sync operation begins when the client-side sync manager sends an Errai RPC request to the server. Although a server-side implementation of the remote interface is provided, you are responsible for implementing a thin wrapper around it. This wrapper serves two purposes:
If you are deploying to a container that supports CDI and EJB 3, you can use this DataSyncServiceImpl as a template for your own:
@Stateless @org.jboss.errai.bus.server.annotations.Service
public class DataSyncServiceImpl implements DataSyncService {
@PersistenceContext
private EntityManager em;
private final JpaAttributeAccessor attributeAccessor = new JavaReflectionAttributeAccessor();
@Inject private LoginService loginService;
@Override
public <X> List<SyncResponse<X>> coldSync(SyncableDataSet<X> dataSet, List<SyncRequestOperation<X>> remoteResults) {
// Ensure a user is logged in
User currentUser = loginService.whoAmI();
if (currentUser == null) {
throw new IllegalStateException("Nobody is logged in!");
}
// Ensure user is accessing their own data!
if (dataSet.getQueryName().equals("groceryListsForUser")) {
User requestedUser = (User) dataSet.getParameters().get("user");
if (!currentUser.getId().equals(requestedUser.getId())) {
throw new AccessDeniedException("You don't have permission to sync user " + requestedUser.getId());
}
}
else {
throw new IllegalArgumentException("You don't have permission to sync dataset " + dataSet.getQueryName());
}
DataSyncService dss = new org.jboss.errai.jpa.sync.server.DataSyncServiceImpl(em, attributeAccessor);
return dss.coldSync(dataSet, remoteResults);
}
}
If you are not using EJB 3, you will not be able to use the @PersistenceContext annotation. In this case, obtain a reference to your EntityManager the same way you would anywhere else in your application.
Like many Errai features, Errai JPA DataSync provides an annotation-driven programming model and a programmatic API. You can choose which to use based on your needs and preferences.
The declarative data sync API is driven by the @Sync annotation. Consider the following example client-side class:
// This injected User object could have been set up in a @PostConstruct method instead of being injected.
@Inject
private User syncThisUser;
@Sync(query = "groceryListsForUser", params = { @SyncParam(name = "user", val = "{syncThisUser}") })
private void onDataSyncComplete(SyncResponses<GroceryList> responses) {
Window.alert("Data Sync Complete!");
}
By placing the above code snippet in a client-side bean, you tell Errai JPA Data Sync that, as long as a managed
instance of the bean containing the @Sync method exists, the Data Sync system should keep all grocery lists
belonging to the syncThisUser user in sync between the client-side JPA EntityManager and the server-side EntityManager.
Right now, the data sets are kept in sync using a sync request every 5 seconds. In the future, this may be optimised
to an incremental approach that pushes changes as they occur.
The annotated method needs to have exactly one parameter of type SyncResponses and will
be called each time a data sync operation has completed. All sync operations passed to the
method will have already been applied to the local EntityManager, with conflicts resolved in
favour of the server’s version of the data. The original client values are available in the
SyncResponses object, which gives you a chance to implement a different conflict
resolution policy.
The query attribute on the @Sync annotation must refer to an existing JPA Named Query that is defined on a shared
JPA entity class.
The params attribute is an array of @SyncParam annotations. There must be exactly one @SyncParam for each named
parameter in the JPA query (positional parameters are not supported). If the val argument is surrounded with brace
brackets (as it is in the example aboce) then it is interpreted as a reference to a declared or inherited field in
the containing class. Otherwise, it is interpreted as a literal String value.
Field-reference sync params are captured just after the bean’s @PostConstruct method is invoked. This means that
values of referenced fields can be provided using @Inject (which in turn could come from a CDI Producer method)
or by code in the @PostConstruct method.
Transport (network) errors are logged to the slf4j logger channel org.jboss.errai.jpa.sync.client.local.ClientSyncWorker.
As of Errai 3.0.0.M4, it is not possible to specify a custom error handler using the declarative API. See the next
section for information about the programmatic API.
@Inject private ClientSyncManager syncManager;
@Inject private EntityManager em;
public void syncGroceryLists(User forUser) {
RemoteCallback<List<SyncResponse<GroceryList>>> onCompletion = new RemoteCallback<List<SyncResponse<GroceryList>>>() {
@Override
public void callback(List<SyncResponse<GroceryList>> response) {
Window.alert("Data Sync Complete!");
}
};
ErrorCallback<?> onError = new BusErrorCallback() {
@Override
public boolean error(Message message, Throwable throwable) {
Window.alert("Data Sync failed!");
return false;
}
};
Map<String, Object> queryParams = new HashMap<String, Object>();
queryParams.put("user", forUser);
syncManager.coldSync("groceryListsForUser", GroceryList.class, queryParams, onCompletion, onError);
}
The onCompletion and onError callbacks are optional. In the unlikely case that your application doesn’t care if a data sync request completed successfully, you can pass null for either callback.
Once your onCompletion callback has been notified, the server and client will have the same entities stored in their respective databases for all entities reachable from the given query result.
When the client sends the sync request to the server, it includes information about the state it expects each entity to be in. If an entity’s state on the server does not match this expected state on the client, the server ignores the client’s change request and includes a ConflictResponse object in the sync reply.
When the client processes the sync responses from the server, it applies the new state from the server to the local data store. This overwrites the change that was initially requested from the client. In short, you could call this the "server wins" conflict resolution policy.
In some cases, your application may be able to do something smarter: apply domain-specific knowledge to merge the conflict automatically, or prompt the user to perform a manual merge. In order to do this, you will have to examine the server response from inside the onCompletion callback you provided to the coldSync() method:
RemoteCallback<List<SyncResponse<GroceryList>>> onCompletion = new RemoteCallback<List<SyncResponse<GroceryList>>>() {
@Override
public void callback(List<SyncResponse<GroceryList>> responses) {
for (SyncResponse<GroceryList> response : responses) {
if (response instanceof ConflictResponse) {
ConflictResponse<GroceryList> cr = (ConflictResponse<GroceryList>) response;
List<Item> expectedItems = cr.getExpected().getItems();
List<Item> serverItems = cr.getActualNew().getItems();
List<Item> clientItems = cr.getRequestedNew().getItems();
// merge the list of items by comparing each to expectedItems
List<Item> merged = ...;
// update local storage with the merged list
em.find(GroceryList.class, cr.getActualNew().getId()).setItems(merged);
em.flush();
}
}
}
};
Remember, because of Errai’s default "server wins" resolution policy, the call to em.find(GroceryList.class, cr.getActualNew().getId()) will return a GroceryList object that has already been updated to match the state present in serverItems.
Searching for ConflictResponse objects in the onCompletion callback is the only way to recover client data that was clobbered in a conflict. If you do not merge this data back into local storage, or at least retain a reference to the cr.getRequestedNew() object, this conflicting client data will be lost forever.
In a future release of Errai JPA, we plan to provide a client-side callback mechanism for custom conflict handling. If such a callback is registered, it will override the default behaviour.