- NoSQL with Hibernate OGM - Part one: Persisting your first Entities
- NoSQL with Hibernate OGM - Part two: Querying for your data
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/modulesIn 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>
...
...
<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>
...
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>
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...
}
<?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>
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 );
}
}
}
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 @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...
}
{
"firstName": "Saundra",
"lastName": "Johnson",
"organizedHikes": [
"http://myserver/ogm-demo-part3/hike-manager/hikes/456",
"http://myserver/ogm-demo-part3/hike-manager/hikes/789"
]
}
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 ...
}
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!
