Skip to content

REST Based Access

Jump to bottom
Amresh edited this page Jul 14, 2013 · 4 revisions

Introduction

Purpose of Kundera's REST-based access is to enable Kundera powered applications to provide new ways for other clients to interact with it. A common use case is a reporting solution on NoSQL datastore that is not part of core-application but is hosted elsewhere. REST access provides a layer that other client applications can interact to. Those client applications can leverage Kundera's power and simplicity, not to forget business logic that's already been written as part of core application.

Why REST

Kundera's REST based interface (Kundera-REST) is meant for what we'll call as "Client consumer applications". Why we choose REST? Umm...because REST has emerged over the past few years as a predominant Web service design model. REST has increasingly displaced other design models such as SOAP and WSDL due to its simpler style. Simplicity runs in parallel with Kundera, ain't it?

Before we explain further, see image below to understand how it works:

Kundera's Client Consumption Framework

How to use

Configuration

Kundera uses Jersey implementation of JAX-RS for implementing REST resources. You would need to put an entry of JAX-RS Servlet into web.xml file in your web application that uses Kundera.

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xmlns="http://java.sun.com/xml/ns/javaee" xmlns:web="http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
	xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
	id="WebApp_ID" version="2.5">	
	<servlet>		
		<servlet-name>JAX-RS Servlet</servlet-name>		
		<servlet-class>com.sun.jersey.spi.container.servlet.ServletContainer</servlet-class>
		<init-param>
			<param-name>com.sun.jersey.config.property.packages</param-name>
			<param-value>com.impetus.kundera.rest.resources</param-value>
		</init-param>
		<init-param>
			<param-name>com.sun.jersey.config.feature.Redirect</param-name>
			<param-value>true</param-value>
		</init-param>
		<load-on-startup>1</load-on-startup>
	</servlet>
	<servlet-mapping>
		<servlet-name>JAX-RS Servlet</servlet-name>
		<url-pattern>/rest/*</url-pattern>
	</servlet-mapping>
</web-app>

REST Operations supported

Operations supported in Kundera are explained below:

We'll use these acronyms:

<host> : Host URL where Kundera powered web application is hosted.
<port> : Port on which web application listens.
<web-context-url> : Web context URL.
<JAX-RS Servlet URL Path> : URL path of JAX-RS servlet. In the above web.xml file, its value is /rest.

Get Application Token

While starting your REST client application, you would need to get Application token. Your client application would typically store it into session or a variable that is available throughout application uptime.

URL:

http://<host>:<port>/<web-context-url>/<JAX-RS Servlet URL Path>/kundera/api/application/<persistence units>

HTTP Method: GET

Corresponding JPA operation:

Persistence.createEntityManagerFactory(persistenceUnits);

Headers to be set: None

Output: Response status of OK, with Application token as String value.

Get Schema Metadata

URL:

http://<host>:<port>/<web-context-url>/<JAX-RS Servlet URL Path>/kundera/api/metadata/schemaList/<persistence units>

HTTP Method: GET

Corresponding JPA operation:

entityManagerFactory.getMetaModel();

Headers to be set: None

Output: Response status of OK, with schema info as per below format:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<schemaMetadata>
	<schemaList>
		<schemaName>KunderaExamples</schemaName>
		<tables>
                    <table>
			<entityClassName>Book</entityClassName>
			<tableName>BOOK</tableName>
                    </table>
                    <table>
			<entityClassName>Song</entityClassName>
			<tableName>SONG</tableName>
                    </table>
		</tables>
	</schemaList>
</schemaMetadata>

Get Session Token

For performing a (group of) CRUD operation, you would need to get session token. It will exist as long as you don't close session. Your client application would typically store it into a local variable and discard it after closing session.

URL:

http://<host>:<port>/<web-context-url>/<JAX-RS Servlet URL Path>/kundera/api/session

HTTP Method: GET

Corresponding JPA operation:

entityManagerFactory.createEntityManager();

Headers to be set:

Name: x-at
Value: <Application token>

Output: Response status of OK, with Session token as String value.

Begin Transaction

After creating a session, you can group a set of CRUD operations a part of transaction. You begin a transaction using this interface.

URL:

http://<host>:<port>/<web-context-url>/<JAX-RS Servlet URL Path>/kundera/api/tx

HTTP Method: GET

Corresponding JPA operation:

entityManager.getTransaction().begin();

Headers to be set:

Name: x-st
Value: <Session token>

Output: Response status of OK.

Write Entity

This interface is for inserting a record into database once you've got a session token.

URL:

http://<host>:<port>/<web-context-url>/<JAX-RS Servlet URL Path>/kundera/api/<Class Name>

HTTP Method: POST

POST Body: Put your entity object in XML/ JSON format (as the case may be) into POST body.

Example:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<book>
	<isbn>1111111111111</isbn>
	<author>Vijay</author>
	<publication>Willey</publication>
</book>

Corresponding JPA operation:

entityManager.persist(entityObject);

Headers to be set:

Name: x-st
Value: <Session token>

Output: Response status of OK.

Find Entity by primary key

This interface is for retrieving a record from database.

URL:

http://<host>:<port>/<web-context-url>/<JAX-RS Servlet URL Path>/kundera/api/<Class Name>/<primary key>

HTTP Method: GET

Corresponding JPA operation:

entityManager.find(entityClass, primaryKey);

Headers to be set:

Name: x-st
Value: <Session token>

Output: Response status of OK with output entity string XML/ JSON format as the case may be.

Update Entity

This interface is for updating a record into database.

URL:

http://<host>:<port>/<web-context-url>/<JAX-RS Servlet URL Path>/kundera/api/<Class Name>

HTTP Method: PUT

PUT Body: Put your modified entity object in XML/ JSON format (as the case may be) into PUT body.

Example:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<book>
	<isbn>1111111111111</isbn>
	<author>Saurabh</author>
	<publication>McGraw</publication>
</book>

Corresponding JPA operation:

entityManager.merge(entityObject);

Headers to be set:

Name: x-st
Value: <Session token>

Output: Response status of OK.

Delete Entity

This interface is for deleting a record from database.

URL:

http://<host>:<port>/<web-context-url>/<JAX-RS Servlet URL Path>/kundera/api/<Class Name>/<primary key>

HTTP Method: DELETE

Corresponding JPA operation:

entityManager.remove(entityObject);

Headers to be set:

Name: x-st
Value: <Session token>

Output: Response status of OK with output entity string XML/ JSON format as the case may be.

Select all records

This interface is for retrieving all records for a given entity from database.

URL:

http://<host>:<port>/<web-context-url>/<JAX-RS Servlet URL Path>/kundera/api/query/<Class Name>/all

HTTP Method: GET

Corresponding JPA operation:

Query query = entityManager.createQuery("select p from Person p");
return query.getResultList();

Headers to be set:

Name: x-st
Value: <Session token>

Output: Response status of OK with output entities in XML/ JSON format as the case may be. Example:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<books>
   <book>
	<isbn>1111111111111</isbn>
	<author>Saurabh</author>
	<publication>McGraw</publication>
   </book>
   <book>
	<isbn>2222222222222</isbn>
	<author>Amresh</author>
	<publication>Willey</publication>
   </book>
</books>

Run JPA Query

This interface is for running a JPA query and retrieving all matching records from database.

URL:

http://<host>:<port>/<web-context-url>/<JAX-RS Servlet URL Path>/kundera/api/query/jpa/<JPA Query>?param1=value1&param2=value2&....

HTTP Method: GET/ POST/ PUT/ DELETE for Select/ Insert/ Update/ Delete queries respectively.

Corresponding JPA operation:

Query query = entityManager.createQuery(jpaQueryString);
query.setParameter("param1","value1");
query.setParameter("param2","value2");
return query.getResultList();

Headers to be set:

Name: x-st
Value: <Session token>

Output: Response status of OK with output entities in XML/ JSON format as the case may be.

Example:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<books>
   <book>
	<isbn>1111111111111</isbn>
	<author>Saurabh</author>
	<publication>McGraw</publication>
   </book>
</books>

Run Named JPA Query

This interface is for running a Named JPA query and retrieving all matching records from database.

URL:

http://<host>:<port>/<web-context-url>/<JAX-RS Servlet URL Path>/kundera/api/query/jpa/<Entity Class Name>/<Named Query>?param1=value1&param2=value2&....

HTTP Method: GET/ POST/ PUT/ DELETE for Select/ Insert/ Update/ Delete queries respectively.

Corresponding JPA operation:

Query query = entityManager.createNamedQuery(namedQueryString);
query.setParameter("param1","value1");
query.setParameter("param2","value2");
return query.getResultList();

Headers to be set:

Name: x-st
Value: <Session token>

Output: Response status of OK with output entities in XML/ JSON format as the case may be.

Example:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<books>
   <book>
	<isbn>1111111111111</isbn>
	<author>Saurabh</author>
	<publication>McGraw</publication>
   </book>
</books>

Run Native Query

This interface is for running a Native query and retrieving all matching records from database.

URL:

http://<host>:<port>/<web-context-url>/<JAX-RS Servlet URL Path>/kundera/api/query/native/<Entity Class Name>/q=<Native Query>

HTTP Method: GET/ POST/ PUT/ DELETE for Select/ Insert/ Update/ Delete queries respectively.

Corresponding JPA operation:

Query query = entityManager.createNativeQuery(nativeQueryString, entityClass);
return query.getResultList();

Headers to be set:

Name: x-st
Value: <Session token>

Output: Response status of OK with output entities in XML/ JSON format as the case may be.

Example:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<books>
   <book>
	<isbn>1111111111111</isbn>
	<author>Saurabh</author>
	<publication>McGraw</publication>
   </book>
</books>

Run Named Native Query

This interface is for running a Named Native query and retrieving all matching records from database.

URL:

http://<host>:<port>/<web-context-url>/<JAX-RS Servlet URL Path>/kundera/api/query/native/<Entity Class Name>/<Named Native Query>

HTTP Method: GET/ POST/ PUT/ DELETE for Select/ Insert/ Update/ Delete queries respectively.

Corresponding JPA operation:

Query query = entityManager.createNamedQuery(nativeQueryString, entityClass);
return query.getResultList();

Headers to be set:

Name: x-st
Value: <Session token>

Output: Response status of OK with output entities in XML/ JSON format as the case may be.

Example:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<books>
   <book>
	<isbn>1111111111111</isbn>
	<author>Saurabh</author>
	<publication>McGraw</publication>
   </book>
</books>

Commit Transaction

You can commit a transaction using this interface.

URL:

http://<host>:<port>/<web-context-url>/<JAX-RS Servlet URL Path>/kundera/api/tx

HTTP Method: POST

Corresponding JPA operation:

entityManager.getTransaction().commit();

Headers to be set:

Name: x-st
Value: <Session token>

Rollback Transaction

You can rollback a transaction using this interface.

URL:

http://<host>:<port>/<web-context-url>/<JAX-RS Servlet URL Path>/kundera/api/tx

HTTP Method: DELETE

Corresponding JPA operation:

entityManager.getTransaction().rollback();

Headers to be set:

Name: x-st
Value: <Session token>

Flush session

You may choose to flush session as and when you need it.

URL:

http://<host>:<port>/<web-context-url>/<JAX-RS Servlet URL Path>/kundera/api/session

HTTP Method: PUT

Corresponding JPA operation:

entityManager.flush();

Headers to be set:

Name: x-st
Value: <Session token>

Output: Response status of OK.

Clear session

You may choose to clear session as and when you need it.

URL:

http://<host>:<port>/<web-context-url>/<JAX-RS Servlet URL Path>/kundera/api/session/clear

HTTP Method: DELETE

Corresponding JPA operation:

entityManager.clear();

Headers to be set:

Name: x-st
Value: <Session token>

Output: Response status of OK.

Close session

After you are done with a session, you can close it and discard session token variable.

URL:

http://<host>:<port>/<web-context-url>/<JAX-RS Servlet URL Path>/kundera/api/session

HTTP Method: DELETE

Corresponding JPA operation:

entityManager.close();

Headers to be set:

Name: x-st
Value: <Session token>

Output: Response status of OK.

Close Application

Typically while shutting down your REST client application, you would want to get rid of (or close gracifully) your connection to Kundera. This would invalid Application Token.

URL:

http://<host>:<port>/<web-context-url>/<JAX-RS Servlet URL Path>/kundera/api/application

HTTP Method: DELETE

Corresponding JPA operation:

entityManagerFactory.close();

Headers to be set:

Name: x-at
Value: <Application token>

Output: Response status of OK.

Test cases demonstrating these operations can be found here:

https://github.com/impetus-opensource/Kundera/tree/trunk/kundera-rest/src/test/java/com/impetus/kundera/rest/resources

Home

Home

Clone this wiki locally