Welcome back to our tutorial series “NoSQL with Hibernate OGM”!
In this part you will learn how to use Hibernate OGM from within a Java EE application running on the WildFly server. Using the entity model you already know from the previous parts of this tutorial, we will build a small REST-based application for managing hikes. In case you haven’t read the first two installments of this series, you can find them here:
In the following you will learn how to prepare WildFly for using it with Hibernate OGM, configure a JPA persistence unit, create repository classes for accessing your data and providing REST resources on top of these. In this post we will primarily focus on the aspects related to persistence, so some basic experience with REST/JAX-RS may help. The complete source code of this tutorial is hosted on GitHub.
Preparing WildFly
The WildFly server runtime is based on the JBoss Modules system. This provides a modular class-loading environment where each library (such as Hibernate OGM) is its own module, declaring the list of other modules it depends on and only “seeing” classes from those other dependencies. This isolation provides an escape from the dreaded “classpath hell”.
ZIP files containing all the required modules for Hibernate OGM are provided on SourceForge. Hibernate OGM 4.2 - which we released yesterday - supports WildFly 9, so download hibernate-ogm-modules-wildfly9-4.2.0.Final.zip for that. If you are on WildFly 8, use Hibernate OGM 4.1 and get hibernate-ogm-modules-wildfly8-4.1.3.Final.zip instead.
Unzip the archive corresponding to your WildFly version into the modules directory of the application server. If you prefer that the original WildFly directories remain unchanged, you also can unzip the Hibernate OGM modules archive to any other folder and configure this as the “module path” to be used by the server. To do so, export the following two environment variables, matching your specific environment:
export JBOSS_HOME=/path/to/wildfly export JBOSS_MODULEPATH=$JBOSS_HOME/modules:/path/to/ogm/modules
In case you are working with the Maven WildFly plug-in, e.g. to launch WildFly during development, you’d achieve the same with the following plug-in configuration in your POM file:
...
<plugin>
<groupId>org.wildfly.plugins</groupId>
<artifactId>wildfly-maven-plugin</artifactId>
<version>1.1.0.Alpha1</version>
<configuration>
<jboss-home>/path/to/wildfly</jboss-home>
<modules-path>/path/to/ogm/modules</modules-path>
</configuration>
</plugin>
...Setting up the project
Start by creating a new Maven project using the “war” packaging type. Add the following to your pom.xml:
...
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.hibernate.ogm</groupId>
<artifactId>hibernate-ogm-bom</artifactId>
<type>pom</type>
<version>4.2.0.Final</version>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
...This makes sure you get matching versions of Hibernate OGM’s modules and any (optional) dependencies. Then add the dependency to the Java EE 7 API and one of the Hibernate OGM backend modules, e.g. Infinispan, JBoss’ high-performance, distributed key/value data grid (any other such as hibernate-ogm-mongodb or the brand-new hibernate-ogm-cassandra module would work as well):
...
<dependencies>
<dependency>
<groupId>javax</groupId>
<artifactId>javaee-api</artifactId>
<version>7.0</version>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>org.hibernate.ogm</groupId>
<artifactId>hibernate-ogm-infinispan</artifactId>
<scope>provided</scope>
</dependency>
</dependencies>
...The provided scope makes these dependencies available for compilation but prevents them from being added to the resulting WAR file. That it because the Java EE API is part of WildFly already, and Hibernate OGM will be contributed through the modules you unzipped before.
Just adding these modules to the server doesn’t cut it, though. They also need to be registered as a module dependency with the application. To do so, add the file src/main/webapp/WEB-INF/jboss-web.xml with the following contents:
<?xml version="1.0" encoding="UTF-8"?>
<jboss-deployment-structure
xmlns="urn:jboss:deployment-structure:1.2"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<deployment>
<dependencies>
<module name="org.hibernate" slot="ogm" services="import" />
<module name="org.hibernate.ogm.infinispan" services="import" />
<module name="org.hibernate.search.orm" services="import" />
</dependencies>
</deployment>
</jboss-deployment-structure>This will make Hibernate OGM core and the Infinispan backend as well as Hibernate Search available to your application. The latter will be used to run JP-QL queries in a bit.
Adding entity classes and repositories
With the basic project infrastructure in place, it’s time to add the entity classes and repository classes for accessing them. The entity types are basically the same as seen in part 1, only now they are annotated with @Indexed in order to allow them to be queried via Hibernate Search and Lucene:
@Entity
@Indexed
public class Person {
@Id
@GeneratedValue(generator = "uuid")
@GenericGenerator(name = "uuid", strategy = "uuid2")
private String id;
private String firstName;
private String lastName;
@OneToMany(
mappedBy = "organizer",
cascade = { CascadeType.PERSIST, CascadeType.MERGE },
fetch = FetchType.EAGER
)
private Set<Hike> organizedHikes = new HashSet<>();
// constructors, getters and setters...
}@Entity
@Indexed
public class Hike {
@Id
@GeneratedValue(generator = "uuid")
@GenericGenerator(name = "uuid", strategy = "uuid2")
private String id;
private String description;
private Date date;
private BigDecimal difficulty;
@ManyToOne
private Person organizer;
@ElementCollection(fetch = FetchType.EAGER)
@OrderColumn(name = "sectionNo")
private List<HikeSection> sections;
// constructors, getters and setters...
}@Embeddable
public class HikeSection {
private String start;
private String end;
// constructors, getters and setters...
}In order to use these entities, a JPA persistence unit must be defined. To do so, create the file src/main/resources/META-INF/persistence.xml:
<?xml version="1.0" encoding="utf-8"?>
<persistence xmlns="http://java.sun.com/xml/ns/persistence"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_1_0.xsd"
version="1.0">
<persistence-unit name="hike-PU" transaction-type="JTA">
<provider>org.hibernate.ogm.jpa.HibernateOgmPersistence</provider>
<class>org.hibernate.ogm.demos.ogm101.part3.model.Person</class>
<class>org.hibernate.ogm.demos.ogm101.part3.model.Hike</class>
<properties>
<property name="hibernate.ogm.datastore.provider" value="INFINISPAN" />
<property name="hibernate.ogm.datastore.database" value="hike_db" />
<property name="hibernate.ogm.datastore.create_database" value="true" />
</properties>
</persistence-unit>
</persistence>Here we define a persistence unit named “hike-PU”. Infinispan is a fully transactional datastore, and using JTA as transaction type allows the persistence unit to participate in container-managed transactions. Specifying HibernateOgmPersistence as the provider class enables Hibernate OGM (instead of Hibernate ORM), which is configured with some properties for the setting backend (INFINISPAN in this case), database name etc.
Note that it actually should not be required to specify the entity types in persistence.xml when running in a Java EE container such as WildFly. Instead they should be picked up automatically. When using Hibernate OGM this unfortunately is needed at the moment. This a known limitation (see OGM-828) which we hope to fix soon.
The next step is to implement repository classes for accessing hike and organizer data. As an example, the following shows the PersonRepository class:
@ApplicationScoped
public class PersonRepository {
@PersistenceContext
private EntityManager entityManager;
public Person create(Person person) {
entityManager.persist( person );
return person;
}
public Person get(String id) {
return entityManager.find( Person.class, id );
}
public List<Person> getAll() {
return entityManager.createQuery( "FROM Person p", Person.class ).getResultList();
}
public Person save(Person person) {
return entityManager.merge( person );
}
public void remove(Person person) {
entityManager.remove( person );
for ( Hike hike : person.getOrganizedHikes() ) {
hike.setOrganizer( null );
}
}
}The implementation is straight-forward; by means of the @ApplicationScoped annotation, the class is marked as application-scoped CDI bean (i.e. one single instance of this bean exists throughout the lifecycle of the application). It obtains a JPA entity manager through dependency injection and uses the same to implement some simple CRUD methods (Create, Read, Update, Delete).
Note how the getAll() method uses a JP-QL query to return all person objects. Upon execution this query will be transformed into an equivalent Lucene index query which will be run through Hibernate Search.
The hike repository looks very similar, so it’s omitted here for the sake of brevity. You can find its source code on GitHub.
Exposing REST services
JAX-RS makes building REST-ful web services a breeze. It defines a declarative programming model where you annotate plain old Java classes to provide implementations for the GET, POST, PUT etc. operations of an HTTP endpoint.
Describing JAX-RS in depth is beyond the scope of this tutorial, e.g. refer to the Java EE 7 tutorial if you would like to learn more. Let’s just have a look at the some methods of a resource class for managing persons as an example:
@Path("/persons")
@Produces("application/json")
@Consumes("application/json")
@Stateless
public class Persons {
@Inject
private PersonRepository personRepository;
@Inject
private ResourceMapper mapper;
@Inject
private UriMapper uris;
@POST
@Path("/")
public Response createPerson(PersonDocument request) {
Person person = personRepository.create( mapper.toPerson( request ) );
return Response.created( uris.toUri( person ) ).build();
}
@GET
@Path("/{id}")
public Response getPerson(@PathParam("id") String id) {
Person person = personRepository.get( id );
if ( person == null ) {
return Response.status( Status.NOT_FOUND ).build();
}
else {
return Response.ok( mapper.toPersonDocument( person ) ).build();
}
}
@GET
@Path("/")
public Response listPersons() { … }
@PUT
@Path("/{id}")
public Response updatePerson(PersonDocument request, @PathParam("id") String id) { … }
@DELETE
@Path("/{id}")
public Response deletePerson(@PathParam("id") String id) { … }
}The @Path, @Produces and @Consumes annotations are defined by JAX-RS. They bind the resource methods to specific URLs, expecting and creating JSON based messages. @GET, @POST, @PUT and @DELETE configure for which HTTP verb each method is responsible.
The @Stateless annotation defines this POJO as a stateless session bean. Dependencies such as the PersonRepository can be obtained via @Inject-based dependency injection. Implementing a session bean gives you the comfort of transparent transaction management by the container. Invocations of the methods of Persons will automatically be wrapped in a transaction, and all the interactions of Hibernate OGM with the datastore will participate in the same. This means that any changes you do to managed entities - e.g. by persisting a new person via PersonRepository#create() or by modifying a Person object retrieved from the entity manager - will be committed to the datastore after the method call returns.
Mapping models
Note that the methods of our REST service do not return and accept the managed entity types themselves, but rather specific transport structures such as PersonDocument:
public class PersonDocument {
private String firstName;
private String lastName;
private Set<URI> organizedHikes;
// constructors, getters and setters...
}The reasoning for that is to represent the elements of associations (Person#organizedHikes, Hike#organizer) in form of URIs, which enables a client to fetch these linked resources as required. E.g. a GET call to http://myserver/ogm-demo-part3/hike-manager/persons/123 may return a JSON structure like the following:
{
"firstName": "Saundra",
"lastName": "Johnson",
"organizedHikes": [
"http://myserver/ogm-demo-part3/hike-manager/hikes/456",
"http://myserver/ogm-demo-part3/hike-manager/hikes/789"
]
}
The mapping between the internal model (e.g. entity Person) and the external one (e.g. PersonDocument) can quickly become a tedious and boring task, so some tool-based support for this is desirable. Several tools exist for this job, most of which use reflection or runtime byte code generation for propagating state between different models.
Another approach for this is pursued by MapStruct, which is a spare time project of mine and generates bean mapper implementations at compile time (e.g. with Maven or in your IDE) via a Java annotation processor. The code it generates is type-safe, fast (it's using plain method calls, no reflection) and dependency-free. You just need to declare Java interfaces with mapping methods for the source and target types you need and MapStruct will generate an implementation as part of the compilation process:
@Mapper(
// allows to obtain the mapper via @Inject
componentModel = "cdi",
// a hand-written mapper class for converting entities to URIs; invoked by the generated
// toPersonDocument() implementation for mapping the organizedHikes property
uses = UriMapper.class
)
public interface ResourceMapper {
PersonDocument toPersonDocument(Person person);
List<PersonDocument> toPersonDocuments(Iterable<Person> persons);
@Mapping(target = "date", dateFormat = "yyyy-MM-dd'T'HH:mm:ss.SSSZ")
HikeDocument toHikeDocument(Hike hike);
// other mapping methods ...
}The generated implementation can then be used in the Persons REST resource to map from the internal to the external model and vice versa. If you would like to learn more about this approach for model mappings, check out the complete mapper interface on GitHub or the MapStruct reference documentation.
Wrap-up
In this part of our tutorial series you learned how to add Hibernate OGM to the WildFly application server and use it to access Infinispan as the data storage for a small REST application.
WildFly is a great runtime environment for applications using Hibernate OGM, as it provides most of the required building blocks out of the box (e.g. JPA/Hibernate ORM, JTA, transaction management etc.), tightly integrated and ready to use. Our module ZIP allows to put the Hibernate OGM modules into the mix very easily, without the need for re-deploying them each time with your application. With WildFly Swarm there is also support for the micro-services architectural style, but we’ll leave it for another time to show how to use Hibernate OGM with Wildfly Swarm (currently JPA support is still lacking from WildFly Swarm).
You can find the sources of the project on GitHub. To build the project run mvn clean install (which executes an integration test for the REST services using Arquillian, an exciting topic on its own). Alternatively, the Maven WildFly plug-in can be used to fire up a WildFly instance and deploy the application via mvn wildfly:run, which is great for manual testing e.g. by sending HTTP requests through curl or wget.
If you have any questions, let us know in the comments below or send us a Tweet to @Hibernate. Also your wishes for future parts of this tutorial are welcome. Stay tuned!
