Setup

Using the JPA database resources is straightforward, simply follow the steps below.

If you have generated a project using an archetype, then depending on the selected archetype these steps might already have been done for you.

Create some JPA entities

In your Kauri module, add some POJO's you want to persist. Annotate them with JPA annotations, only @Entity is required.

Create a persistence.xml

Add a META-INF/persistence.xml file and configure your persistence unit (connection-url, username, pasword)

The default persistence-unit name is "kauri-dbresources". If you use another one, you need to define it using a Spring bean named "persistenceUnitName", see below.

Update the pom.xml

In the pom.xml of your module, add a dependency on the kauri-dbresources-impl artifact:

    <dependency>
      <groupId>org.kauriproject</groupId>
      <artifactId>kauri-dbresources-impl</artifactId>
      <version>${version.kauri}</version>
    </dependency>

Spring bean configuration

In your spring bean configuration (src/main/kauri/spring/...), add the following import:

<import resource="classpath:org/kauriproject/dbresources/jpa/services.xml"/>

If needed override the default persistenceUnitName by adding:

<bean id="persistenceUnitName" class="java.lang.String">
  <constructor-arg value="{your-persistency-unit-name-here}"/>
</bean>

wiring.xml

The import we did in the Spring configuration will automatically export a REST-service called jpaRestlet.

In the wiring.xml, you can mount this REST-service on a path of your choice.

Inside the XML-element defining your module, add:
<mount name="jpaRestlet" path="/data"/>

Try it out

After doing an "mvn install" and (re)starting Kauri, browse to:

http://localhost:8888/data/myentity

where myentity corresponds to the name of an entity as annotated on your Java classes, such as @Entity(name = "myentity")

JPA database resource interface specifics

The JpaRestlet provides the JPA database resources. It implements the common database resource interface.

All resources have three representations:

application/json: a json representation
text/xml or application/xml: an XML representation
text/plain: a textual representation of your entity

Content negotiation (the HTTP Accept header) can be used to indicate your preferred representation.

In case you can't set the Accept header, you can work around this by specifying it in the URI, for example ?media=json

Entities that are serializable, can also be retrieved as serialized Java objects.

For POST/PUT operations, the payload can be JSON, XML or serialized Java objects.

Limitations

Currently database resources are in initial stable phase. We are aware of certain restrictions and imperfections, but before we tackle those issues we'd like to have a better view on where this module is going and what features users want to see in it.

The database resources are vulnerable to SQL injection.

The database resources only work with Hibernate as JPA provider.

JPA DATABASE RESOURCES