Download the Stand-alone installer for JBoss Developer Studio (JBDS) 9.1.0 from the Red Hat Customer Support Portal.

The installer is an executable JAR file. Installing a recent version of the JDK and having the java and associated commands in the execution path is a prerequisite to using JBDS and JBoss Fuse itself.

In most operating systems, it is enough to simply double-click the JBoss Developer Studio installation JAR file to start installing the IDE. You can also trigger the installation from the command line:

$ java -jar jboss-devstudio-9.1.0.GA-installer-standalone.jar

Accept the license, choose a location to install the product and proceed with the installation. Select the default or preferred JDK location. Is it not necessary to configure any platform or server location while installing JBoss Developer Studio.

Start JBoss Developer Studio by locating the shortcut created in the designated location. Select a location for the IDE workspace. Once started, an initial welcome screen appears. Close this screen to enter the familiar Eclipse framework environment.

Click the drop-down for the New toolbar icon at the top left of the JBoss Developer Studio window and select Maven Project. Alternatively, you can click the icon to open the New wizard dialog, open the group called Maven and select Maven Project from there.

Create a new project called product that will handle the definition and inventory management of the products sold through the e-commerce site that is the subject of this reference architecture’s sample application.

The new project wizard prompts you to select a location for the project or use the default workspace location. For temporary and testing purposes, it is easiest to let JBDS simply create the project in the designated workspace. Select Next and choose the jboss javaee6 blank webapp archetype to create the basic structure for a Web Application project based on Maven. When a webapp archetype is avaivalable for a more recent and better matching version of JBoss EAP, it can be substituted, but the basic strcuture of the project remains the same:

Figure 5.1. Maven Archetype

Use the next dialog to set the group and artifact Id of the project, as well as the version:

Figure 5.2. Maven Project

Click the finish button to complete the initial project setup.

The project template is only a starting point and requires a number of additions, removals and modifications to adapt to individual projects. This reference architecture uses and relies on Java 8. Open the generated Maven Project Object Model (pom) file in JBoss Developer Studio and change the Java version:

Figure 5.3. Java version in pom file

Change the Java version for both the source code and the generated artifacts to 1.8 by modifying the value of the maven.compiler.source and maven.compiler.target properties. In each case, double-click the property in the Overview window to open a dialog and edit the value.

The maven template includes support for JPA and creates a default persistence configuration file to connect to a datasource.

This persistence configuration file is located at: src/main/resources/persistence.xml

As part of the maven template, this file includes a single persistence unit called primary. The name of the transactional datasource is derived from the project name. Review this configuration by opening the persistence xml file in JBoss Developer Studio and navigating to the Connection tab:

Figure 5.4. Datasource Configuration

Rename the data source to simply use a capital letter at the beginning: ProductDS

Change to the Hibernate tab. Configure hibernate to use your database of choice. This reference architecture uses MySQL and sets the Database dialect accordingly:

Figure 5.5. Hibernate Dialect Setting

For learning purposes, it can also be useful to turn on hibernate logging of SQL statements by setting hibernate.show_sql to true. This can be configured from the Properties tab.

Also note the hibernate.hbm2ddl.auto property, concerning the mapping of JPA classes to database tables. The template default value of create-drop results in non-persistent behavior between application redeployment and server restarts. This property should be set to a value of validate, or complete removed, when not in an early testing phase.

The remainder of this document assumes that this property has been removed. Instead, database scripts are used to create the required tables.

Create a JPA entity to represent a product that will be listed and sold through the e-commerce application.

 @Entity
 public class Product
 {

 @Id
 @GeneratedValue(strategy = GenerationType.IDENTITY)
 private Long sku

 @NamedQuery(name = "Product.findFeatured",
			 query = "SELECT p FROM Product p WHERE p.featured = true")

 List<Product> products = em.createNamedQuery( "Product.findFeatured",
												Product.class ).getResultList();

 @Entity
 public class Keyword
 {
     @Id
     private String keyword;

 @ManyToMany(fetch = FetchType.EAGER, mappedBy = "keywords")
 private List<Product> products;

 @ManyToMany(fetch = FetchType.EAGER)
 @JoinTable(name = "PRODUCT_KEYWORD",
     joinColumns = @JoinColumn(name = "SKU", referencedColumnName = "SKU"),
     inverseJoinColumns = @JoinColumn(name = "KEYWORD",
 private List<Keyword> keywords;

 @NamedQuery(name = "Keyword.findKeyword",
	query = "SELECT k FROM Keyword k WHERE UPPER(k.keyword) = UPPER(:query)")

To enable support for the Java API for RESTful Web Services (JAX-RS), create a web descriptor for your application and provide a mapping for the standard JAX-RS servlet, which is javax.ws.rs.core.Application.

To create a web.xml descriptor, first navigate to the src/main/webapp/WEB-INF directory of your project in JBoss Developer Studio. Using either the File menu or by right-clicking on the folder, select to create a new artifact of type Other. Select Web Descriptor from the JBoss Tools Web category and press Next. Change the Servlet version to 3.1 and type the name as web.xml:

Figure 5.6. Create Web Descriptor

Click the Finish button to create the web.xml file. JBoss Developer Studio automatically opens this file in the web descriptor editor.

Right-click on the web.xml file name in the editor and select to create a new Servlet Mapping.

Enter the fully qualified class name of the JAX-RS Servlet and map it to the web application context root:

Figure 5.7. JAX-RS Servlet Mapping

The mapping specified for the JAX-RS servlet determines the root context of REST requests. The maven configuration of this web application has a project name of product and specifies war as its packaging format. As a result, this web application will have a root context of /product. Using a wildcard URL pattern means that this will also be the top context of REST requests.

To create a RESTful service, simply create a Java class and annotate the class with javax.ws.rs.Path.

Create a package called com.redhat.refarch.microservices.product.service in your project and place the ProductService class in this package.

This will be the only RESTful service in the product web application and it can therefore consume all requests targeted at the web application target. Set the service path to root:

 package com.redhat.refarch.microservices.product.service;

 import javax.ws.rs.Path;

 @Path("/")
 public class ProductService
 {

 }

To create an operation for this service, create a method and annotate it with a Path. For example, create a method called addProduct that both takes and returns a product and specify its relative context as /products.

Note that the URL of this operation will be a combination of the path to the server, the web application, the JAX-RS servlet, the service and the operation itself. Assuming a local development server listening on http://localhost:8080 and the current maven build file, which generates a web application called product.war, along with the root relative context given to the JAX-RS servlet and product service itself, the path pieces are http://localhost:8080 and /product and / and /products.

The final path to this operation is: http://localhost:8080/product/products

Also use annotations to declare the HTTP method supported by this operation as well as the media type consumed and produced.

Create this operation with the assumption that the product will be posted to the service in JSON form and also returned in JSON form:

	@Path("/products")
	@POST
	@Consumes(MediaType.APPLICATION_JSON)
	@Produces(MediaType.APPLICATION_JSON)
	public Product addProduct(Product product)
	{
		return product;
	}

Build the project by running the install goal of maven, either through JBDS by choosing Run As Maven build or in command line: mvn install

Once built, a product.war archive file will be generated in the target directory. Deploy this web application archive to JBoss EAP.

Once deployed, test invoking the add product operation. Use a REST client of your choice. For example, if using the cURL command line tool:

# curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d @request.json http://localhost:8080/product/products

{"sku":null,"name":"Product","description":"The product description","length":40,"width":40,"height":40,"weight":1040,"featured":true,"availability":10,"price":19.95,"image":null}

In the above example, the request.json file would be created with the following content:

Notice that the JAX-RS implementation automatically deserializes the JSON request to the provided Java type. The missing fields are left as null and this can be observed in the response.

Deserializing XML to Java types requires an extra step. JBoss EAP 7 can use JAXB to convert Java to XML and back, but Java classes must be annotated as XML types. Modify the Product class and annotate it as a JAXB root element:

 @Entity
 @NamedQuery(name = "Product.findFeatured",
			 query = "SELECT p FROM Product p WHERE p.featured = true")
 @XmlRootElement
 public class Product
 {

Modify the add product annotation to include XML as an acceptable media type for both the request and response:

	@Path("/products")
	@POST
	@Consumes({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
	@Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
	public Product addProduct(Product product)

Note the use of curly braces to specify a list of options instead of a single string value.

Redeploy the web application and issue a similar REST request in XML, specifying both the request and response types as application/xml: Once again, using the cURL command line tool:

# curl -X POST -H 'Content-Type: application/xml' -H 'Accept: application/xml' -d @request.xml http://localhost:8080/product/products

<?xml version="1.0" encoding="UTF-8" standalone="yes"?><product><description>The product description</description><height>40</height><length>40</length><name>Product</name><weight>1040</weight><width>40</width></product>

Note that while serializing the response, JAXB simply omits elements with a null value. The request XML looks as follows:

Some operations such as JPA persistence require a transactional context to proceed. The Narayana 5 community project, used as the basis of the transactions subsystem in JBoss EAP 7, provides REST transactions. However JBoss EAP 7 does not support this feature and only includes support for WS-BA and WS-AT. This reference application simply relies on transactions with the scoped of individual REST services. To create a transactional context for a REST operation, you can use either implicit container managed transactions or user transactions.

To leverage user transactions, declare the required dependencies on the transaction API and inject a user transaction object. Once this is set up, you can start a transaction at any point by calling the begin() method. The entity manager can enlist the database driver in the transaction through its joinTransaction() method. After the success or failure of the operation, either the commit() or the rollback() methods can be called to respectively commit or abandon the transaction.

It is often much simpler to allow the application server to manage transactions. This functionality is available for EJB3 session beans. Any class annotated as a REST service can also be enhanced to act as a stateless session bean. Annotate the ProductService class as a stateless session bean with no interface (therefore only a local bean):

 @Path("/")
 @Stateless
 @LocalBean
 public class ProductService
 {

Inject an entity manager to find, query, save, update and delete JPA entities:

	@PersistenceContext
	private EntityManager em;

Modify the add product operation to use this entity manager and persist the supplied product:

	@Path("/products")
	@POST
	@Consumes({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
	@Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
	public Product addProduct(Product product)
	{
		em.persist( product );
		return product;
	}

Redeploy the application and test it again by invoking the add product operation. For example, using cURL:

# curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d @request.json http://localhost:8080/product/products

{"sku":10012,"name":"Product","description":"The product description","length":40,"width":40,"height":40,"weight":1040,"featured":true,"availability":10,"price":19.95,"image":null}

Notice that this time, the SKU has been filled in and returned as 10012. That is because the object was persisted to the database and its primary key was auto generated. The table was created with SKU as a primary key that is auto-incremented and starts with 10001:

...PRIMARY KEY (SKU)) AUTO_INCREMENT = 10001;

After inserting 11 sample products into the database using SQL scripts, the next inserted row should indeed be assigned a primary key of 10012.

Use the Java Logging API to plug into the JBoss EAP logging mechanism. Create a logger field in your service class and use the class name as the name:

	@PersistenceContext
	private EntityManager em;

	private Logger logger = Logger.getLogger( getClass().getName() );

For convenience, create logInfo and logError methods that log statements with the respective verbosity levels:

	private void logInfo(String message)
	{
		logger.log( Level.INFO, message );
	}

	private void logError(String message)
	{
		logger.log( Level.SEVERE, message );
	}

Use these convenience methods to generate log statements that can help troubleshoot and verify application functionality:

	public Product addProduct(Product product)
	{
		logInfo( "Will persist product " + product );
		em.persist( product );
		return product;
	}

Well-designed RESTful services use standard HTTP codes along with descriptive information to communicate errors. The JAX-RS specification allows developers to return HTTP errors by throwing javax.ws.rs.WebApplicationException.

To validate a request and return an error when invalid, use HTTP code 422:

	throw new WebApplicationException( 422 );

While this simple approach succeeds in communicating a correct and meaningful HTTP error code back to the client, it fails to provide any details or even return the response in the expected format, which is typically either JSON or XML. To return the proper descriptive response with the error, create a javax.ws.rs.core.Response object and pass it to the constructor of javax.ws.rs.WebApplicationException.

Create an Error class to use to represent various potential errors.

Like other object types returned by the RESTful serivce, annotate this class as javax.xml.bind.annotation.XmlRootElement so that it can be serialized to both JSON and XML. Create the following fields in the Error class:

The Error class would start as follows:

 package com.redhat.refarch.microservices.product.model;

 import javax.xml.bind.annotation.XmlRootElement;

 @XmlRootElement
 public class Error
 {

	private int code;
	private String message;
	private String details;

Provide convenient constructors to instantiate the class:

	public Error(int code, String message, Throwable throwable)
	{
		this.code = code;
		if( message != null )
		{
			this.message = message;
		}
		else if( throwable != null )
		{
			this.message = throwable.getMessage();
		}
		if( throwable != null )
		{
			StringWriter writer = new StringWriter();
			throwable.printStackTrace( new PrintWriter( writer ) );
			this.details = writer.toString();
		}
	}

	public Error(int code, String message)
	{
		this( code, message, null );
	}

	public Error(int code, Throwable throwable)
	{
		this( code, null, throwable );
	}

There is no legitimate use case for a default constructor with no arguments, however JAXB requires such a constructor. Providing a private constructor allows you to satisfy this JAXB requirement without promoting the incorrect use of the class:

	@SuppressWarnings("unused")
	private Error()
	{
	}

Remember that serialization to either JSON or XML is based on JavaBean properties. Provide getter and setter methods for only the second and third field, to include them in the response:

	public String getMessage()
	{
		return message;
	}

	public void setMessage(String message)
	{
		this.message = message;
	}

	public String getDetails()
	{
		return details;
	}

	public void setDetails(String details)
	{
		this.details = details;
	}

Also provide a convenience method to return a WebApplicationException based on this Error response:

	public WebApplicationException asException()
	{
		ResponseBuilder responseBuilder = Response.status( code );
		responseBuilder = responseBuilder.entity( this );
		return new WebApplicationException( responseBuilder.build() );
	}

This class may now be used to return meaningful error messages. For example, try validating that the product being added has its name, price and availability set:

	@Path("/products")
	@POST
	@Consumes({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
	@Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
	public Product addProduct(Product product)
	{
		if( product.getAvailability() == null ||
			product.getName() == null || product.getPrice() == null )
		{
			throw new Error( 422, "Validation Error" ).asException();
		}

The Error class can also map any potential Java exceptions into a response code and description that can be consumed by a RESTful client. For example, an attempt to store a product that violates database constraints causes the entity manager to throw a javax.persistence.PersistenceException, which is a runtime exception:

		try
		{
			logInfo( "Will persist product " + product );
			em.persist( product );
			return product;
		}
		catch( RuntimeException e )
		{
			logError( "Got exception " + e.getMessage() );
			throw new Error( HttpURLConnection.HTTP_INTERNAL_ERROR,
										e ).asException();
		}

Redeploy the application and test error handling. Try to add a product using JSON without including the price, with a request.json file as follows:

Use the -i parameter with cURL to include the response headers:

# curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d @request.json -i http://localhost:8080/product/products

HTTP/1.1 422 Unprocessable Entity
Server: Apache-Coyote/1.1
Content-Type: application/json
Transfer-Encoding: chunked
Date: ...

{"message":"Validation Error","details":null}

Notice that the error code 422 is included in the response along with its default HTTP description. Now, try the corresponding XML request:

The response looks a bit different this time:

# curl -X POST -H 'Content-Type: application/xml' -H 'Accept: application/xml' -d @request.xml -i http://localhost:8080/product/products

HTTP/1.1 422 Unprocessable Entity
Server: Apache-Coyote/1.1
Content-Type: application/xml
Content-Length: 105
Date: Sat, 28 Mar 2015 00:28:48 GMT

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<error><message>Validation Error</message></error>

Most notably, the JSON response includes a null detail whereas the XML response omits it entirely. These differences may be attributed to both the protocol as well as the serialization libraries.

Include the price to pass validation but change one of the other fields to an invalid value that will fail persistence. For example, set the weight to 9999999 which violates database constraint for the corresponding column. The details of the response will include the full stack of the exception:

Note that simply catching and mapping Java exceptions to a service error risks exposing any content contained in the exception stack. Employ caution to not inadvertently expose vulnerabilities or any other information that you do not wish to expose as part of the exception stack trace.

While no strict standards govern RESTful service API design, conventions and common practice often go a long way in promoting consistent behavior. Familiar API design helps increase productivity and reduce misunderstanding and developer error.

This document proposes a set of URL patterns that are combined with standard HTTP methods to provide full create, read, update and delete (CRUD) capability for a resource using RESTful API.

There are some disagreements on the details of this approach but a large number of systems use some slight variation of this.

	@Path("/products")
	@POST
	@Consumes({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
	@Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
	public Product addProduct(Product product)

	@Path("/products")
	@POST
	@Consumes({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
	@Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
	public Product addProduct(Product product)
	{
		try
		{
			logInfo( "Will persist product " + product );
			em.persist( product );
			return product;
		}
		catch( RuntimeException e )
		{
			logError( "Got exception " + e.getMessage() );
			throw new Error( HttpURLConnection.HTTP_INTERNAL_ERROR,
										e ).asException();
		}
	}

	@GET
	@Path("/products")
	@Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
	public Collection<Product> getProducts(@Context UriInfo uriInfo)
	{
		try
		{
			MultivaluedMap<String, String> queryParams =
								uriInfo.getQueryParameters();

if( queryParams.containsKey( "featured" ) )
{
	return em.createNamedQuery( "Product.findFeatured",
								Product.class ).getResultList();
}

else if( queryParams.containsKey( "keyword" ) )
{
	Collection<Product> products = new HashSet<Product>();
	for( String keyword : queryParams.get( "keyword" ) )
	{
		try
		{
			TypedQuery<Keyword> query =
	em.createNamedQuery( "Keyword.findKeyword", Keyword.class );
			query.setParameter( "query", keyword );
			Keyword keywordEntity = query.getSingleResult();
			List<Product> keywordProducts = keywordEntity.getProducts();
			logInfo( "Found " + keyword + ": " + keywordProducts );
			products.addAll( keywordProducts );
		}
		catch( NoResultException e )
		{ //keyword not found, which is acceptable
		}
	}
	return products;
}

  else
  {
  	throw new Error( HttpURLConnection.HTTP_BAD_REQUEST,
				"All products cannot be returned" ).asException();
  }
}
catch( RuntimeException e )
{
  throw new Error( HttpURLConnection.HTTP_INTERNAL_ERROR, e ).asException();
}

	@GET
	@Path("/products/{sku}")
	@Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
	public Product getProduct(@PathParam("sku") Long sku)
	{
		logInfo( "SKU is " + sku );
		Product product = em.find( Product.class, sku );
		if( product == null )
		{
			throw new Error( HttpURLConnection.HTTP_NOT_FOUND,
							"Product not found" ).asException();
		}
		return product;
	}

package com.redhat.refarch.microservices.utils;

...
public class Utils
{

	private static final Map<Class<?>, PropertyDescriptor[]>
		beanDescriptors = new HashMap<Class<?>, PropertyDescriptor[]>();

	private static PropertyDescriptor[] getBeanDescriptors(Class<?> clazz)
	{
		PropertyDescriptor[] descriptors = beanDescriptors.get( clazz );
		if( descriptors == null )
		{
			try
			{
				BeanInfo beanInfo = Introspector.getBeanInfo( clazz );
				descriptors = beanInfo.getPropertyDescriptors();
				beanDescriptors.put( clazz, descriptors );
			}
			catch( IntrospectionException e )
			{
				throw new IllegalStateException( e );
			}
		}
		return descriptors;
	}

public static <T> void copy(T source, T destination, boolean skipIfNull)
{
	PropertyDescriptor[] descriptors = getBeanDescriptors(
										source.getClass() );
	for( PropertyDescriptor descriptor : descriptors )
	{
		try
		{
			if( "class".equals( descriptor.getName() ) )
			{
				//Class is not a regular JavaBeans property!
				continue;
			}
			Method readMethod = descriptor.getReadMethod();
			Method writeMethod = descriptor.getWriteMethod();
			if( readMethod == null || writeMethod == null )
			{
				//Property must be read/write to copy
				continue;
			}
			Object value = readMethod.invoke( source );
			if( value == null && skipIfNull == true )
			{
				//As per the flag, do not copy null properties
				continue;
			}
			else
			{
				writeMethod.invoke( destination, value );
			}
		}
		catch( ReflectiveOperationException e )
		{
			throw new IllegalStateException( e );
		}
	}
}

 @PUT
 @Path("/products/{sku}")
 @Consumes({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
 @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
 public Product updateProduct(@PathParam("sku") Long sku, Product product)
 {
	Product entity = getProduct( sku );
	try
	{
		//Ignore any attempt to update product SKU:
		product.setSku( sku );
		Utils.copy( product, entity, false );
		em.merge( entity );
		return product;
	}
	catch( RuntimeException e )
	{
		throw new Error( HttpURLConnection.HTTP_INTERNAL_ERROR,
										e ).asException();
	}
 }

 @Target({ElementType.METHOD})
 @Retention(RetentionPolicy.RUNTIME)
 @HttpMethod("PATCH")
 public @interface PATCH
 {
 }

 @PATCH
 @Path("/products/{sku}")
 @Consumes({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
 @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
 public Product partiallyUpdateProduct(@PathParam("sku") Long sku,
										Product product)
 {
	Product entity = getProduct( sku );
	try
	{
		//Ignore any attempt to update product SKU:
		product.setSku( sku );
		Utils.copy( product, entity, true );
		em.merge( entity );
		return product;
	}
	catch( RuntimeException e )
	{
		throw new Error( HttpURLConnection.HTTP_INTERNAL_ERROR,
										e ).asException();
	}
 }

 @DELETE
 @Path("/products/{sku}")
 @Consumes({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
 @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
 public void deleteProduct(@PathParam("sku") Long sku)
 {
	Product product = getProduct( sku );
	try
	{
		em.remove( product );
	}
	catch( RuntimeException e )
	{
		throw new Error( HttpURLConnection.HTTP_INTERNAL_ERROR,
										e ).asException();
	}
 }

Not all product requirements always neatly fit into the resource model. Model other operations in a consistent and similar way. Create a method to add a keyword to the database that can later be used to classify product.

This can be modeled after a Create resource operation:

 @Path("/keywords")
 @POST
 @Consumes({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
 @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
 public Keyword addKeyword(Keyword keyword)
 {
	try
	{
		logInfo( "Will persist keyword " + keyword );
		em.persist( keyword );
		return keyword;
	}
	catch( RuntimeException e )
	{
		logError( "Got exception " + e.getMessage() );
		throw new Error( HttpURLConnection.HTTP_INTERNAL_ERROR,
										e ).asException();
	}
 }

Once keywords have been added using the above operation, they can be used to classify a product:

 @POST
 @Path("/classify/{sku}")
 @Consumes({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
 @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
 public void classifyProduct(@PathParam("sku") Long sku,
								List<Keyword> keywords)
 {
	Product product = getProduct( sku );
	logInfo( "Asked to classify " + product + " as " + keywords );
	try
	{
		product.setKeywords( keywords );
		em.merge( product );
	}
	catch( RuntimeException e )
	{
		throw new Error( HttpURLConnection.HTTP_INTERNAL_ERROR,
										e ).asException();
	}
 }

Once again, keep calls to other methods outside the try loop so the exceptions are not caught and wrapped inside an internal server error.

To adjust product availability in response to a purchase, the service client is expected to match each product SKU with the quantity that’s been ordered. Create a java bean to represent the inventory adjustment:

package com.redhat.refarch.microservices.product.model;

public class Inventory
{

	private long sku;
	private int quantity;

	public long getSku()
	{
		return sku;
	}

	public void setSku(long sku)
	{
		this.sku = sku;
	}

	public int getQuantity()
	{
		return quantity;
	}

	public void setQuantity(int quantity)
	{
		this.quantity = quantity;
	}

	@Override
	public String toString()
	{
		return "Inventory [sku=" + sku + ", quantity=" + quantity + "]";
	}
}

Create an operation to reduce product availability based on the order quantity:

	@POST
	@Path("/reduce/")
	@Consumes({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
	@Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
	public void reduceInventory(Inventory[] inventoryAdjustment)
	{
		…
	}

Certain concurrency issues would benefit from pessimistic locking to avoid data modification while a transaction is inflight.

Some distributed databases cannot support pessimistic locking but where the database provides the required support, JPA exposes this capability through its API.

When fulfilling orders, product availability is checked against the order quantity. With the potential for concurrent requests, it is crucial to ensure that the product availability is not prone to changes until the transaction is completed and the availability is updated.

Specify the lock type while looking up the product:

Product product = em.find( Product.class, inventory.getSku(),
							   LockModeType.PESSIMISTIC_WRITE );

This results in a SELECT FOR UPDATE database query that locks the affected rows until the transaction is either committed or rolled back.

Compare the amount of inventory adjustment with the product availability and if the requested quantity exceeds available inventory, return an HTTP error code 409 with a descriptive message that states there was insufficient availability for the given product SKU:

try
{
	logInfo( "Asked to reduce inventory: " +
					Arrays.toString( inventoryAdjustment ) );
	for( Inventory inventory : inventoryAdjustment )
	{
		Product product = em.find( Product.class, inventory.getSku(),
							   LockModeType.PESSIMISTIC_WRITE );
		logInfo( "Looked up product as " + product );
		if( product == null )
		{
			throw new Error( HttpURLConnection.HTTP_NOT_FOUND,
							"Product not found" ).asException();
		}
		int availability = product.getAvailability();
		if( inventory.getQuantity() > availability )
		{
			String message = "Insufficient availability for "
									 + inventory.getSku();
			throw new Error( HttpURLConnection.HTTP_CONFLICT,
									message ).asException();
		}
		else
		{
			product.setAvailability(
						availability - inventory.getQuantity() );
			em.merge( product );
			logInfo( "Saved " + product );
		}
	}
}
catch( WebApplicationException e )
{
	throw e;
}
catch( RuntimeException e )
{
	throw new Error( HttpURLConnection.HTTP_INTERNAL_ERROR, e ).asException();
}

Create a second JBDS project called Sales to develop a second service that handles customer data maintenance and order management.

Follow the same steps that were used to create the product project, starting by Creating a Maven Project. Optionally, you can also duplicate the existing product project in JBoss Developer Studio, renaming it to sales and making the necessary changes.

Use a datasource file called sales-ds.xml with the following content:

Reference the new and correct datasource in the persistence.xml configuration file:

Follow the same instructions provided in the Persistence Entity section to create a JPA bean to represent a customer. Include JAXB annotations to allow XML serialization for this bean.

Also include a named query to find customers by their username, as they attempt to log in to the application:

 package com.redhat.refarch.microservices.sales.model;

 import javax.persistence.Entity;
 import javax.persistence.GeneratedValue;
 import javax.persistence.GenerationType;
 import javax.persistence.Id;
 import javax.persistence.NamedQuery;
 import javax.xml.bind.annotation.XmlRootElement;

 @XmlRootElement
 @Entity
 @NamedQuery(name = "Customer.findByUsername",
		  query = "SELECT c FROM Customer c WHERE c.username = :username")
 public class Customer
 {

	@Id
	@GeneratedValue(strategy = GenerationType.IDENTITY)
	private Long id;
	private String name;
	private String address;
	private String telephone;
	private String email;
	private String username;
	private String password;

	public Long getId()
	{
		return id;
	}

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

	public String getName()
	{
		return name;
	}

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

	public String getAddress()
	{
		return address;
	}

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

	public String getTelephone()
	{
		return telephone;
	}

	public void setTelephone(String telephone)
	{
		this.telephone = telephone;
	}

	public String getEmail()
	{
		return email;
	}

	public void setEmail(String email)
	{
		this.email = email;
	}

	public String getUsername()
	{
		return username;
	}

	public void setUsername(String username)
	{
		this.username = username;
	}

	public String getPassword()
	{
		return password;
	}

	public void setPassword(String password)
	{
		this.password = password;
	}

	@Override
	public String toString()
	{
		return "Customer [id=" + id + ", name=" + name +
		", address=" + address + ", telephone=" + telephone + ", email=" + email + ", username=" + username + ", password=" + password + "]";
	}
 }

Model orders as logically dependent on customers. In other words, an order can only be created by a customer and exists only as part of the customer data. Similarly, order items are parts of an order that exist within an order.

Use a Java enumeration to define the status of an order. Create two named queries for order, allowing the service to find all orders for a customer or to find customer orders that are in a given status.

Create one to many mapping between customer and order, as well as between order and order item. When creating getters for bean properties, remember to omit those fields that you do not want returned as part of the entity. Instead, use a different method name to allow retrieval of the field or relationship by the service while excluding it from the default serialization behavior. For example, use retrieveCustomer instead of getCustomer:

 package com.redhat.refarch.microservices.sales.model;

 import java.util.Date;
 import java.util.List;

 import javax.persistence.CascadeType;
 import javax.persistence.Entity;
 import javax.persistence.FetchType;
 import javax.persistence.GeneratedValue;
 import javax.persistence.GenerationType;
 import javax.persistence.Id;
 import javax.persistence.JoinColumn;
 import javax.persistence.ManyToOne;
 import javax.persistence.NamedQueries;
 import javax.persistence.NamedQuery;
 import javax.persistence.OneToMany;
 import javax.xml.bind.annotation.XmlRootElement;

 @XmlRootElement
 @Entity(name = "Orders")
 @NamedQueries({@NamedQuery(name = "Order.findByCustomer", query = "SELECT o FROM Orders o WHERE o.customer = :customer"), @NamedQuery(name = "Order.findByOrderStatus", query = "SELECT o FROM Orders o WHERE o.customer = :customer AND o.status = :status")})
 public class Order
 {

	public enum Status
	{
		Initial, InProgress, Canceled, Paid, Shipped, Completed
	}

	@Id
	@GeneratedValue(strategy = GenerationType.IDENTITY)
	private Long id;

	private Status status;
	private Long transactionNumber;
	private Date transactionDate;

	@ManyToOne(optional = false, fetch = FetchType.EAGER)
	@JoinColumn(name = "CUSTOMER_ID", referencedColumnName = "ID")
	private Customer customer;

	@OneToMany(cascade = CascadeType.ALL, fetch = FetchType.EAGER, mappedBy = "order")
	private List<OrderItem> orderItems;

	public Long getId()
	{
		return id;
	}

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

	public Status getStatus()
	{
		return status;
	}

	public void setStatus(Status status)
	{
		this.status = status;
	}

	//Avoid getter so it is not included in automatic serialization
	public Customer retrieveCustomer()
	{
		return customer;
	}

	public void setCustomer(Customer customer)
	{
		this.customer = customer;
	}

	public List<OrderItem> getOrderItems()
	{
		return orderItems;
	}

	public Long getTransactionNumber()
	{
		return transactionNumber;
	}

	public void setTransactionNumber(Long transactionNumber)
	{
		this.transactionNumber = transactionNumber;
	}

	public Date getTransactionDate()
	{
		return transactionDate;
	}

	public void setTransactionDate(Date transactionDate)
	{
		this.transactionDate = transactionDate;
	}

	@Override
	public String toString()
	{
		return "Order [id=" + id + ", status=" + status + ", transactionNumber=" + transactionNumber + ", transactionDate=" + transactionDate
				+ ", customer=" + customer + ", orderItems=" + orderItems + "]";
	}
 }

The order item is very similar and only includes the SKU of the product being ordered along with the order quantity:

 package com.redhat.refarch.microservices.sales.model;

 import javax.persistence.Entity;
 import javax.persistence.FetchType;
 import javax.persistence.GeneratedValue;
 import javax.persistence.GenerationType;
 import javax.persistence.Id;
 import javax.persistence.JoinColumn;
 import javax.persistence.ManyToOne;
 import javax.xml.bind.annotation.XmlRootElement;

 @XmlRootElement
 @Entity
 public class OrderItem
 {

	@Id
	@GeneratedValue(strategy = GenerationType.IDENTITY)
	private Long id;

	private Long sku;
	private Integer quantity;

	@ManyToOne(optional = false, fetch = FetchType.EAGER)
	@JoinColumn(name = "ORDER_ID", referencedColumnName = "ID")
	private Order order;

	public Long getId()
	{
		return id;
	}

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

	public Long getSku()
	{
		return sku;
	}

	public void setSku(Long sku)
	{
		this.sku = sku;
	}

	public Integer getQuantity()
	{
		return quantity;
	}

	public void setQuantity(Integer quantity)
	{
		this.quantity = quantity;
	}

	//Avoid getter so it is not included in automatic serialization
	public Order retrieveOrder()
	{
		return order;
	}

	public void setOrder(Order order)
	{
		this.order = order;
	}

	@Override
	public int hashCode()
	{
		final int prime = 31;
		int result = 1;
		result = prime * result + ( ( id == null ) ? 0 : id.hashCode() );
		return result;
	}

	@Override
	public boolean equals(Object obj)
	{
		if( this == obj )
			return true;
		if( obj == null )
			return false;
		if( getClass() != obj.getClass() )
			return false;
		OrderItem other = (OrderItem)obj;
		if( id == null )
		{
			if( other.id != null )
				return false;
		}
		else if( !id.equals( other.id ) )
			return false;
		return true;
	}

	@Override
	public String toString()
	{
		return "OrderItem [id=" + id + ", sku=" + sku + ", quantity=" + quantity + "]";
	}
 }

Set up the database for the sales service similar to the product service. No sample data is required for this database to use the application:

CREATE DATABASE sales;

USE sales;
CREATE USER 'sales'@'localhost' IDENTIFIED BY 'password';
GRANT USAGE ON . TO 'sales'@'localhost' IDENTIFIED BY 'password';
GRANT ALL PRIVILEGES ON sales.* to sales@localhost;

CREATE TABLE CUSTOMER (ID BIGINT NOT NULL AUTO_INCREMENT, NAME VARCHAR(255) NOT NULL, ADDRESS varchar(255), EMAIL varchar(255) NOT NULL, PASSWORD varchar(255), TELEPHONE varchar(255), USERNAME varchar(255) NOT NULL UNIQUE, PRIMARY KEY (ID)) AUTO_INCREMENT = 100001;

CREATE TABLE ORDERS (ID BIGINT NOT NULL AUTO_INCREMENT, STATUS INTEGER, TRANSACTIONDATE DATETIME, TRANSACTIONNUMBER BIGINT, CUSTOMER_ID BIGINT NOT NULL, PRIMARY KEY (ID)) AUTO_INCREMENT = 100001;

ALTER TABLE ORDERS ADD INDEX FK_ORDER_CUSTOMER (CUSTOMER_ID), add constraint FK_ORDER_CUSTOMER FOREIGN KEY (CUSTOMER_ID) REFERENCES CUSTOMER (ID);

CREATE TABLE ORDERITEM (ID BIGINT NOT NULL AUTO_INCREMENT, SKU BIGINT NOT NULL, QUANTITY INTEGER NOT NULL, ORDER_ID BIGINT NOT NULL, PRIMARY KEY (ID)) AUTO_INCREMENT = 1000001;

ALTER TABLE ORDERITEM ADD INDEX FK_ORDERITEM_ORDER (ORDER_ID), add constraint FK_ORDERITEM_ORDER FOREIGN KEY (ORDER_ID) REFERENCES ORDERS (ID);

Database constraints provide further assurance that data integrity will be preserved, even if JPA is bypassed when entering or modifying data.

Copy the same com.redhat.refarch.microservices.utils.Utils class over to this project to use for full and partial updates to entities. The com.redhat.refarch.microservices.sales.model.Error class is also reused to map various business and runtime exceptions to RESTful error responses.

Create the sales service similar to the previously created RESTful Service for product:

 package com.redhat.refarch.microservices.sales.service;

 import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 import java.net.HttpURLConnection;
 import java.util.List;
 import java.util.logging.Level;
 import java.util.logging.Logger;
 import javax.ejb.LocalBean;
 import javax.ejb.Stateless;
 import javax.persistence.EntityManager;
 import javax.persistence.NoResultException;
 import javax.persistence.PersistenceContext;
 import javax.persistence.TypedQuery;
 import javax.ws.rs.Consumes;
 import javax.ws.rs.DELETE;
 import javax.ws.rs.GET;
 import javax.ws.rs.HttpMethod;
 import javax.ws.rs.POST;
 import javax.ws.rs.PUT;
 import javax.ws.rs.Path;
 import javax.ws.rs.PathParam;
 import javax.ws.rs.Produces;
 import javax.ws.rs.QueryParam;
 import javax.ws.rs.WebApplicationException;
 import com.redhat.refarch.microservices.sales.model.Customer;
 import com.redhat.refarch.microservices.sales.model.Error;
 import com.redhat.refarch.microservices.sales.model.Order;
 import com.redhat.refarch.microservices.sales.model.Order.Status;
 import com.redhat.refarch.microservices.sales.model.OrderItem;
 import com.redhat.refarch.microservices.utils.Utils;

 @Stateless
 @LocalBean
 @Path("/")
 public class SalesService
 {
	private Logger logger = Logger.getLogger( getClass().getName() );

	@PersistenceContext
	private EntityManager em;

Follow the same principles for RESTful Resource API design to create CRUD operations for customer. Only allow the search for customers based on their username:

	@POST
	@Path("/customers")
	@Consumes({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
	@Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
	public Customer addCustomer(Customer customer)
	{
		try
		{
			em.persist( customer );
			return customer;
		}
		catch( RuntimeException e )
		{
			throw new Error( HttpURLConnection.HTTP_INTERNAL_ERROR,
										e ).asException();
		}
	}

	@GET
	@Path("/customers")
	@Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
	public Customer getCustomer(@QueryParam("username") String username)
	{
		try
		{
			TypedQuery<Customer> query = em.createNamedQuery(
					 "Customer.findByUsername", Customer.class );
			Customer customer = query.setParameter(
						"username", username ).getSingleResult();
			logInfo( "Customer for " + username + ": " + customer );
			return customer;
		}
		catch( NoResultException e )
		{
			throw new Error( HttpURLConnection.HTTP_NOT_FOUND,
							"Customer not found" ).asException();
		}
		catch( RuntimeException e )
		{
			throw new Error( HttpURLConnection.HTTP_INTERNAL_ERROR,
										e ).asException();
		}
	}
	@GET
	@Path("/customers/{id}")
	@Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
	public Customer getCustomer(@PathParam("id") Long id)
	{
		try
		{
			logInfo( "Customer Id is " + id );
			Customer customer = em.find( Customer.class, id );
			logInfo( "Customer with ID " + id + " is " + customer );
			if( customer == null )
			{
				throw new Error( HttpURLConnection.HTTP_NOT_FOUND,
							"Customer not found" ).asException();
			}
			return customer;
		}
		catch( WebApplicationException e )
		{
			throw e;
		}
		catch( RuntimeException e )
		{
			throw new Error( HttpURLConnection.HTTP_INTERNAL_ERROR,
										e ).asException();
		}
	}

	@PUT
	@Path("/customers/{id}")
	@Consumes({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
	@Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
	public Customer updateCustomer(@PathParam("id") Long id,
										Customer customer)
	{
		Customer entity = getCustomer( id );
		try
		{
			//Ignore any attempt to update customer Id:
			customer.setId( id );
			Utils.copy( customer, entity, false );
			em.merge( entity );
			return entity;
		}
		catch( RuntimeException e )
		{
			throw new Error( HttpURLConnection.HTTP_INTERNAL_ERROR,
										e ).asException();
		}
	}
	@PATCH
	@Path("/customers/{id}")
	@Consumes({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
	@Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
	public Customer partiallyUpdateCustomer(@PathParam("id") Long id,
										Customer customer)
	{
		Customer entity = getCustomer( id );
		try
		{
			//Ignore any attempt to update customer Id:
			customer.setId( id );
			Utils.copy( customer, entity, true );
			em.merge( entity );
			return entity;
		}
		catch( RuntimeException e )
		{
			throw new Error( HttpURLConnection.HTTP_INTERNAL_ERROR,
										e ).asException();
		}
	}

	@DELETE
	@Path("/customers/{id}")
	@Consumes({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
	@Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
	public void deleteCustomer(@PathParam("id") Long id)
	{
		Customer entity = getCustomer( id );
		try
		{
			em.remove( entity );
		}
		catch( RuntimeException e )
		{
			throw new Error( HttpURLConnection.HTTP_INTERNAL_ERROR,
										e ).asException();
		}
	}

Orders are also modeled as resources, as described in the section on Resource API design, but an order only exists in the context of a customer and the REST API can reflect this fact by using the path to the parent customer as the relative context for the order.

The path for each REST operation therefore follows the same pattern, but is preceded by /customers/{customerId}:

	@POST
	@Path("/customers/{customerId}/orders")
	@Consumes({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
	@Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
	public Order addOrder(@PathParam("customerId") Long customerId, Order order)
	{
		Customer customer = getCustomer( customerId );
		order.setCustomer( customer );
		try
		{
			em.persist( order );
			return order;
		}
		catch( RuntimeException e )
		{
			throw new Error( HttpURLConnection.HTTP_INTERNAL_ERROR,
										e ).asException();
		}
	}

	@GET
	@Path("/customers/{customerId}/orders")
	@Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
	public List<Order> getOrders(@PathParam("customerId") Long customerId, @QueryParam("status") Status status)
	{
		logInfo( "getOrders(" + customerId + ", " + status + ")" );
		Customer customer = getCustomer( customerId );
		try
		{
			TypedQuery<Order> query;
			if( status == null )
			{
				query = em.createNamedQuery( "Order.findByCustomer",
											Order.class );
			}
			else
			{
				query = em.createNamedQuery( "Order.findByOrderStatus",
											Order.class );
				query.setParameter( "status", status );
			}
			query.setParameter( "customer", customer );
			List<Order> orders = query.getResultList();
			logInfo( "Orders retrieved as " + orders );
			return orders;
		}
		catch( RuntimeException e )
		{
			throw new Error( HttpURLConnection.HTTP_INTERNAL_ERROR,
										e ).asException();
		}
	}

	@GET
	@Path("/customers/{customerId}/orders/{orderId}")
	@Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
	public Order getOrder(@PathParam("customerId") Long customerId,
							@PathParam("orderId") Long orderId)
	{
		try
		{
			Order order = em.find( Order.class, orderId );
			logInfo( "Order retrieved as " + order );
			if( order != null && customerId.equals(
							order.retrieveCustomer().getId() ) )
			{
				return order;
			}
			else
			{
				throw new Error( HttpURLConnection.HTTP_NOT_FOUND,
							"Order not found" ).asException();
			}
		}
		catch( WebApplicationException e )
		{
			throw e;
		}
		catch( RuntimeException e )
		{
			throw new Error( HttpURLConnection.HTTP_INTERNAL_ERROR,
										e ).asException();
		}
	}

	@PUT
	@Path("/customers/{customerId}/orders/{orderId}")
	@Consumes({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
	@Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
	public Order updateOrder(@PathParam("customerId") Long customerId, @PathParam("orderId") Long orderId, Order order)
	{
		Order entity = getOrder( customerId, orderId );
		try
		{
			//Ignore any attempt to update order Id:
			order.setId( orderId );
			Utils.copy( order, entity, false );
			em.merge( entity );
			return entity;
		}
		catch( RuntimeException e )
		{
			throw new Error( HttpURLConnection.HTTP_INTERNAL_ERROR,
										e ).asException();
		}
	}

	@PATCH
	@Path("/customers/{customerId}/orders/{orderId}")
	@Consumes({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
	@Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
	public Order partiallyUpdateOrder( @PathParam("customerId") Long customerId, @PathParam("orderId") Long orderId, Order order)
	{
		Order entity = getOrder( customerId, orderId );
		try
		{
			//Ignore any attempt to update order Id:
			order.setId( orderId );
			Utils.copy( order, entity, true );
			em.merge( entity );
			return entity;
		}
		catch( RuntimeException e )
		{
			throw new Error( HttpURLConnection.HTTP_INTERNAL_ERROR,
										e ).asException();
		}
	}

	@DELETE
	@Path("/customers/{customerId}/orders/{orderId}")
	public void deleteOrder(@PathParam("customerId") Long customerId,
							@PathParam("orderId") Long orderId)
	{
		Order entity = getOrder( customerId, orderId );
		try
		{
			em.remove( entity );
		}
		catch( RuntimeException e )
		{
			throw new Error( HttpURLConnection.HTTP_INTERNAL_ERROR,
										e ).asException();
		}
	}

The order item is similarly treated as a resource underneath order. The path for its operations are therefore preceded by /customers/{customerId}/orders/{orderId}/:

	@POST
	@Path("/customers/{customerId}/orders/{orderId}/orderItems")
	@Consumes({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
	@Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
	public OrderItem addOrderItem(@PathParam("customerId") Long customerId,
			@PathParam("orderId") Long orderId, OrderItem orderItem)
	{
		Order order = getOrder( customerId, orderId );
		orderItem.setOrder( order );
		try
		{
			em.persist( orderItem );
			return orderItem;
		}
		catch( RuntimeException e )
		{
			throw new Error( HttpURLConnection.HTTP_INTERNAL_ERROR, e ).asException();
		}
	}

	@GET
	@Path("/customers/{customerId}/orders/{orderId}/orderItems")
	@Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
	public List<OrderItem> getOrderItems(@PathParam("customerId") Long customerId, @PathParam("orderId") Long orderId)
	{
		Order order = getOrder( customerId, orderId );
		if( order == null )
		{
			throw new Error( HttpURLConnection.HTTP_NOT_FOUND, "Order not found" ).asException();
		}
		try
		{
			return order.getOrderItems();
		}
		catch( RuntimeException e )
		{
			throw new Error( HttpURLConnection.HTTP_INTERNAL_ERROR, e ).asException();
		}
	}

	@GET
	@Path("/customers/{customerId}/orders/{orderId}/orderItems/{orderItemId}")
	@Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
	public OrderItem getOrderItem(@PathParam("customerId") Long customerId,
			@PathParam("orderId") Long orderId,
			@PathParam("orderItemId") Long orderItemId)
	{
		try
		{
			OrderItem orderItem = em.find( OrderItem.class,
											orderItemId );
			if( orderItem != null && orderId.equals( orderItem.retrieveOrder().getId() )
			&& customerId.equals( orderItem.retrieveOrder().retrieveCustomer().getId() ) )
			{
				return orderItem;
			}
			else
			{
				throw new Error( HttpURLConnection.HTTP_NOT_FOUND,
												"Order Item not found" ).asException();
			}
		}
		catch( WebApplicationException e )
		{
			throw e;
		}
		catch( RuntimeException e )
		{
			throw new Error( HttpURLConnection.HTTP_INTERNAL_ERROR, e ).asException();
		}
	}

	@PUT
	@Path("/customers/{customerId}/orders/{orderId}/orderItems/{orderItemId}")
	@Consumes({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
	@Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
	public OrderItem updateOrderItem(
					@PathParam("customerId") Long customerId,
					@PathParam("orderId") Long orderId,
					@PathParam("orderItemId") Long orderItemId, OrderItem orderItem)
	{
		OrderItem entity = getOrderItem( customerId, orderId, orderItemId );
		try
		{
			//Ignore any attempt to update order item Id:
			orderItem.setId( orderItemId );
			Utils.copy( orderItem, entity, false );
			em.merge( entity );
			return entity;
		}
		catch( RuntimeException e )
		{
			throw new Error( HttpURLConnection.HTTP_INTERNAL_ERROR, e ).asException();
		}
	}

	@PATCH
	@Path("/customers/{customerId}/orders/{orderId}/orderItems/{orderItemId}")
	@Consumes({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
	@Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
	public OrderItem partiallyUpdateOrderItem(
						@PathParam("customerId") Long customerId,
						@PathParam("orderId") Long orderId,
						@PathParam("orderItemId") Long orderItemId, OrderItem orderItem)
	{
		OrderItem entity = getOrderItem( customerId, orderId, orderItemId );
		try
		{
			//Ignore any attempt to update order item Id:
			orderItem.setId( orderItemId );
			Utils.copy( orderItem, entity, true );
			em.merge( entity );
			return entity;
		}
		catch( RuntimeException e )
		{
			throw new Error( HttpURLConnection.HTTP_INTERNAL_ERROR, e ).asException();
		}
	}

	@DELETE
	@Path("/customers/{customerId}/orders/{orderId}/orderItems/{orderItemId}")
	public void deleteOrderItem(@PathParam("customerId") Long customerId,
			@PathParam("orderId") Long orderId,
			@PathParam("orderItemId") Long orderItemId)
	{
		Order order = getOrder( customerId, orderId );
		OrderItem entity = getOrderItem( customerId, orderId, orderItemId );
		try
		{
			em.remove( entity );
			order.getOrderItems().remove( entity );
			em.merge( order );
		}
		catch( RuntimeException e )
		{
			throw new Error( HttpURLConnection.HTTP_INTERNAL_ERROR, e ).asException();
		}
	}

The only other operation in the sales service is an authenticate method that verifies the customer’s credentials:

	@POST
	@Path("/authenticate")
	@Consumes({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
	@Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
	public Customer authenticate(Customer customer)
	{
		logInfo( "Asked to authenticate " + customer );
		Customer response = getCustomer( customer.getUsername() );
		try
		{
			if( response.getPassword().equals( customer.getPassword() ) == false )
			{
				throw new WebApplicationException( HttpURLConnection.HTTP_UNAUTHORIZED );
			}
			return response;
		}
		catch( WebApplicationException e )
		{
			throw e;
		}
		catch( RuntimeException e )
		{
			throw new Error( HttpURLConnection.HTTP_INTERNAL_ERROR, e ).asException();
		}
	}

The security aspect of this reference application is only for demonstration purposes. This authentication example is not intended to provide a reference of security best practices and the security aspect of these uses cases is beyond the scope of this reference architecture.

This service class also uses the JDK logging framework and declares the PATCH annotation for partial updates:

	private void logInfo(String message)
	{
		logger.log( Level.INFO, message );
	}

	@Target({ElementType.METHOD})
	@Retention(RetentionPolicy.RUNTIME)
	@HttpMethod("PATCH")
	public @interface PATCH
	{
	}
}

This reference architecture assumes the existence of a third microservice to process credit card transactions. This functionality is provided by an external system with a legacy interface, wrapped by a microservice that exposes a REST API.

Once again, either create a new JBDS project called Billing and follow the same steps that were used to create the product project, or optionally, you can also duplicate the existing product project in JBoss Developer Studio, renaming it to billing and making the necessary changes. This project does not require database and JPA dependencies.

The service models its request as a transaction object:

 @XmlRootElement
 public class Transaction
 {

	private Long creditCardNumber;
	private Integer expMonth;
	private Integer expYear;
	private Integer verificationCode;
	private String billingAddress;
	private String customerName;
	private Long orderNumber;
	private Double amount;

 ...

A result type is defined to provide a response to a transaction processing request:

 @XmlRootElement
 public class Result
 {

	public enum Status
	{
		SUCCESS, FAILURE
	}

	private Status status;
	private String name;
	private Long orderNumber;
	private Date transactionDate;
	private Integer transactionNumber;

 ...

The main operation of the billing service receives a transaction request, processes it and depending on the outcome, returns the appropriate result. The legacy credit card processing system can be slow and consumes resources on a different thread or even different system, so this service is a prime candidate for asynchronous processing. The process operation injects an AsyncResponse and uses the executor service to call a synchronous operation on a different thread:

@Path("/")
public class BillingService {

	private ManagedExecutorService executorService;

	private Logger logger = Logger.getLogger( getClass().getName() );

	private static final Random random = new Random();

	@POST
	@Path("/process")
	@Consumes({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
	@Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
	public void process(final Transaction transaction, final @Suspended AsyncResponse asyncResponse) {

		Runnable runnable = () -> {
			try {
				final long sleep = 5000;
				logInfo( "Will simulate credit card processing for " + sleep + " milliseconds" );
				Thread.sleep( sleep );
				Result result = processSync( transaction );
				asyncResponse.resume( result );
			} catch (Exception e) {
				asyncResponse.resume( e );
			}
		};
		getExecutorService().execute( runnable );
	}

This service simulates processing delays by putting the thread to sleep for 5 seconds. After waking up, the asynchronous response object is used to return the result.

For this mock-up service, the success of the credit card transaction only depends on the credit card having a future expiration date. The transaction number is randomly generated as a 7-digit number and the transaction date matches the time of the request.

	private Result processSync(Transaction transaction) {
		Result result = new Result();
		result.setName( transaction.getCustomerName() );
		result.setOrderNumber( transaction.getOrderNumber() );
		logInfo( "Asked to process credit card transaction: " + transaction );
		Calendar now = Calendar.getInstance();
		Calendar calendar = Calendar.getInstance();
		calendar.clear();
		calendar.set( transaction.getExpYear(), transaction.getExpMonth(), 1 );
		if( calendar.after( now ) ) {
			result.setTransactionNumber( (long)(random.nextInt( 9000000 ) + 1000000) );
			result.setTransactionDate( now.getTime() );
			result.setStatus( Status.SUCCESS );
		} else {
			result.setStatus( Status.FAILURE );
		}
		return result;
	}

Another operation is provided to reverse the transaction charge:

 @POST
 @Path("/refund/{transactionNumber}")
 @Consumes({"/"})
 @Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
 public void refund(@PathParam("transactionNumber") int transactionNumber)
 {
	logInfo( "Asked to refund credit card transaction: " + transactionNumber );

The billing service uses a Java EE 7 managed executor service to perform the actual credit card processing on a separate managed thread. To use this library in your project, first declare the necessary maven dependency:

This allows ManagedExecutorService to be imported:

	private ManagedExecutorService executorService;

In certain circumstances, resource injection may be used to instantiate the executor service. However in this case and in a Servlet that has not been added to the ServletContext, simply use a JNDI lookup:

private Executor getExecutorService() {
	if( executorService == null ) {
		try {
			executorService = InitialContext.doLookup( "java:comp/DefaultManagedExecutorService" );
		} catch (NamingException e) {
			throw new WebApplicationException( e );
		}
	}
	return executorService;
}

While this example uses a default and generic executor service, a custom managed executor service may be defined and configured for specific requirements. Refer to the official Red Hat documentation on this topic for further details.