The Keyhole team is proud to announce the release of the khsSherpa framework, a JSON Endpoint Open Source Framework for Mobile and HTML5 Support. This framework is publicly available on gitHub, and version 1.2.2 (as of 3/26/2013) is available in the Maven Public Central Repository.

How khsSherpa Works

The intent of the khsSherpa framework is to invoke service side Java classes, which we refer to as endpoints, and execute methods that are members of this endpoint. Member method execution can accept parameters via an HTTP request and/or return object values serialized as JSON objects. The framework utilizes the Jackson JSON framework to serialize result objects. Here are a list of features the framework provides (these are features that need to be considered when developing native or hybrid container-based mobile applications):

• Spring IOC Container Support (as of 1/7/2013)
• Spring Support (as of 9/7/2012)
• RESTful Service URL Mappings (as of 8/1/2012)
• Annotation-Based Configuration Authentication and Role-Based Permissions
• JSONP Cross Domain Support
• Session Support
• Type Mapping
• XSS Prevention Support
• Pluggable Activity Logging
• Works With Any Java Application Server

Background

Over the last couple of years we’ve had some native mobile development projects that require interaction with server side application logic. The traditional approach of XML based web services seemed too heavy. Even though some mobile devices can have a lot of horse power, we wanted to cut down on parsing overhead. And since this was machine-to-machine processing, and there were no re-purposing requirements, we decided that JSON would be more efficient.

Since we were developing native applications, user interface elements were client resident, however data object values and some business logic was contained in an application server. Also, use cases identified for the mobile application already existed as a browser-based application with user identity and authentication implemented. It made logical sense to leverage the existing server side Java web application infrastructure already in place.

There are many MVC frameworks that would allow access to JSON objects via HTTP, however they are intended for server side view and controller processing, and assume a request/response type mechanism where the UI and controller elements exist on the app server. Additionally, they rely upon web browser session management. So, we created a framework that was lighter-weight, named “khsSherpa,” that enables remote Java classes resident in a JEE WAR component accessed via HTTP.

Framework Details

Server Side Endpoints

Endpoints are defined by applying the framework supplied @Endpoint annotation to POJO’s that will be accessed remotely. Method implementations with parameters are annotated with a @Param annotation that defines a parameter name used for the http parameter requests. An partial example server side endpoint service that returns stock price information for a specified stock ticker is shown below:

@Endpoint
public class StockService {
     public Stock quote(@Param(name = "ticker") String ticker) {
          //logic to return Stock JSON Quote information

A client accesses this endpoint using a get/post url operation specifying an endpoint and action/method name defined in the endpoint class along with any parameters, if any. See the example below:

    http:/sherpa?endpoint=StockService&action=quote&ticker=goog

Clients can use native code to execute in either a get/post request. JSON object result for this endpoint will look like this and can then be consumed by the client.

{
"ticker": "GOOG",
"name": "Google Inc.",
"tradeDate": "4/27/2012",
"price": 614.98,
"dividendYield": 0,
"pe": 18.65
}

URL Request Data Type Mappings

Java @Endpoint methods invoked from a client application are automatically mapped to Java primitive types, using the @Param annotation. This annotation marks method argument values and the request parameter names used in URL’s. Consider the Java endpoint definition below, it defines a class that accepts to double values adds them together and returns a Result JSON object. The framework automatically converts request parameters to double values, errors are logged and reported as a JSON result object with an error code and description.

@Endpoint(authenticated = false)
public class TestService {
 // add two number and return result
 public Result add(@Param(name="x_value") double x, @Param(name="y_value") double y){
		return new Result(x + y);
	}

Besides mapping primitive Java types to endpoint method arguments, JSON objects can be specified from the client and mapped to client side reference objects using the @JsonParam annotation. As with the param annotation, the JSON parameter allows a parameter name with the addition of a type value to be specified. The type value should be a POJO class visible on the server side class path. The framework will map the supplied JSON string to an instance of this type, and mapping errors will be reported. The example below shows how a Stock JSON object from a client request is mapped to the Stock.java class.

Quick Screencast About khsSherpa

The Sherpa open source framework is being hosted on gitHub here.

Example khsSherpa Web Application

An example web application with a sherpa web harness is also available on gitHub here.

// argument is JSON string for Stock object
public void saveStock(@JsonParam(name = "stock",type = Stock.class) Object object) {
     Stock stock = (Stock) stock;
     // save stock object form client;
     .....

Installing in a JEE Application Server

A standard Java application server (i.e. Tomcat) is enabled to serve up JSON endpoints by simply including the framework jar in the class path and registering the framework servlet in the web.xml file as shown below.

  	SherpaServlet
	  SherpaServlet
	  com.khs.sherpa.servlet.SherpaServlet

	SherpaServlet
	/SherpaServlet

The only other required configuration is to identity the project package where the @Endpoint annotation will be applied to service POJO’s. This is done by defining a sherpa.properties file in the class path as shown below.

###
# sherpa.properties
# Sherpa server properties
###

## package where endpoints are located
endpoint.package=com.khs.example.endpoints

The framework will read this property file by default. There are other configuration options applied in this file, but they are beyond the scope of this blog. Do check out the project on gitHub for more detailed information.

Activity Logging

By default the framework logs activity (which is information about endpoints being accessed) to the java.util.logging api — the standard out console by default. An alternative logging implementation can be installed by implementing the supplied ActivityService interface, and registering it in the sherpa.properties file. An example is shown below:

## register user activity to mongodb datasource
activity.service.impl = com.example.activity.MonoDbActivityServiceImpl

Token-based Authentication and Session Management

Since clients will probably be accessing @Endpoint’s from outside a browser using native client code, or Java script, they can be marked as requiring authentication in order to be accessed. The authentication policy employed by the framework is token based. Endpoint methods marked as authenticated require a valid token and user id to be specified for each request. A authenticated token is obtained by invoking the authentication url with a valid user id and password. The resulting token must be supplied to each @Endpoint requiring authentication. Endpoints are marked as authenticated as shown below:

@Endpoint(authenticated = true)
public class TestService {

Authentication tokens are valid for a specified session time period. Inactivity longer than the specified session timeout period requires re-authentication and a new token.

User credentials (user id and password) are authenticated by implementing and registering an authentication service implementation in the sherpa.properties file, as shown below:

## user authentication service class
#authentication.service = com.example.authentication.LDAPAuthenticationServiceImpl

—

We hope you will find this framework useful. Please let our team know if you have an questions on how to go about utilizing it in your projects.

— The Keyhole Team, [email protected]

Important Links:

Open Source khsSherpa Project

Example Web Application

khsSherpa Screencast