RestEasy: JAX-RS web service for uploading/downloading Excel file + Java client

September 30, 2014 SJ JBoss RestEasy 0

In this article, we will learn and implement JAX-RS Restful web service which is exposed to upload/download EXCEL file

JBoss RestEasy is a JAX-RS implementation for developing Restful web service in java. Once developed, it isn’t restricted to deploy only in JBoss Application Server but you can deploy in any other server like Apache Tomcat, Glassfish, Oracle Weblogic, etc

Download

  • Annotate download Excel method with @Produces(“application/vnd.ms-excel”)
  • Set “Content-Disposition” in the ResponseBuilder to allow downloading users to select path to download Excel file
  • Finally, build() the ResponseBuilder and return Response object with “download success” message

Upload

  • Annotate upload method with @Consumes(“multipart/form-data”)
  • Get MultipartFormDataInputand and process inputParts to get headers and inputstreams
  • Finally, write the steams to the upload file server using basic file handling operations
  • Return “upload success” message within Response object

Annotation Used

  • @Path (ws.rs.Path)
  • @GET (ws.rs.GET)
  • @POST (ws.rs.POST)
  • @Consumes (ws.rs.Consumes)
  • @Produces (ws.rs.Produces)
  • MediaType (ws.rs.core.MediaType)

Technology Used

  • Java 1.7
  • Eclipse Luna IDE
  • RestEasy-3.0.8.Final
  • Apache Maven 3.2.1
  • Apache Tomcat 7.0.54
  • JBoss Application Server 7.1.1.Final

Mavenize or download required jars

Add RestEasy-3.0.8.Final dependencies to pom.xml

	<properties>
		<resteasy.version>3.0.8.Final</resteasy.version>
		<resteasy.scope>compile</resteasy.scope> 		<!-- compile(Tomcat) / provided(JBoss) -->
		<compileSource>1.7</compileSource>
		<maven.compiler.target>1.7</maven.compiler.target>
		<maven.compiler.source>1.7</maven.compiler.source>
		<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
	</properties>

	<dependencies>
		<!-- RESTEasy JAX RS Implementation -->
		<dependency>
			<groupId>org.jboss.resteasy</groupId>
			<artifactId>resteasy-jaxrs</artifactId>
			<version>${resteasy.version}</version>
			<scope>${resteasy.scope}</scope>
		</dependency>

		<!-- Resteasy Multipart Provider -->
		<dependency>
			<groupId>org.jboss.resteasy</groupId>
			<artifactId>resteasy-multipart-provider</artifactId>
			<version>${resteasy.version}</version>
			<scope>${resteasy.scope}</scope>
		</dependency>

		<!-- Resteasy Servlet Container Initializer -->
		<dependency>
			<groupId>org.jboss.resteasy</groupId>
			<artifactId>resteasy-servlet-initializer</artifactId>
			<version>${resteasy.version}</version>
			<scope>${resteasy.scope}</scope>
		</dependency>

		<!-- RESTEasy JAX RS Client -->
		<dependency>
			<groupId>org.jboss.resteasy</groupId>
			<artifactId>resteasy-client</artifactId>
			<version>${resteasy.version}</version>
			<scope>${resteasy.scope}</scope>
		</dependency>
	</dependencies>

Folks who aren’t familiar with Maven concepts or don’t require maven for their project, can download the below jars individually from the central repository or maven repository and download directly from Spring site include them in the classpath

Directory Structure

Before moving on, let us understand the directory/package structure once you create project in Eclipse IDE

Maven has to follow certain directory structure

  • src/test/java –> test related files, mostly JUnit test cases
  • src/main/java –> create java source files under this folder
  • src/main/resources –> all configuration files placed here
  • src/test/resources –> all test related configuration files placed here
  • Maven Dependencies or Referenced Libraries –> includes jars in the classpath
  • WEB-INF under webapp –> stores web.xml & other configuration files related to web application

Project Structure (Package Explorer view in Eclipse)

1_RestEasy-UP-DOWN-Excel-File_Project_Structure_In_Eclipse

Jars Libraries Used in the Project (Maven Dependencies)

2_RestEasy-UP-DOWN-Text-File_Jars_In_Classpath

Web application

For any web application, entry point is web.xml which describes how the incoming http requests are served / processed. Further, it describes about the global-context and local-context param (i.e.; <context-param> & <init-param>) for loading files particular to project requirements & contains respective listener

With this introduction, we will understand how we configured web.xml for RestEasy JAX-RS Restful web service

web.xml (the entry point –> under WEB-INF)

This web.xml file describes,

  • Like any JEE web framework register jboss.resteasy.plugins.server.servlet.HttpServletDispatcher with servlet container
  • http requests with URL pattern “/resteasy/*” will be sent to the registered servlet called “ws.rs.core.Application” i.e.; HttpServletDispatcher (org.jboss.resteasy.plugins.server.servlet.HttpServletDispatcher)
  • set servlet.mapping.prefix as <context-param>, if your servlet-mapping has a url-pattern anything other than “/*”. In this example, set “/resteasy”
  • if not set, then you will end up with 404 not found error
  • set resources as <param-name> with comma delimited list of fully qualified JAX-RS resource class names you want to register as <param-value> using global <context-param>
  • <welcome-file-list> files under this tag is the start-up page

web.xml

<?xml version="1.0" encoding="UTF-8"?>
<web-app version="3.0" xmlns="http://java.sun.com/xml/ns/javaee"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd">

	<display-name>RestEasy-UP-DOWN-Excel-File</display-name>

	<!-- RestEasy resource registering -->
	<context-param>
		<param-name>resteasy.resources</param-name>
		<param-value>com.resteasy.series.upload.download.service.FileServiceImpl</param-value>
	</context-param>

	<!-- RestEasy Servlet -->
	<servlet>
		<servlet-name>javax.ws.rs.core.Application</servlet-name>
		<servlet-class>org.jboss.resteasy.plugins.server.servlet.HttpServletDispatcher</servlet-class>
	</servlet>

	<servlet-mapping>
		<servlet-name>javax.ws.rs.core.Application</servlet-name>
		<url-pattern>/resteasy/*</url-pattern>
	</servlet-mapping>

	<!-- this is mandatory, if url-pattern is other than /* -->
	<context-param>
		<param-name>resteasy.servlet.mapping.prefix</param-name>
		<param-value>/resteasy</param-value>
	</context-param>

	<!-- welcome file -->
	<welcome-file-list>
		<welcome-file>index.html</welcome-file>
	</welcome-file-list>
</web-app>

Let’s see coding in action

 

URL Pattern

Http url for any common web application is http://<server>:<port>/<root-context>/<from_here_application_specific_path>

In our example, we are going to deploy the war into Tomcat 7.0 server so our server and port are localhost and 8080 respectively. Context root is the project name i.e.; RestEasy-UP-DOWN-Excel-File. Initial path for this application is http://localhost:8080/RestEasy-UP-DOWN-Excel-File

We have configured “/resteasy/*” as url-pattern for the “javax.ws.rs.core.Application” servlet in web.xml and at interface-level (or say class-level) path configured is “/fileservice” using @Path annotation. Next respective path for each method annotated with @Path (method-level)

File Service interface

File service exposes two public methods one for downloading Excel file and another for uploading file

Download Excel file method annotated with @Produces(“application/vnd.ms-excel”) and upload file method annotated with @Consumes(“multipart/form-data”)

NOTE: It’s always a good programming practice to do code-to-interface and have its implementation separately

IFileService.java

package com.resteasy.series.upload.download.service;

import javax.ws.rs.Consumes;
import javax.ws.rs.GET;
import javax.ws.rs.POST;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response;

import org.jboss.resteasy.plugins.providers.multipart.MultipartFormDataInput;

@Path("/fileservice")
public interface IFileService {

	// http://localhost:8080/RestEasy-UP-DOWN-Excel-File/resteasy/fileservice/download/xls  - Tomcat 7.0.x
	// http://localhost:9090/RestEasy-UP-DOWN-Excel-File/resteasy/fileservice/download/xls  - JBoss AS7
	@GET
	@Path("/download/xls")
	@Produces("application/vnd.ms-excel")
	public Response downloadExcelFile();

	// http://localhost:8080/RestEasy-UP-DOWN-Excel-File/resteasy/fileservice/upload/xls  - Tomcat 7.0.x
	// http://localhost:9090/RestEasy-UP-DOWN-Excel-File/resteasy/fileservice/upload/xls  - JBoss AS7
	@POST
	@Path("/upload/xls")
	@Consumes(MediaType.MULTIPART_FORM_DATA)
	public Response uploadExcelFile(MultipartFormDataInput multipartFormDataInput);
}

File Service implementation

Implements above interface

Download

It’s quite straightforward, constructing file object supplying path location for the .xlsx file to be downloaded and setting this file object in ResponseBuilder and returning Response object

Upload

Iterate through each inputParts extracted from multiPartFormDataInput & get inputstreams and write to the UPLOAD_FILE_SERVER using simple file handling operations

FileServiceImpl.java

package com.resteasy.series.upload.download.service;

import java.io.File;
import java.io.FileOutputStream;
import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.util.List;
import java.util.Map;

import javax.ws.rs.core.MultivaluedMap;
import javax.ws.rs.core.Response;
import javax.ws.rs.core.Response.ResponseBuilder;

import org.jboss.resteasy.plugins.providers.multipart.InputPart;
import org.jboss.resteasy.plugins.providers.multipart.MultipartFormDataInput;

public class FileServiceImpl implements IFileService {

	public static final String UPLOAD_FILE_SERVER = "D:/Demo/upload/";

	public Response downloadExcelFile() {

		// set file (and path) to be download
		File file = new File("D:/Demo/download/Sample.xlsx");

		ResponseBuilder responseBuilder = Response.ok((Object) file);
		responseBuilder.header("Content-Disposition", "attachment; filename=\"MyExcelFile.xlsx\"");
		return responseBuilder.build();
	}

	public Response uploadExcelFile(MultipartFormDataInput multipartFormDataInput) {

		// local variables
		MultivaluedMap<String, String> multivaluedMap = null;
		String fileName = null;
		InputStream inputStream = null;
		String uploadFilePath = null;

		try {
			Map<String, List<InputPart>> map = multipartFormDataInput.getFormDataMap();
			List<InputPart> lstInputPart = map.get("uploadedFile");

			for(InputPart inputPart : lstInputPart){

				// get filename to be uploaded
				multivaluedMap = inputPart.getHeaders();
				fileName = getFileName(multivaluedMap);

				if(null != fileName && !"".equalsIgnoreCase(fileName)){

					// write & upload file to UPLOAD_FILE_SERVER
					inputStream = inputPart.getBody(InputStream.class,null);
					uploadFilePath = writeToFileServer(inputStream, fileName);

					// close the stream
					inputStream.close();
				}
			}
		}
		catch(IOException ioe){
			ioe.printStackTrace();
		}
		finally{
			// release resources, if any
		}
		return Response.ok("File uploaded successfully at " + uploadFilePath).build();
	}

	/**
	 *
	 * @param inputStream
	 * @param fileName
	 * @throws IOException
	 */
	private String writeToFileServer(InputStream inputStream, String fileName) throws IOException {

		OutputStream outputStream = null;
		String qualifiedUploadFilePath = UPLOAD_FILE_SERVER + fileName;

		try {
			outputStream = new FileOutputStream(new File(qualifiedUploadFilePath));
			int read = 0;
			byte[] bytes = new byte[1024];
			while ((read = inputStream.read(bytes)) != -1) {
				outputStream.write(bytes, 0, read);
			}
			outputStream.flush();
		}
		catch (IOException ioe) {
			ioe.printStackTrace();
		}
		finally{
			//release resource, if any
			outputStream.close();
		}
		return qualifiedUploadFilePath;
	}

	/**
	 *
	 * @param multivaluedMap
	 * @return
	 */
	private String getFileName(MultivaluedMap<String, String> multivaluedMap) {

		String[] contentDisposition = multivaluedMap.getFirst("Content-Disposition").split(";");

		for (String filename : contentDisposition) {

			if ((filename.trim().startsWith("filename"))) {
				String[] name = filename.split("=");
				String exactFileName = name[1].trim().replaceAll("\"", "");
				return exactFileName;
			}
		}
		return "UnknownFile";
	}
}

 

View Technologies

 

<table> element within <form> tag, on click of “Upload File” button invokes upload file service method which is configured in the action attribute

uploadXlsFile.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>RestEasy : File Upload</title>
</head>
<body>
	<center>
		<b>RestEasy : JAX-RS Restful web service Learning</b>
		<h4>Uploading files using JAX-RS Restful web service</h4>
		<div
			style="width: 400px; border: 1px solid blue; padding: 20px; text-align: center;">

			<form method="post" action="resteasy/fileservice/upload/xls"
				enctype="multipart/form-data">
				<table align="center" border="1" bordercolor="black" cellpadding="0"
					cellspacing="0">
					<tr>
						<td>Select File :</td>
						<td><input type="file" name="uploadedFile" size="100" /></td>
					</tr>
					<tr>
						<td><input type="submit" value="Upload File" /></td>
						<td><input type="reset" value="Reset" /></td>
					</tr>
				</table>
			</form>
		</div>
	</center>
</body>
</html>

 

Deployment

  • Run maven command to build the war: mvn clean install (use command prompt or integrated maven in eclipse IDE
  • Copy the war file from the target folder
  • Paste it into apache tomcat (webapps folder)
  • Start the tomcat server

Test the service !!

 

Testing

There are many ways to do testing

  • Access html page from web browser
  • Copy the URL of GET service into web browser
  • Advanced REST client from Google Chrome
  • Rest client in Mozilla Firefox Add On
  • Write your own client for example, Java client using improved CloseableHttpClient from Apache
  • JDK’s in-built classes like HttpURLConnection
  • Using Client, WebTarget from core JAX-RS classes javax.ws.rs.client
  • Using ResteasyClient, ResteasyWebTarget and Response classes from JBoss package org.jboss.resteasy.client
  • Using ClientRequest and ClientResponse classes from JBoss package org.jboss.resteasy.client

1. HTML page in web browser

1.1 upload file

Enter URL: http://localhost:8080/RestEasy-UP-DOWN-Excel-File/uploadXlsFile.html
And select excel file using file chooser
Click “Upload File”

3_RestEasy-UP-DOWN-Excel-File_upload_web_client

Result in web browser: upload success

4_RestEasy-UP-DOWN-Excel-File_upload_web_client_success

1.2 download excel file

Enter URL: http://localhost:8080/RestEasy-UP-DOWN-Excel-File/resteasy/fileservice/download/xls into web browser
Allows downloading users to open/save excel file

5_RestEasy-UP-DOWN-Excel-File_download_firefox

 

2. Java client (RestEasy)

 

2.1 Upload excel file

Uses ResteasyClient, ResteasyWebTarget and Response classes from JBoss RestEasy package org.jboss.resteasy.client.jaxrs for invoking Restful web service to upload .xlsx file

TestUploadFileService.java

package test.resteasy.series.upload.download.service;

import java.io.File;
import java.io.FileInputStream;

import javax.ws.rs.client.Entity;
import javax.ws.rs.core.GenericEntity;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response;

import org.jboss.resteasy.client.jaxrs.ResteasyClient;
import org.jboss.resteasy.client.jaxrs.ResteasyClientBuilder;
import org.jboss.resteasy.client.jaxrs.ResteasyWebTarget;
import org.jboss.resteasy.plugins.providers.multipart.MultipartFormDataOutput;

public class TestUploadFileService {

	public static void main(String []args) throws Exception {

		// set file upload parameters
		String httpURL = "http://localhost:8080/RestEasy-UP-DOWN-Excel-File/resteasy/fileservice/upload/xls";
		File filePath = new File("D:/Demo/download/Sample.xlsx");
		String filename = "MyExcelSample.xlsx";

		// invoke file upload service using above parameters
		String responseString = testUploadService(httpURL, filePath, filename);
		System.out.println("responseString : " + responseString);
	}

	/**
	 * using ResteasyClient, ResteasyWebTarget and Response classes from org.jboss.resteasy.client
	 * @param httpURL
	 * @param requestString
	 * @return
	 */
	public static String testUploadService(String httpURL, File filePath, String filename)  throws Exception {

		// local variables
		ResteasyClient resteasyClient = null;
		ResteasyWebTarget resteasyWebTarget = null;
		MultipartFormDataOutput multipartFormDataOutput = null;
		GenericEntity<MultipartFormDataOutput> genericEntity = null;
		Response response = null;
		int responseCode;
		String responseMessageFromServer = null;
		String responseString = null;

		try{
			resteasyClient = new ResteasyClientBuilder().build();
			resteasyWebTarget = resteasyClient.target(httpURL);
			resteasyWebTarget.property("Content-Type", MediaType.MULTIPART_FORM_DATA);

			// set file upload values
			multipartFormDataOutput = new MultipartFormDataOutput();
			multipartFormDataOutput.addFormData("uploadedFile", new FileInputStream(filePath), MediaType.MULTIPART_FORM_DATA_TYPE, filename);
			genericEntity = new GenericEntity<MultipartFormDataOutput>(multipartFormDataOutput) { };

			// invoke service
			response = resteasyWebTarget.request().post(Entity.entity(genericEntity, MediaType.MULTIPART_FORM_DATA));

			// get response code
			responseCode = response.getStatus();
			System.out.println("Response code: " + responseCode);

			if (response.getStatus() != 200) {
				throw new RuntimeException("Failed with HTTP error code : " + responseCode);
			}

			// get response message
			responseMessageFromServer = response.getStatusInfo().getReasonPhrase();
			System.out.println("ResponseMessageFromServer: " + responseMessageFromServer);

			// get response string
			responseString = response.readEntity(String.class);
		}
		catch(Exception ex){
			ex.printStackTrace();
		}
		finally{
			// release resources, if any
			response.close();
		}
		return responseString;
	}
}

Output in console (upload .xlsx file)

Response code: 200
ResponseMessageFromServer: OK
responseString : File uploaded successfully at D:/Demo/upload/MyExcelSample.xlsx

 

2.2 Download excel file

Uses ResteasyClient, ResteasyWebTarget and Response classes from org.jboss.resteasy.client.jaxrs to invoke Restful web service to download .xlsx file

TestDownloadFileService.java

package test.resteasy.series.upload.download.service;

import java.io.FileOutputStream;
import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;

import javax.ws.rs.core.Response;

import org.jboss.resteasy.client.jaxrs.ResteasyClient;
import org.jboss.resteasy.client.jaxrs.ResteasyClientBuilder;
import org.jboss.resteasy.client.jaxrs.ResteasyWebTarget;

public class TestDownloadFileService {

	public static final String DOWNLOAD_FILE_LOCATION = "D:/Demo/test/";

	public static void main(String []args) throws IOException {

		String httpURL = "http://localhost:8080/RestEasy-UP-DOWN-Excel-File/resteasy/fileservice/download/xls";
		String responseString = testDownloadService(httpURL);
		System.out.println("responseString : " + responseString);
	}

	/**
	 * using ResteasyClient, ResteasyWebTarget and Response classes from org.jboss.resteasy.client
	 * @param httpURL
	 * @param requestString
	 * @return
	 */
	public static String testDownloadService(String httpURL) throws IOException {

		// local variables
		ResteasyClient resteasyClient = null;
		ResteasyWebTarget resteasyWebTarget = null;
		Response response = null;
		InputStream inputStream = null;
		OutputStream outputStream = null;
		int responseCode;
		String responseMessageFromServer = null;
		String responseString = null;
		String qualifiedDownloadFilePath = null;

		try{
			// invoke service after setting neccessary parameters
			resteasyClient = new ResteasyClientBuilder().build();
			resteasyWebTarget = resteasyClient.target(httpURL);
			resteasyWebTarget.property("accept", "application/vnd.ms-excel");
			response = resteasyWebTarget.request().get();

			// get response code
			responseCode = response.getStatus();
			System.out.println("Response code: " + responseCode);

			if (response.getStatus() != 200) {
				throw new RuntimeException("Failed with HTTP error code : " + responseCode);
			}

			// get response message
			responseMessageFromServer = response.getStatusInfo().getReasonPhrase();
			System.out.println("ResponseMessageFromServer: " + responseMessageFromServer);

			// read response string
			inputStream = response.readEntity(InputStream.class);
			qualifiedDownloadFilePath = DOWNLOAD_FILE_LOCATION + "MyExcelFile.xlsx";
			outputStream = new FileOutputStream(qualifiedDownloadFilePath);
			byte[] buffer = new byte[1024];
			int bytesRead;
			while ((bytesRead = inputStream.read(buffer)) != -1) {
				outputStream.write(buffer, 0, bytesRead);
			}

			// set download SUCCES message to return
			responseString = "downloaded successfully at " + qualifiedDownloadFilePath;
		}
		catch(Exception ex){
			ex.printStackTrace();
		}
		finally{
			// release resources, if any
			outputStream.close();
			response.close();
		}
		return responseString;
	}
}

Output in console (download .xlsx file)

Response code: 200
ResponseMessageFromServer: OK
responseString : downloaded successfully at D:/Demo/test/MyExcelFile.xlsx

Download project (Tomcat Server 7.0.x)

RestEasy-UP-DOWN-Excel-File (Tomcat server) (12kB)

 

JBoss Deployment

  1. Update pom.xml with resteasy scope “provided” for dependencies as JBoss AS7 modules already contains these dependent jars 
    <resteasy.scope>provided</resteasy.scope> <!-- compile(Tomcat) / provided(JBoss) -->
  2. Update web.xml
    web.xml

    <?xml version="1.0" encoding="UTF-8"?>
<web-app version="3.0" xmlns="http://java.sun.com/xml/ns/javaee"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd">

	<display-name>RestEasy-UP-DOWN-Excel-File</display-name>

	<!-- RestEasy Servlet -->
	<servlet-mapping>
		<servlet-name>javax.ws.rs.core.Application</servlet-name>
		<url-pattern>/resteasy/*</url-pattern>
	</servlet-mapping>

	<!-- welcome file -->
	<welcome-file-list>
		<welcome-file>index.html</welcome-file>
	</welcome-file-list>

</web-app>
  3. Rest remain the same
  4. Read through this article which explains development & deployment of RestEasy web service with JBoss Application Server in detail

Note: JBoss Application Server 7.1.1.Final comes with default RestEasy distribution with version 2.3.2.Final. So update JBoss AS7 with latest RestEasy version. Look at this article, which explains how to update default version with latest version available in the JBoss community

Download project (JBoss Application Server 7.1.1.Final)

RestEasy-UP-DOWN-Excel-File (JBoss server) (12kB)

Conclusion: It’s quite easy to implement download/upload files functionality in JAX-RS Restful web service using simple annotations like @Produces & @Consumes on top of the service class to be exposed

In the next article, very similarly we will implement an example for uploading/downloading Microsoft Word document (.docx) files

Happy Coding !!
Happy Learning !!

RestEasy: JAX-RS web service for uploading/downloading Word document + Java client
RestEasy: JAX-RS web service for uploading/downloading PDF file + Java client

Related posts:

  1. RestEasy: JAX-RS web service using @QueryParam annotation
  2. RestEasy: JAX-RS web service using @FormParam annotation
  3. RestEasy: JAX-RS web service + Integrating with Spring framework 3.2.x
  4. RestEasy: JAX-RS web service for uploading/downloading Image file + Java client