Monday 26 November 2012

Groovy's RESTClient with Spock Extensions

Groovy has an extension to its HTTPBuilder class called RESTClient which makes it fairly easy to test a RESTful web service. This post will describe how to use the RESTClient, how to inject it into a Groovy Spock test class via custom annotations, how to swap the injected client between a real one and a mocked one using Mockito, and how to test it.

The RESTClient class provides methods to perform the HTTP's GET, POST, PUT and DELETE methods. The RESTClient instance can be constructed with a url string and optionally a content type. The HTTP methods can then be called with a named parameter list. For example, the below code will create a RESTClient instance and call the get method passing in the path and a path parameter:

def client = new RESTClient("http://localhost:8080/testWebService/")
def resp = client.get(path : "server/status/ServerOne")

The response returned is an instance of HttpResponseDecorator. This wraps the HttpResponse to allow for easy access to the data which is parsed depending upon the content type. The below class shows it's use within a Spock framework test and how the parsed data can be extracted from the response object. The returned XML is:

<serverstatus>
  <servername>ServerOne</servername>
  <isrunning>true</isrunning>
</serverstatus>

then

<serverstatus>
  <servername>ServerTwo</servername>
  <isrunning>false</isrunning>
</serverstatus>


import groovy.util.slurpersupport.GPathResult
import groovyx.net.http.RESTClient
import spock.lang.*
import groovyx.net.http.ContentType

class InjectedRestServiceTest extends Specification {
 
 @RESTWebClient
 def client
   
 def "Test Server Statuses"() {

  when: "retrieve server status"
  def resp1 = client.get(path : "server/status/ServerOne")
  def resp2 = client.get(path : "server/status/ServerTwo")
  
  then: "test server one response"
  assert resp1.data.serverName.text() == "ServerOne"
  assert resp1.data.isRunning.text() == "true"
  
  then: "test server two response"
  assert resp2.data.serverName.text() == "ServerTwo"
  assert resp2.data.isRunning.text() == "false"
  
 }
 
}

The test asserts are purely there in this example to prove that the response from the real web service are the same as from the mocked web service. In reality, you would be testing some other functionality of which calling a RESTful web service is part of the flow. You wouldn't really assert the response from a mocked RESTClient although you may want to verify that it has been called n times.

The InjectedRestServiceTest class has the RESTClient injected using the custom made annotation @RESTWebClient. There are three classes involved which enable this functionality. First the interface, which is marked as only visible at field level, contains an @ExtensionAnnotation specifying the class which basically tells Spock what to do when it encounters the @RESTClient annotation:

import java.lang.annotation.ElementType
import java.lang.annotation.Retention
import java.lang.annotation.RetentionPolicy
import java.lang.annotation.Target
import org.spockframework.runtime.extension.ExtensionAnnotation

@Retention(RetentionPolicy.RUNTIME)
@Target([ ElementType.FIELD ])
@ExtensionAnnotation(RESTWebClientAnnotationDrivenExtension)

public @interface RESTWebClient{}
The RESTWebClientAnnotationDrivenExtension class in this example only needs to override the visitFieldAnnotation method of the AbstractAnnotationDrivenExtension class because of the annotation's target element type:

import org.spockframework.runtime.extension.AbstractAnnotationDrivenExtension
import org.spockframework.runtime.extension.AbstractMethodInterceptor
import org.spockframework.runtime.extension.IMethodInvocation
import org.spockframework.runtime.model.FieldInfo
import org.spockframework.runtime.model.SpecInfo

class RESTWebClientAnnotationDrivenExtension extends 
 AbstractAnnotationDrivenExtension<RESTWebClient> {

 private static final String url = 
  System.getProperties().getProperty("url")
 private static final boolean useMock = 
  Boolean.parseBoolean(System.getProperties().getProperty("useMock"))
 
 @Override
 void visitFieldAnnotation(RESTWebClient annotation, FieldInfo field) {
  def methodInterceptor = new RESTWebClientMethodInterceptor(field, url, useMock)
  methodInterceptor.install(field.parent)
 }
 
}

The above extension tells Spock that when it encounters @RESTClient, it must create an interceptor with the arguments denoting the field to which the RESTClient instance is to be set, the url of the web service and a boolean to specify if the mock is to be used or the real web service should be used. (The meaning of the two values could be combined to just have a url and if set then the real web service must be used.)

The interceptor will create either a mock RESTClient or a real one. It will do this when the client field needs to be set in the InjectedRestServiceTest class. If the real RESTClient is required then an instance using the url will be created and set using the fieldInfo.writeValue method. If a mock is required then a Mockito mock RESTClient is created and the expected behaviour mocked using instances of the class HttpResponseDecorator (although these could be mocks too.) Again, this is set using the fieldInfo.writeValue method. The mocking code should probably be in its own method or even class but for this simple example its within the setupRESTClient method:

import groovy.mock.interceptor.MockFor
import groovyx.net.http.HttpResponseDecorator
import groovyx.net.http.RESTClient
import org.spockframework.runtime.extension.AbstractMethodInterceptor;
import org.spockframework.runtime.extension.IMethodInvocation;
import org.spockframework.runtime.model.FieldInfo;
import org.spockframework.runtime.model.SpecInfo;

import static org.mockito.Mockito.*
import static org.mockito.Matchers.*

class RESTWebClientMethodInterceptor extends AbstractMethodInterceptor {

 private final FieldInfo fieldInfo
 private final String url
 private final boolean useMock

 RESTWebClientMethodInterceptor(FieldInfo fieldInfo, String url, boolean useMock) {
  this.fieldInfo = fieldInfo
  this.url = url
  this.useMock = useMock
 }

 @Override
 void interceptSetupMethod(IMethodInvocation methodInvocation) {
  setupRESTClient(methodInvocation.target)
  methodInvocation.proceed()
 }

 @Override
 void install(SpecInfo specInfo) {
  specInfo.setupMethod.addInterceptor this
 }

 private void setupRESTClient(target) {

  if (useMock) {

   def xmlServerOne =
     """
      <serverStatus>
        <serverName>ServerOne</serverName>
        <isRunning>true</isRunning>
      </serverStatus>
      """

   def xmlServerTwo =
     """
      <serverStatus>
        <serverName>ServerTwo</serverName>
        <isRunning>false</isRunning>
      </serverStatus>
      """

   def httpResponseDecoratorServerOne = new HttpResponseDecorator(
     null, new XmlParser().parseText(xmlServerOne))
   def httpResponseDecoratorServerTwo = new HttpResponseDecorator(
     null, new XmlParser().parseText(xmlServerTwo))
   def mapServerOne = [path:"server/status/ServerOne"]
   def mapServerTwo = [path:"server/status/ServerTwo"]

   RESTClient mockRESTClient = org.mockito.Mockito.mock(RESTClient)
   when(mockRESTClient.get(mapServerOne)).thenReturn(httpResponseDecoratorServerOne);
   when(mockRESTClient.get(mapServerTwo)).thenReturn(httpResponseDecoratorServerTwo);

   fieldInfo.writeValue(target, mockRESTClient)
  }
  else {
   fieldInfo.writeValue(target, new RESTClient(url))
  }
 }
 
}

Whilst there are different ways to mock and test RESTful web services, the above classes do show how easily RESTful web services can be called and their responses parsed, how annotations can be created and how objects can be mocked. Similar examples could be constructed for different aspects of a Spock test eg features, fixtures etc..

More can be found on extensions at http://code.google.com/p/spock/wiki/SpockBasics#Extensions and on RESTClient at http://groovy.codehaus.org/modules/http-builder/doc/rest.html

Friday 14 September 2012

Using Spock to test Spring classes

As the previous post mentioned, Spock is a powerful DSL built on Groovy ideal for TDD and BDD testing and this post will describe how easy it is to use Spock to test Spring classes, in this case the CustomerService class from the post Using Spring Data to access MongoDB. It will also cover using Spock for mocking.

Spock relies heavily on the Spring's TestContext framework and does this via the @ContextConfiguration annotation. This allows the test specification class to load an application context from one or more locations.

This will then allow the test specification to access beans either via the annotation @Autowired or @Resource. The test below shows how an injected CusotmerService instance can be tested using Spock and the Spring TestContext: (This is a slightly contrived example as to properly unit test the CustomerService class as you would create a CustomerService class in the test as opposed to one created and injected by Spring.)

package com.city81.mongodb.springdata.dao

import org.springframework.beans.factory.annotation.Autowired
import org.springframework.test.context.ContextConfiguration

import spock.lang.*

import com.city81.mongodb.springdata.entity.Account
import com.city81.mongodb.springdata.entity.Address
import com.city81.mongodb.springdata.entity.Customer

@ContextConfiguration(locations = "classpath:spring/applicationContext.xml")
class CustomerServiceTest extends Specification {

 @Autowired
 CustomerService customerService
 
 
 def setup() {
  customerService.dropCustomerCollection()
 } 
 
 def "insert customer"() {
  
  setup:
  
  // setup test class args
  Address address = new Address()
  address.setNumber("81")
  address.setStreet("Mongo Street")
  address.setTown("City")
  address.setPostcode("CT81 1DB")
 
  Account account = new Account()
  account.setAccountName("Personal Account")
  List<Account> accounts = new ArrayList<Account>()
  accounts.add(account)
  
  Customer customer = new Customer()
  customer.setAddress(address)
  customer.setName("Mr Bank Customer")
  customer.setAccounts(accounts)

  when:
  customerService.insertCustomer(customer)
  
  then:
  def customers = customerService.findAllCustomers()
  customers.size == 1
  customers.get(0).name == "Mr Bank Customer"
  customers.get(0).address.street == "Mongo Street"
  
 } 
}

The problem though with the above test is that MongoDB needs to be up and running so to remove this dependency we can Mock out the interaction the database. Spock's mocking framework provides many of the features you'd find in similar frameworks like Mockito.

The enhanced CustomerServiceTest mocks the CustomerRepository and sets the mocked object on the CustomerService.

package com.city81.mongodb.springdata.dao

import org.springframework.beans.factory.annotation.Autowired
import org.springframework.test.context.ContextConfiguration

import spock.lang.*

import com.city81.mongodb.springdata.entity.Account
import com.city81.mongodb.springdata.entity.Address
import com.city81.mongodb.springdata.entity.Customer

@ContextConfiguration(locations = "classpath:spring/applicationContext.xml")
class CustomerServiceTest extends Specification {

 @Autowired
 CustomerService customerService
 
 CustomerRepository customerRepository = Mock()
 
 def setup() {
  customerService.customerRepository = customerRepository
  customerService.dropCustomerCollection()
 } 
 
 def "insert customer"() {
  
  setup:
    
  // setup test class args
  Address address = new Address()
  address.setNumber("81")
  address.setStreet("Mongo Street")
  address.setTown("City")
  address.setPostcode("CT81 1DB")
 
  Account account = new Account()
  account.setAccountName("Personal Account")
  List<Account> accounts = new ArrayList<Account>()
  accounts.add(account)
  
  Customer customer = new Customer()
  customer.setAddress(address)
  customer.setName("Mr Bank Customer")
  customer.setAccounts(accounts)
  
  when:
  customerService.insertCustomer(customer)
  
  then:
  1 * customerRepository.save(customer)
  
 } 
 
 def "find all customers"() {
 
  setup:
  
  // setup test class args
  Address address = new Address()
  address.setStreet("Mongo Street")
  
  Customer customer = new Customer()
  customer.setAddress(address)
  customer.setName("Mr Bank Customer")
  
  // setup mocking  
  def mockCustomers = []
  mockCustomers << customer
  customerRepository.findAll() >> mockCustomers
  
  when:
  def customers = customerService.findAllCustomers()
  
  then:
  customers.size() == 1  
  customers.get(0).name == "Mr Bank Customer"
  
 }
 
}


The CustomerRepository is by way of name and type although it could be inferred by just the name eg

def customerRepository = Mock(CustomerRepository)

The injected customerRepository is overwritten by the mocked instance and then in the test setup, functionality can be mocked.

In the then block of the insert customer feature, the number of interactions with the save method of customerRepository is tested and in the find all customers feature, the return list of customers from the findAll call is a mocked List,as opposed to one retrieved from the database.

More detail on Spock's mocking capabilities can be found on the project's home page.


Tuesday 11 September 2012

Testing Java using the Spock Framework

The testing framework Spock is a powerful DSL built on Groovy which enables easily writable and extremely readable tests which lends itself well to software development processes like TDD and BDD.

As an example of how much clarity Spock and Groovy bring to testing I'll compare it with the tests for the ForkJoinPool example class InterpolationService.

Every Spock test (or specification) extends spock.lang.Specification. This abstract class uses Spock's JUnit runner, org.spockframework.runtime.Sputnik, and contains useful methods for writing tests eg creating mock objects

There are four main aspects to a specification: Fields, Fixtures, Features and Helpers. There is no point going into depth on each as there are well documented on the Spock Basics wiki but we'll certainly concentrate on Features with respect to the comparison with the JUnit InterpolationService tests.

Features are instance methods which must contain at least one block where a block is one of six methods: setup, when, then, expect, cleanup and where. The blocks setup and cleanup are as you might expect but others are described in more detail below.

First though and the first few lines of the InterpolationServiceTest are shown below:

package com.city81.interpolation.service

import spock.lang.*

class InterpolateServiceTest extends Specification {

    @Shared def interpolateService = new InterpolateService()

The class under test ie InterpolationService is marked as being @Shared (ie all features use the same instance).  This annotation is ideal for expensive resources like a DB connection.

Next the first feature which tests the interpolation of two numbers with an even number of steps:

def "interpolate two numbers with even no. of steps"() {
            
            expect:
            interpolateService.interpolate(a, b, c) == d
            
            where:
            a   | b    | c | d
            5.0 | 25.0 | 4 | [5.0, 10.0, 15.0, 20.0, 25.0] 
            }


The equivalent JUnit assert test method would be:

@Test
 public void testInterpolateTwoValues() {
     List<Double> interpolatedList = 
         interpolateService.interpolate(5.0, 25.0, 4);

    assertEquals(5, interpolatedList.size());
    assertEquals(5.0, interpolatedList.get(0), 0);
    assertEquals(10.0, interpolatedList.get(1), 0);
    assertEquals(15.0, interpolatedList.get(2), 0);
    assertEquals(20.0, interpolatedList.get(3), 0);
    assertEquals(25.0, interpolatedList.get(4), 0);
}


The clarity in what you are testing is easy to see and it is so easy with Spock just to add another where line to test another scenario:

def "interpolate two numbers with even no. of steps"() {

            expect:
            interpolateService.interpolate(a, b, c) == d

            where:
            a   | b    | c | d
            5.0 | 25.0 | 4 | [5.0, 10.0, 15.0, 20.0, 25.0] 
            2.0 | 14.0 | 6 | [2.0, 4.0, 6.0, 8.0, 10.0, 12.0, 14.0] 
            }

It is also worth noting at this point that Groovy uses BigDecimal for floating number numbers but if you want to denote doubles then numbers can be appended with a d eg 5.0d, -15.0d

Whilst the above demonstrates the expect and where blocks, the below shows how to test for exceptions using when and then blocks:

def "interpolate two numbers where first arg is null"() {
       
            when:
            interpolateService.interpolate(null, 25.0, 4)

            then:
            thrown(IllegalArgumentException)
            }

An alternative approach to using thrown(IllegalArgumentException) could be to bind a variable to access the exception:

then:
            IllegalArgumentException e = thrown()
            e.cause == InterpolateService.VALUE_ARG_NOT_NULL_EXCP_TEXT

You can also use the when and then blocks to order interactions although not if the first when throws an exception.

There is much more on Spock on it's Google code pages and the above only describes a few basics but the next post will look at Mocking and also examine it's use with Spring by testing code from a previous post. Might even get the Groovy code formatting working by then too!

Friday 13 July 2012

Using Spring Data to access MongoDB

Spring Data is the data access Spring project for integrating with data stores. This post will cover the Spring Data sub project for accessing the document store MongoDB. It follows on from the Morphia post by showing how Spring Data for MongoDB would persist and query the same POJOs.

The four domain objects are shown below:

package com.city81.mongodb.springdata.entity;

import org.springframework.data.annotation.Id;

public abstract class BaseEntity {

 @Id
 protected String id;
 private Long version;

 public BaseEntity() {
  super();
 }

 public String getId() {
  return id;
 }

 public void setId(String id) {
  this.id = id;
 }

 public Long getVersion() {
  return version;
 }

 public void setVersion(Long version) {
  this.version = version;
 }

}


package com.city81.mongodb.springdata.entity;

import java.util.List;

import org.springframework.data.mongodb.core.mapping.Document;

@Document
public class Customer extends BaseEntity {

 private String name;
 private List<Account> accounts;
 private Address address;
 
 public String getName() {
  return name;
 }

 public void setName(String name) {
  this.name = name;
 } 
  
 public List<Account> getAccounts() {
  return accounts;
 }

 public void setAccounts(List<Account> accounts) {
  this.accounts = accounts;
 }

 public Address getAddress() {
  return address;
 }

 public void setAddress(Address address) {
  this.address = address;
 }
 
}

package com.city81.mongodb.springdata.entity;


public class Address {

 private String number;
 private String street;
 private String town;
 private String postcode;
 
 public String getNumber() {
  return number;
 }
 public void setNumber(String number) {
  this.number = number;
 }
 public String getStreet() {
  return street;
 }
 public void setStreet(String street) {
  this.street = street;
 }
 public String getTown() {
  return town;
 }
 public void setTown(String town) {
  this.town = town;
 }
 public String getPostcode() {
  return postcode;
 }
 public void setPostcode(String postcode) {
  this.postcode = postcode;
 }
}

package com.city81.mongodb.springdata.entity;

import org.springframework.data.mongodb.core.mapping.Document;

@Document
public class Account extends BaseEntity {

 private String accountName;
 
 public String getAccountName() {
  return accountName;
 }

 public void setAccountName(String accountName) {
  this.accountName = accountName;
 }

}

Some classes are marked with the @Document annotation. This is optional but does allow you to provide a collection name eg

@Document(collection="personalBanking")


Also in the Customer class, the Address and Accounts attributes would be stored as embedded within the document but they can be stored separately by marking the variables with @DBRef. These objects will then be eagerly loaded when the Customer record is retrieved.

Next, using XML based metadata to register a MongoDB instance and a MongoTemplate instance.

The MongoFactoryBean is used to register an instance of com.mongodb.Mongo. Using the Bean as opposed to creating an instance of Mongo itself ensures that the calling code doesn't have to handle the checked exception UnknownHostException. It also ensures database specific exceptions are translated to be Spring exceptions of the DataAccessException hierarchy.

The MongoTemplate provides the operations (via the MongoOperations interface) to interact with MongoDB documents. This thread safe class has several constructors but for this example we only need to call the one that takes an instance of Mongo and the database name.

Whilst you could call the operations on the MongoTemplate to manage the entities, there exists a MongoRepository interface which can be extended to be 'document' specific via the use of Generics. The <mongo:repositories base-package="com.city81.mongodb.springdata.dao" />   registers beans extending this interface.



<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
 xmlns:context="http://www.springframework.org/schema/context"
 xmlns:mongo="http://www.springframework.org/schema/data/mongo" 
 xsi:schemaLocation="http://www.springframework.org/schema/beans        
  http://www.springframework.org/schema/beans/spring-beans-3.0.xsd         
  http://www.springframework.org/schema/context         
  http://www.springframework.org/schema/context/spring-context-3.0.xsd
  http://www.springframework.org/schema/data/mongo 
  http://www.springframework.org/schema/data/mongo/spring-mongo.xsd">    
  
 <context:annotation-config />
  
 <context:component-scan base-package="com.city81.mongodb.springdata" />
 
 <!-- MongoFactoryBean instance --> 
 <bean id="mongo" class="org.springframework.data.mongodb.core.MongoFactoryBean">
  <property name="host" value="localhost" />
 </bean>   
 
 <!-- MongoTemplate instance --> 
 <bean id="mongoTemplate" class="org.springframework.data.mongodb.core.MongoTemplate">
  <constructor-arg name="mongo" ref="mongo" />
  <constructor-arg name="databaseName" value="bank" />
 </bean> 
 
 <mongo:repositories base-package="com.city81.mongodb.springdata.dao" />
  
</beans>

The repository class in this example is the CustomerRepository. It gets wired with the MongoTemplate so provides the same (this time implicit type safe) operations but also provides the ability to add other methods. In this example, a find method has been added to demonstrate how a query can be built from the method name itself. There is no need to implement this method as Spring Data will parse the method name and determine the criteria ie findByNameAndAddressNumberAndAccountsAccountName will return documents where the customer name is equal to the first arg (name), and where the customer address number is equal to the second arg (number) and where the customer has an account which has an account name equal to the thrid arg (accountName).


package com.city81.mongodb.springdata.dao;

import java.util.List;

import org.springframework.data.mongodb.repository.MongoRepository;
import org.springframework.stereotype.Repository;

import com.city81.mongodb.springdata.entity.Customer;

@Repository
public interface CustomerRepository extends MongoRepository<Customer,String> {
 
 List<Customer> findByNameAndAddressNumberAndAccountsAccountName(
   String name, String number, String accountName);
 
}


In this example, we'll add a service layer in the form of the CustomerService class, which for this simple example just wraps the repository calls. The class has the CustomerRepository wired in and this service class is then in turn called from the Example class, which performs similar logic to the Morphia Example class.

package com.city81.mongodb.springdata.dao;

import java.util.List;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

import com.city81.mongodb.springdata.entity.Customer;

@Service
public class CustomerService {  

 @Autowired
 CustomerRepository customerRepository;
  
 public void insertCustomer(Customer customer) {    
  customerRepository.save(customer);
 }
 
 public List<Customer> findAllCustomers() {           
  return customerRepository.findAll();
 }       
 
 public void dropCustomerCollection() {        
  customerRepository.deleteAll();   
 } 
 
 public List<Customer> findSpecificCustomers(
   String name, String number, String accountName) {           
  return customerRepository.findByNameAndAddressNumberAndAccountsAccountName(
    name, number, accountName);
 } 
 
}

package com.city81.mongodb.springdata;

import java.util.ArrayList;
import java.util.List;

import org.springframework.context.ConfigurableApplicationContext;
import org.springframework.context.support.ClassPathXmlApplicationContext;

import com.city81.mongodb.springdata.dao.CustomerService;
import com.city81.mongodb.springdata.entity.Account;
import com.city81.mongodb.springdata.entity.Address;
import com.city81.mongodb.springdata.entity.Customer;

public class Example {
 
 public static void main( String[] args ) {     
  
  ConfigurableApplicationContext context
   = new ClassPathXmlApplicationContext("spring/applicationContext.xml");       
  
  CustomerService customerService = context.getBean(CustomerService.class);       
  
  // delete all Customer records
  customerService.dropCustomerCollection();  
  
     Address address = new Address();
     address.setNumber("81");
     address.setStreet("Mongo Street");
     address.setTown("City");
     address.setPostcode("CT81 1DB");
    
     Account account = new Account();
     account.setAccountName("Personal Account");
     List<Account> accounts = new ArrayList<Account>();
     accounts.add(account);
     
     Customer customer = new Customer();
     customer.setAddress(address);
     customer.setName("Mr Bank Customer");
     customer.setAccounts(accounts);
          
     // insert a Customer record into the database
  customerService.insertCustomer(customer);          
     
     address = new Address();
     address.setNumber("101");
     address.setStreet("Mongo Road");
     address.setTown("Town");
     address.setPostcode("TT10 5DB");
    
     account = new Account();
     account.setAccountName("Business Account");
     accounts = new ArrayList<Account>();
     accounts.add(account);
     
     customer = new Customer();
     customer.setAddress(address);
     customer.setName("Mr Customer");
     customer.setAccounts(accounts);  

     // insert a Customer record into the database
  customerService.insertCustomer(customer);     
      
  // find all Customer records
  System.out.println("\nALL CUSTOMERS:");
  List<Customer> allCustomers = customerService.findAllCustomers();     
  for (Customer foundCustomer : allCustomers) {
   System.out.println(foundCustomer.getId() + " " + foundCustomer.getName());   
   System.out.println(foundCustomer.getAddress().getTown());   
   System.out.println(foundCustomer.getAccounts().get(0).getAccountName() + "\n");   
  }
  
  // find by customer name, address number and account name
  System.out.println("\nSPECIFIC CUSTOMERS:");  
  List<Customer> specficCustomers = customerService.findSpecificCustomers(
    "Mr Customer","101","Business Account");     
  for (Customer foundCustomer : specficCustomers) {
   System.out.println(foundCustomer.getId() + " " + foundCustomer.getName());   
   System.out.println(foundCustomer.getAddress().getTown());   
   System.out.println(foundCustomer.getAccounts().get(0).getAccountName() + "\n");   
  }
  
 } 
 
}
The output from the above would look similiar to the below:

04-Oct-2012 13:48:48 org.springframework.context.support.AbstractApplicationContext prepareRefresh
INFO: Refreshing org.springframework.context.support.ClassPathXmlApplicationContext@15eb0a9: startup date [Thu Oct 04 13:48:48 BST 2012]; root of context hierarchy
04-Oct-2012 13:48:48 org.springframework.beans.factory.xml.XmlBeanDefinitionReader loadBeanDefinitions
INFO: Loading XML bean definitions from class path resource [spring/applicationContext.xml]
04-Oct-2012 13:48:48 org.springframework.beans.factory.support.DefaultListableBeanFactory preInstantiateSingletons
INFO: Pre-instantiating singletons in org.springframework.beans.factory.support.DefaultListableBeanFactory@1c92535: defining beans [org.springframework.context.annotation.internalConfigurationAnnotationProcessor,org.springframework.context.annotation.internalAutowiredAnnotationProcessor,org.springframework.context.annotation.internalRequiredAnnotationProcessor,org.springframework.context.annotation.internalCommonAnnotationProcessor,customerService,mongo,mongoTemplate,customerRepository,org.springframework.data.repository.core.support.RepositoryInterfaceAwareBeanPostProcessor#0]; root of factory hierarchy

ALL CUSTOMERS:
506d85b115503d4c92392c79 Mr Bank Customer
City
Personal Account

506d85b115503d4c92392c7a Mr Customer
Town
Business Account


SPECIFIC CUSTOMERS:
506d85b115503d4c92392c7a Mr Customer
Town
Business Account


This is a brief overview of Spring Data from MongoDB but there are many other facets to this project including MappingConverters, Compound Indexes and MVC support. For more info http://static.springsource.org/spring-data/data-mongodb/docs/current/reference/html/

Wednesday 11 July 2012

Using Morphia to map Java objects in MongoDB

MongoDB is an open source document-oriented NoSQL database system which stores data as JSON-like documents with dynamic schemas.  As it doesn't store data in tables as is done in the usual relational database setup, it doesn't map well to the JPA way of storing data. Morphia is an open source lightweight type-safe library designed to bridge the gap between the MongoDB Java driver and domain objects. It can be an alternative to SpringData if you're not using the Spring Framework to interact with MongoDB.

This post will cover the basics of persisting and querying entities along the lines of JPA by using Morphia and a MongoDB database instance.

There are four POJOs this example will be using. First we have BaseEntity which is an abstract class containing the Id and Version fields:

package com.city81.mongodb.morphia.entity;

import org.bson.types.ObjectId;
import com.google.code.morphia.annotations.Id;
import com.google.code.morphia.annotations.Property;
import com.google.code.morphia.annotations.Version;

public abstract class BaseEntity {

    @Id
    @Property("id")
    protected ObjectId id;

    @Version 
    @Property("version")
    private Long version;

    public BaseEntity() {
        super();
    }

    public ObjectId getId() {
        return id;
    }

    public void setId(ObjectId id) {
        this.id = id;
    }

    public Long getVersion() {
        return version;
    }

    public void setVersion(Long version) {
        this.version = version;
    }

}


Whereas JPA would use @Column to rename the attribute, Morphia uses @Property. Another difference is that @Property needs to be on the variable whereas @Column can be on the variable or the get method.

The main entity we want to persist is the Customer class:

package com.city81.mongodb.morphia.entity;

import java.util.List;
import com.google.code.morphia.annotations.Embedded;
import com.google.code.morphia.annotations.Entity;

@Entity
public class Customer extends BaseEntity {

    private String name;
    private List<Account> accounts;
    @Embedded
    private Address address;

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public List<Account> getAccounts() {
        return accounts;
    }

    public void setAccounts(List<Account> accounts) {
        this.accounts = accounts;
    }

    public Address getAddress() {
        return address;
    }

    public void setAddress(Address address) {
        this.address = address;
    }

}


As with JPA, the POJO is annotated with @Entity. The class also shows an example of @Embedded:

The Address class is also annotated with @Embedded as shown below:

package com.city81.mongodb.morphia.entity;

import com.google.code.morphia.annotations.Embedded;

@Embedded
public class Address {

    private String number;
    private String street;
    private String town;
    private String postcode;

    public String getNumber() {
        return number;
    }

    public void setNumber(String number) {
        this.number = number;
    }

    public String getStreet() {
        return street;
    }

    public void setStreet(String street) {
        this.street = street;
    }

    public String getTown() {
        return town;
    }

    public void setTown(String town) {
        this.town = town;
    }

    public String getPostcode() {
        return postcode;
    }

    public void setPostcode(String postcode) {
        this.postcode = postcode;
    }

}

Finally, we have the Account class of which the customer class has a collection of:

package com.city81.mongodb.morphia.entity;

import com.google.code.morphia.annotations.Entity;

@Entity
public class Account extends BaseEntity {

    private String name;

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

}

The above show only a small subset of what annotations can be applied to domain classes. More can be found at http://code.google.com/p/morphia/wiki/AllAnnotations

The Example class shown below goes through the steps involved in connecting to the MongoDB instance, populating the entities, persisting them and then retrieving them:

package com.city81.mongodb.morphia;

import java.net.UnknownHostException;
import java.util.ArrayList;
import java.util.List;
import com.city81.mongodb.morphia.entity.Account;
import com.city81.mongodb.morphia.entity.Address;
import com.city81.mongodb.morphia.entity.Customer;
import com.google.code.morphia.Datastore;
import com.google.code.morphia.Key;
import com.google.code.morphia.Morphia;
import com.mongodb.Mongo;
import com.mongodb.MongoException;

/**
 * A MongoDB and Morphia Example
 *
 */
public class Example {

    public static void main( String[] args ) throws UnknownHostException, MongoException {

     String dbName = new String("bank");
     Mongo mongo = new Mongo();
     Morphia morphia = new Morphia();
     Datastore datastore = morphia.createDatastore(mongo, dbName);       

     morphia.mapPackage("com.city81.mongodb.morphia.entity");
        
     Address address = new Address();
     address.setNumber("81");
     address.setStreet("Mongo Street");
     address.setTown("City");
     address.setPostcode("CT81 1DB");  

     Account account = new Account();
     account.setName("Personal Account");

     List<Account> accounts = new ArrayList<Account>();
     accounts.add(account);  

     Customer customer = new Customer();
     customer.setAddress(address);
     customer.setName("Mr Bank Customer");
     customer.setAccounts(accounts);
    
     Key<Customer> savedCustomer = datastore.save(customer);    
     System.out.println(savedCustomer.getId());

}


Executing the first few lines will result in the creation of a Datastore. This interface will provide the ability to get, delete and save objects in the 'bank' MongoDB instance.

The mapPackage method call on the morphia object determines what objects are mapped by that instance of Morphia. In this case all those in the package supplied. Other alternatives exist to map classes, including the method map which takes a single class (this method can be chained as the returning object is the morphia object), or passing a Set of classes to the Morphia constructor.

After creating instances of the entities, they can be saved by calling save on the datastore instance and can be found using the primary key via the get method. The output from the Example class would look something like the below:

11-Jul-2012 13:20:06 com.google.code.morphia.logging.MorphiaLoggerFactory chooseLoggerFactory
INFO: LoggerImplFactory set to com.google.code.morphia.logging.jdk.JDKLoggerFactory
4ffd6f7662109325c6eea24f
Mr Bank Customer

There are many other methods on the Datastore interface and they can be found along with the other Javadocs at http://morphia.googlecode.com/svn/site/morphia/apidocs/index.html

An alternative to using the Datastore directly is to use the built in DAO support. This can be done by extending the BasicDAO class as shown below for the Customer entity:

package com.city81.mongodb.morphia.dao;

import com.city81.mongodb.morphia.entity.Customer;
import com.google.code.morphia.Morphia;
import com.google.code.morphia.dao.BasicDAO;
import com.mongodb.Mongo;

public class CustomerDAO extends BasicDAO<Customer, String> {    

    public CustomerDAO(Morphia morphia, Mongo mongo, String dbName) {        
        super(mongo, morphia, dbName);    
    }

}

To then make use of this, the Example class can be changed (and enhanced to show a query and a delete):

...

     CustomerDAO customerDAO = new CustomerDAO(morphia, mongo, dbName);
     customerDAO.save(customer);

     Query<Customer> query = datastore.createQuery(Customer.class);
     query.and(        
       query.criteria("accounts.name").equal("Personal Account"),      
       query.criteria("address.number").equal("81"),        
       query.criteria("name").contains("Bank")
     );       

     QueryResults<Customer> retrievedCustomers =  customerDAO.find(query);   

     for (Customer retrievedCustomer : retrievedCustomers) {
         System.out.println(retrievedCustomer.getName());    
         System.out.println(retrievedCustomer.getAddress().getPostcode());    
         System.out.println(retrievedCustomer.getAccounts().get(0).getName());
         customerDAO.delete(retrievedCustomer);
     }  
    
...


With the output from running the above shown below:

11-Jul-2012 13:30:46 com.google.code.morphia.logging.MorphiaLoggerFactory chooseLoggerFactory
INFO: LoggerImplFactory set to com.google.code.morphia.logging.jdk.JDKLoggerFactory
Mr Bank Customer
CT81 1DB
Personal Account

This post only covers a few brief basics of Morphia but shows how it can help bridge the gap between JPA and NoSQL.

Thursday 3 May 2012

Using Spring @Profile with @EnableAspectJAutoProxy

A new feature introduced in Spring 3.1 is the ability to mark components as being ready for registration if one or more 'profiles' (logical groupings) have been activated. The activation of the profiles is done at runtime either through a system property (-Dspring.profiles.active=xxx) or programmatically by calling the setActiveProfiles method on the ConfigurableEnvironment interface.

A common example of using profiles is to have different datasource beans for different environments eg a local jdbc datasource for a profile of dev but a jndi datasource for a profile of prod. This post though will describe a simple example of using @Profile to switch between different aspects when in different profiles.

Also as this example will use annotations and no XML, it will briefly cover the ability to enable AspectJ auto proxying using the new annotation @EnableAspectJAutoProxy.

The below CustomerApplication class has one simple task and that is to process a Customer object. In order to do that, the CustomerService bean needs to be obtained from the context and the context in this example is an AnnotationConfigApplicationContext.

This type of context will register annotated classes with the package prefix of com.city81. Classes marked with @Profile but not dev will be ignored. (More than one profile can be specified as setActiveProfiles takes an array of Strings.)


public class CustomerApplication {

    public static void main(String[] args) {
  
        AnnotationConfigApplicationContext ctx = new AnnotationConfigApplicationContext();  
        ctx.getEnvironment().setActiveProfiles("dev");  
        ctx.scan("com.city81");
        ctx.refresh(); 

        Customer address = new Customer();
        address.setId("idOne");
        address.setName("custOne");
        address.setAge(21);
        address.setAddress("addressOne");
  
        CustomerService customerService = ctx.getBean(CustomerService.class);
        customerService.processCustomer(address);    
    }
 
}

As we're using Spring configuration programmatically, the getBean method on the context is able find the CustomerService bean as we have a CustomerServiceConfig class which is annotated with @Configuration. This allows the container to generate bean definitions at runtime.

@Configuration
@EnableAspectJAutoProxy
public class CustomerServiceConfig {

    @Bean
    public CustomerService customerService() {
        return new CustomerServiceImpl();
    }

}

This is the class that also includes @EnableAspectJAutoProxy. Prior to Spring 3.1, auto proxying AspectJ could be done using  <aop:aspectj-autoproxy>  but now @Configuration classes can include the @EnableAspectJAutoProxy annotation thereby enabling support for classes annotated with @Aspect.

In this example, there are two classes marked with @Aspect. Both extend an abstract class which defines the pointcut.

public abstract class LoggingAspect {

    @Pointcut("execution(* com.city81.service.CustomerService.processCustomer(..))")
    public void processCustomer() {
    }

}


@Configuration 
@Profile("prod")  
@Aspect
public class ConciseLoggingAspect extends LoggingAspect {

    @Before("processCustomer()")
    public void logCustomerId(JoinPoint jp) {
        Customer customer = (Customer) jp.getArgs()[0];
        System.out.println("id = " + customer.getId());
    }

}


@Configuration 
@Profile("dev")  
@Aspect
public class VerboseLoggingAspect extends LoggingAspect {

    @Before("processCustomer()")
    public void logCustomerAll(JoinPoint jp) {
        Customer customer = (Customer) jp.getArgs()[0];
        System.out.println("id = " + customer.getId());
        System.out.println("name = " + customer.getName());
        System.out.println("age = " + customer.getAge());
        System.out.println("address = " + customer.getAddress());
    }

}

In this example, there are two profiles, dev and prod, and depending on the profile activated there will be a different level of (contrived) 'logging'.

Each concrete LoggingAspect class contains an @Profile annotation. This can specify one or more profiles. Therefore in the case of using  ctx.getEnvironment().setActiveProfiles("dev") only VerboseLoggingAspect will be registered.

This post shows how easy it is to create profiles and activate them programmatically although it can be done just as easily using XML config.


Wednesday 25 April 2012

Hibernate and Multiple Bags

Certain associations an Entity can have can be deemed 'bags' by Hibernate. A bag is an unordered collection that permits duplicate elements and when persisting these collections, the order of elements cannot be guaranteed. For these reasons, bags are an efficient way of representing a collection as you can add to a bag collection without the collection having been loaded. An example of a bag would be an ArrayList.

When designing the mapping between the objects and the database ie building entities, thought must be given to the type of associations between the entities and the fetching strategy for each association.

A common problem encountered when modelling entities using Hibernate is that of multiple bags. ie when an Entity contains two or more associations which are bags that have a fetch strategy of EAGER. This could be an Entity which has two member collections like the Company class below,  or an Entity that contains collections within its object graph, for example, the Company class may contain a collection of Buildings which in turn has a collection of MeetingRooms.

(Note: BaseEntity contains Id and Version fields.)


@Entity
public class Company extends BaseEntity {

    private List<Department> departments;
    private List<String> shareholders;

    @OneToMany(fetch=FetchType.EAGER)
    @Cascade(value ={CascadeType.SAVE_UPDATE, CascadeType.DELETE_ORPHAN})
    @JoinColumn(name="CO_ID") 
    public List<Department> getDepartments() {  
        return this.departments; 
    }

    public void setDepartments(List<Department> departments) {      
        this.departments = departments; 
    }  

    @CollectionOfElements(fetch=FetchType.EAGER,targetElement=java.lang.String.class) 
    @JoinTable(name="CO_SHR",joinColumns=@JoinColumn(name="CO_ID")) 
    @Column(name="CO_SHR") 
    public List<String> getShareholders() {  
        return this.shareholders; 
    }

    public void setShareholders(List<String> shareholders) {  
        this.shareholders = shareholders; 
    }

}


The Hibernate exception when identifying more than one bag to fetch is shown below:

Caused by: org.hibernate.HibernateException: cannot simultaneously fetch multiple bags
 at org.hibernate.loader.BasicLoader.postInstantiate(BasicLoader.java:66)
 at org.hibernate.loader.entity.EntityLoader.<init>(EntityLoader.java:75)

There are a few ways to resolve this problem once the offending association(s) have been identified. One option is to make all or all but one collection have a fetch strategy of LAZY. This is the default strategy for Hibernate. This would mean that LAZY associations would not be loaded until requested but if requested outside of a session, this would raise a LazyInitializationException. One way to get around this is to load the collection when in a session. For example, if the Company -> Departments association is changed to be @OneToMany, the collection can be loaded as described below using Hibernate.initialize:


    public Company findById(String id) {
        HibernateTemplate ht = getHibernateTemplate();
        Company company = (Company) ht.get(Company.class, id);
        Hibernate.initialize(company.getDepartments());
        return company;
    }


Another option is to revise the type of collection being used. Does it have to be java.util.List? An alternative could be to use java.util.Set which isn't treated by Hibernate as a bag. An example of this would be to change the Company -> Shareholders association to be a SortedSet as shown below:


    private SortedSet<String> shareholders;

    @CollectionOfElements(fetch=FetchType.EAGER,targetElement=java.lang.String.class)
    @JoinTable(name="CO_SHR",joinColumns=@JoinColumn(name="CO_ID"))
    @Column(name="CO_SHR")
    @Sort(type=SortType.NATURAL)
    public SortedSet<String> getShareholders() {
        return this.shareholders;
    }


(Note that if you use HashSet, the retrieved collection may not be in the same order as it was persisted.)


If it must be java.util.List, then another solution is to use @IndexColumn which would mean the Collection semantic is that of List and not Bag. As well as a name, the Index can have a base number which if not specified will default to zero.


    @CollectionOfElements(fetch=FetchType.EAGER,targetElement=java.lang.String.class)
    @JoinTable(name="CO_SHR",joinColumns=@JoinColumn(name="CO_ID"))
    @Column(name="CO_SHR")
    @IndexColumn(name="IDX",base=1)
    public List<String> getShareholders() {
        return this.shareholders;
    }


This post highlights the need to think carefully about all associations and pose questions like what needs to be EAGERly loaded, what is the effect on memory usage, etc...

Thursday 22 March 2012

RestTemplate and Spring MVC

This post is a follow up to the Spring MVC and RESTful Web Services post and shows a simple example of using Spring's RestTemplate class for client side access to, in this case, the Spring MVC RESTful web service built in the aforementioned post.

The RestTemplate class is, as it's javadoc describes, "the central class for client-side HTTP access. It simplifies communication with HTTP servers, and enforces RESTful principles. It handles HTTP connections, leaving application code to provide URLs (with possible template variables) and extract results."

In this example, we'll only be using the GET HTTP method (as that is all we have on our MVC example!) but the idea will be pretty much the same for other methods.

First, the Spring config and the XML below lists three beans. The Jaxb2Marshaller bean lists the classes that the JAXBContext needs to be aware of. This bean is then in turn injected into the MarshallingHttpMessageConverter as the marshaller and unmarshaller so Objects can be converted to and from an XML Stream. (Note that by default the MarshallingHttpMessageConverter supports text/xml and application/xml.) For this example, the message converter is the only entry in the list set on the RestTemplate bean. Finally, the RestTemplate bean is injected into the ExampleControllerClient bean.


<beans xmlns="http://www.springframework.org/schema/beans"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://www.springframework.org/schema/beans 
 http://www.springframework.org/schema/beans/spring-beans.xsd">

 <bean id="jaxbMarshaller" class="org.springframework.oxm.jaxb.Jaxb2Marshaller">
  <property name="classesToBeBound">
   <list>
    <value>com.city81.spring.mvc.rest.domain.Message</value>
   </list>
  </property>
 </bean>

 <bean id="restTemplate" class="org.springframework.web.client.RestTemplate">    
  <property name="messageConverters">    
   <list>      
    <bean id="messageConverter"            
     class="org.springframework.http.converter.xml.MarshallingHttpMessageConverter">        
     <property name="marshaller" ref="jaxbMarshaller" />        
     <property name="unmarshaller" ref="jaxbMarshaller" />    
    </bean>    
   </list>    
  </property>  
 </bean>

 <bean id="exampleControllerClient" class="com.city81.spring.mvc.rest.ExampleControllerClient">
  <constructor-arg ref="restTemplate" />
 </bean>

</beans> 


The ExampleControllerClient class below shows how simple it is to make a RESTful web service call:

package com.city81.spring.mvc.rest;

import org.springframework.beans.factory.BeanFactory;
import org.springframework.context.support.ClassPathXmlApplicationContext;
import org.springframework.web.client.RestTemplate;
import com.city81.spring.mvc.rest.domain.Message;

public class ExampleControllerClient {

 private RestTemplate restTemplate;

 public ExampleControllerClient(RestTemplate restTemplate) {
  this.restTemplate = restTemplate;
 }

 public void getMessage() {

  Message message = restTemplate.getForObject(
   "http://localhost:8080/spring-rest-0.0.1-SNAPSHOT/example/controller/message", 
   Message.class); 
  System.out.println(message.getMessageString());
 }

 public static void main(String[] args) {

  ClassPathXmlApplicationContext appContext = new ClassPathXmlApplicationContext(
          new String[] {"applicationContext.xml"});
  BeanFactory factory = (BeanFactory) appContext;
  ExampleControllerClient client = (ExampleControllerClient) factory
    .getBean("exampleControllerClient");
  client.getMessage();

 }

}


The getForObject method takes a URL and the type of the response object and retrieves a representation by doing a GET on the URL arg. This method is overloaded and can be used for different URLs. For example, if there are URI templates in the URL, then these can be populated by a third arg of a Map containing a collection of name value pairs or by using varargs.


public  T getForObject(String url,
                          Class responseType,
                          Object... urlVariables)
               throws RestClientException

public  T getForObject(String url,
                          Class responseType,
                          Map urlVariables)
               throws RestClientException


Back to the example and when the getForObject call is invoked, the JAXB marshaller behind the scenes will convert the XML into a Message object. An alternative to using the Jaxb2Marshaller  is the XStreamMarshaller. To swap JAXB for XStream would just be a Spring XML change as shown below:


<bean id="xstreamMarshaller" class="org.springframework.oxm.xstream.XStreamMarshaller">    
   <property name="aliases">    
    <props>      
     <prop key="message">com.city81.spring.mvc.rest.domain.Message</prop>    
    </props>    
   </property>  
  </bean>

...
     <property name="marshaller" ref="xstreamMarshaller" />        
     <property name="unmarshaller" ref="xstreamMarshaller" /> 
...


There are many different marshallers to achieve the same goal, and indeed many different media types with different marshallers. This post barely scratches the surface but just shows how simple it is to create client side code for calling a RESTful web service.

Tuesday 31 January 2012

Parallel Processing with ForkJoinPool

With the release of Java 7 came the new Executor Service, ForkJoinPool. The class uses the notion of work-stealing threads which execute tasks which have been created by other tasks. Ultimately, this division of work will result in large problems becoming a series of smaller ones which will eventually result in one answer when all the tasks have completed their processing.

This post will demonstrate this new threading feature by an interpolation example. In this case, for two numbers with a given number of steps, the code will attempt to construct new points between those numbers using linear interpolation, and for simplicity using only a number of steps divisible by 2. eg for the numbers 5 and 25 with a step number of 4, the generated sequence would be:

[5.0, 10.0, 15.0, 20.0, 25.0]

The InterpolationService class below will contain an instance of the ForkJoinPool class. A ForkJoinPool instance can be created with an argument representing a target parallelism. This can either be supplied or left as the default which will be the number of processors ie  Runtime.availableProcessors()

package com.city81.forkjoin;

import java.util.ArrayList;
import java.util.List;
import java.util.concurrent.ForkJoinPool;
import java.util.concurrent.ForkJoinTask;
import java.util.concurrent.RecursiveTask;

public class InterpolateService {

    private final ForkJoinPool forkJoinPool;

    public InterpolateService() {
        forkJoinPool = new ForkJoinPool();
    }

    public List<Double> interpolate(double valueOne, double valueTwo, int steps) {
        
        ForkJoinTask<List<Double>> job = forkJoinPool.submit(
            new InterpolateTask(valueOne, valueTwo, steps));
        return job.join();
    }

    private static class InterpolateTask 
        extends RecursiveTask<List<Double>> {

        private final double valueOne;
        private final double valueTwo;
        private final int steps;
        private static final int LOWEST_STEP = 2;

        protected InterpolateTask(double valueOne, double valueTwo, int steps) {

            this.valueOne = valueOne;
            this.valueTwo = valueTwo;
            this.steps = steps;
        }

        @Override
        protected List<Double> compute() {
    
            List<Double> interpolatedArray = new ArrayList<Double>();
            double interpolatedValue = interpolate(valueOne, valueTwo);
    
            if (this.steps == LOWEST_STEP) {
                interpolatedArray.add(valueOne);
                interpolatedArray.add(interpolatedValue);
                interpolatedArray.add(valueTwo);
            } else {
                InterpolateTask interpolateTask1 = 
                    new InterpolateTask(valueOne, interpolatedValue, (steps/2));
                interpolateTask1.fork();
                InterpolateTask interpolateTask2 = 
                    new InterpolateTask(interpolatedValue, valueTwo, (steps/2));
                List<Double> interpolatedArrayTask2 = 
                    interpolateTask2.compute();
                List<Double> interpolatedArrayTask1 = 
                    interpolateTask1.join();
                interpolatedArray.addAll(
                    interpolatedArrayTask1.subList(0, interpolatedArrayTask1.size() - 1));
                interpolatedArray.addAll(interpolatedArrayTask2);
            }
            // System.out.println(interpolatedArray);
            return interpolatedArray;
        }

        private double interpolate(
            double valueOne, double valueTwo) {
   
            return ((valueTwo - valueOne) / 2.0) + valueOne;
        }

    }

    public static void main(String[] args) {
        InterpolateService interpolateService = new InterpolateService();
        List<Double> interpolatedArray = interpolateService.interpolate(5,25,4);
        System.out.println(interpolatedArray);
    }

}

The InterpolationService 's only public method interpolate, takes two numbers and the number of steps. These are the parameters to construct an instance of our private static class InterpolateTask. This class implements RecursiveTask which can return a result when the compute method is called on the task. An alternative implementation (but not suitable for this example) would be RecursiveAction whose compute method returns nothing.

The constructed task is submitted to the ForkJoinPool.

The compute method is where the logic for subdividing the task resides. It decides whether the work it has to process is small enough to process now or whether it needs further division. In the case of our example, the task will determine a task small enough when the step size is 2. If not, it will create two sub tasks, dividing the step size each time.

Eventually, all tasks will be of a small enough size to be completed. This will result in the arrays being added together as the recursive task tree is traversed back up to the original task.

This is not example of how to efficiently perform linear interpolation on a set of numbers but is just one example implementation of how to use the ForkJoinPool and its associated Task classes. Over time, hopefully this post can be updated to make the above code more efficient as well gathering metrics and benchmarking against other implementations.

Friday 27 January 2012

Spring MVC and RESTful Web Services

This post is a follow up to the Spring MVC Bare Essentials post and shows how a simple RESTful web service can be implemented using Spring MVC. It'll also show the different ways in which the controller services can be implemented and how the model can be rendered.

The post will use the same classes and XML files as in the Bare Essentials post but change them to make the methods expoed by the controller RESTful.

First of all, the ExampleController class will change to use web bind annotations which will mark the class and the methods within it with URL paths.

@Controller
@RequestMapping("/controller")
public class ExampleController {

    @RequestMapping(value="message", method=RequestMethod.GET)

    public ModelAndView getMessage() {
        Message message = new Message("Spring MVC Rest Example");
        ModelAndView modelAndView = new ModelAndView(
            "example", "message", message);
        return modelAndView;
    }

}


The web.xml below shows the changes to the servlet mapping tag and in particular the url-pattern. This means our URLs will be:

http://<ip>:<port>/<app name>/example/<request mapping>

<servlet-mapping>
    <servlet-name>springMVCRESTExample</servlet-name>
    <url-pattern>/example/*</url-pattern>
</servlet-mapping>


In the servlet's context XML file, we'll auto detect the ExampleController bean by using context:component-scan and then add the BeanNameViewResolver to interpret a view name as a bean name. Finally, add a MarshallingView which will use JAX-B to marshall and unmarshall the com.city81.spring.mvc.rest.domain.Message class.

<context:component-scan base-package="com.city81.spring.mvc.rest" /> 

<bean class="org.springframework.web.servlet.view.BeanNameViewResolver" />

<bean id="example" class="org.springframework.web.servlet.view.xml.MarshallingView">
    <constructor-arg>
        <bean class="org.springframework.oxm.jaxb.Jaxb2Marshaller">
            <property name="classesToBeBound">
                <list>
                    <value>com.city81.spring.mvc.rest.domain.Message</value>
                </list>
            </property>
        </bean>
    </constructor-arg>
</bean>


Building a WAR and deploying to a container such as Tomcat would then enable you call the getMessage method of the ExampleController class with the URL:

http://<ip>:<port>/<app name>/example/controller/message

An alternative to implementing the getMessage method is to use the @ModelAttribute instead the the ModelView class as shown below:

@RequestMapping(value = "message", method = RequestMethod.GET)
public @ModelAttribute("example") Message getMessage() {
    Message message = new Message("Spring MVC Rest Example");
    return message;
}


Another alternative is to use <mvc:annotation-driven /> which was introduced in Spring 3. By adding it to the servlet's context XML file (in place of the beans BeanNameViewResolver and MarshallingView), the getMessage method can then be implemented as show below:

@RequestMapping(value="message", method = RequestMethod.GET)
public @ResponseBody Message getMessage() {
    Message message = new Message("Spring MVC Rest Example");
    return message;
}


This is a very simple example that can be built upon to use different RESTful methods. There are also different ways in which XML can be rendered in the view and also different types that can be rendered eg text. It is also worth considering Spring Roo if wanting to implement a RESTful web service. These will hopefully be covered in further posts.

Thursday 19 January 2012

Using Maven to Generate Wrapped or Non-Wrapped SOAP Bindings

For a given WSDL, there are several different ways to generate Java web service code (CXF, Axis2, etc..). And depending on certain settings within the WSDL file and settings used by the relevant build tool, there are different ways of exposing those services described in the WSDL.

This post will briefly document the generating of Java code for a WSDL using Maven and the jaxws wsimport plugin. It will also show the difference in the services exposed when using wrapped and non-wrapped bindings.

Below is an extract from a pom.xml to generate the Java code:

<plugin>
    <groupId>org.codehaus.mojo</groupId>
    <artifactId>jaxws-maven-plugin</artifactId>
    <version>1.10</version>
    <executions>
        <execution>
            <goals>
                <goal>wsimport</goal>
            </goals>
            <configuration>
                <wsdlFiles>
                    <wsdlFile>City81SOAPService.wsdl</wsdlFile>
                </wsdlFiles>
                <bindingDirectory>${basedir}/src/wsdl</bindingDirectory>
            </configuration>
            <id>generate-sources</id>
            <phase>generate-sources</phase>
        </execution>
    </executions>
    <dependencies>
         .........            
    </dependencies>
    <configuration>
        <sourceDestDir>
            ${project.build.directory}/generated-sources/jaxws-wsimport
        </sourceDestDir>
        <xnocompile>true</xnocompile>
        <verbose>true</verbose>
        <extension>true</extension>
        <catalog>${basedir}/src/jax-ws-catalog.xml</catalog>                  
    </configuration>
</plugin>


For the below WSDL file, the wsimport plugin will generate the following classes:

com\city81\soap\Balance.java
com\city81\soap\City81SOAP.java
com\city81\soap\City81SOAPImplService.java
com\city81\soap\CreateCustomer.java
com\city81\soap\CreateCustomerResponse.java
com\city81\soap\CreateCustomerResponseType.java
com\city81\soap\CreateStatus.java
com\city81\soap\ObjectFactory.java
com\city81\soap\package-info.java


<?xml version='1.0' encoding='UTF-8'?>
<wsdl:definitions name="City81SOAPService" targetNamespace=http://soap.city81.com/ xmlns:ns1=http://schemas.xmlsoap.org/wsdl/soap/http
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:tns="http://soap.city81.com/"
xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:xsd="http://www.w3.org/2001/XMLSchema">

    <wsdl:types>
        <xsd:schema>
            <xsd:import namespace="http://soap.city81.com/" schemaLocation="City81SOAPService.xsd" />
        </xsd:schema>
    </wsdl:types>

    <wsdl:message name="createCustomer">
        <wsdl:part name="params" element="tns:createCustomer"></wsdl:part>
    </wsdl:message>
    <wsdl:message name="createCustomerResponse">
        <wsdl:part name="params" element="tns:createCustomerResponse"></wsdl:part>
    </wsdl:message>

    <wsdl:portType name="City81SOAP">
        <wsdl:operation name="createCustomer">
            <wsdl:input message="tns:createCustomer"></wsdl:input>
            <wsdl:output message="tns:createCustomerResponse"></wsdl:output>
        </wsdl:operation>
    </wsdl:portType>

    <wsdl:binding name="City81SOAPImplServiceSoapBinding" type="tns:City81SOAP">
        <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http" />
        <wsdl:operation name="createCustomer">
            <soap:operation soapAction="http://soap.city81.com/createCustomer" />
            <wsdl:input>
                <soap:body use="literal" />
            </wsdl:input>
            <wsdl:output>
                <soap:body use="literal" />
            </wsdl:output>
        </wsdl:operation>
    </wsdl:binding>

    <wsdl:service name="City81SOAPImplService">
        <wsdl:port binding="tns:City81SOAPImplServiceSoapBinding" name="City81SOAPImplPort">
            <soap:address location=http://localhost:8080/city81-soap/soap />
        </wsdl:port>
    </wsdl:service>

</wsdl:definitions>


For the above settings, the generated City81SOAP class will be as below:

@WebService(name = "City81SOAP", targetNamespace = "http://soap.city81.com/")
@SOAPBinding(parameterStyle = SOAPBinding.ParameterStyle.BARE)
@XmlSeeAlso({
    ObjectFactory.class
})
public interface City81SOAP {

    @WebMethod(action = "http://soap.city81.com/createCustomer")
    @WebResult(name = "createCustomerResponse", targetNamespace = "http://soap.city81.com/", partName = "params")
    public CreateCustomerResponse createCustomer(@WebParam(name = "createCustomer", targetNamespace = "http://soap.city81.com/", partName = "params") CreateCustomer params);

}


The binding style as can be seen from the @SOAPBinding annotation  at the head of the class is BARE ie non-wrapped. The method's args and return parameters are in each case represented as a single Java object. CreateCustomer and CreateCustomerResponse.

This has happened because in the pom.xml file, there is a bindingDirectory tag which points to a folder containing a binding.xml file. This file, shown below, has an enableWrapperStyle tag and the boolean value of false.

<bindings
    xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
    wsdlLocation="City81SOAPService.wsdl"
    xmlns="http://java.sun.com/xml/ns/jaxws">
        <!-- Disable default wrapper style -->
        <enableWrapperStyle>false</enableWrapperStyle>        
</bindings>


If the boolean was true, or if there was no bindingDirectory tag in the pom.xml file, then the default SOAP binding style would be used ie WRAPPED. This would then result in the below generated City81SOAP class:

@WebService(name = "City81SOAP", targetNamespace = "http://soap.city81.com/")
@XmlSeeAlso({
    ObjectFactory.class
})
public interface City81SOAP {

    @WebMethod(action = "http://soap.city81.com/createCustomer")
    @RequestWrapper(localName = "createCustomer", targetNamespace = "http://soap.city81.com/", className = "com.city81.soap.CreateCustomer")
    @ResponseWrapper(localName = "createCustomerResponse", targetNamespace = "http://soap.city81.com/", className = "com.city81.soap.CreateCustomerResponse")
    public void createCustomer(

        @WebParam(name = "surname", targetNamespace = "")
        String surname,
        @WebParam(name = "firstName", targetNamespace = "")
        String firstName,
        @WebParam(name = "balance", targetNamespace = "")
        Balance balance,
        @WebParam(name = "customerId", targetNamespace = "", mode = WebParam.Mode.OUT)
        Holder<String> customerId,
        @WebParam(name = "status", targetNamespace = "", mode = WebParam.Mode.OUT)
        Holder<CreateStatus> status);

}


The method's args are now individual Java objects and the return parameters are each represented as Holder objects with a WebParam.Mode.OUT value denoting they are return objects. This means that return objects are set as opposed to actually being returned in the method's signature.

Another way to specify bindings other than using the binding.xml file is to embed the enableWrapperStyle as a child of the portType but if a WSDL is from a third party, then having to change it every time a new version of the WSDL is released is open to errors.

<wsdl:portType name="City81SOAPImplService">
    <jaxws:bindings xmlns:jaxws="http://java.sun.com/xml/ns/jaxws">
        <jaxws:enableWrapperStyle>false</jaxws:enableWrapperStyle>
    </jaxws:bindings>
    ...
</wsdl:portType>


Back to the generated interfaces, and these of course need to be implemented. For an interface with a binding type of BARE, the implemented class would look like below:

@WebService(targetNamespace = "http://soap.city81.com/", name = "City81SOAP", portName = "City81SOAPImplPort", serviceName = "City81SOAPImplService")
@SOAPBinding(style = SOAPBinding.Style.DOCUMENT, use = SOAPBinding.Use.LITERAL, parameterStyle = SOAPBinding.ParameterStyle.BARE)
public class City81SOAPImpl implements City81SOAP {    

    @Override   
    public CreateCustomerResponse createCustomer(CreateCustomer createCustomer) {      
        CreateCustomerResponse createCustomerResponse = 
            new CreateCustomerResponse();     
         .....
        return createCustomerResponse;  
    } 
}


In the case of WRAPPED binding style, the SOAPBinding annotation would include parameterStyle = SOAPBinding.ParameterStyle.WRAPPED and the createCustomer method would be as below:
 

    public void createCustomer(
        String surname,
        String firstName,
        Balance balance,
        Holder<String> customerId,
        Holder<CreateStatus> status) {
    
        customerId= new Holder<String>("1");
        status = new Holder<CreateStatus>(CreateStatus.CREATE_PENDING);
    }   


This post shows that there are different ways to ultimately achieve the same result.