Jersey 2.x web service for uploading/downloading Excel file + Java client

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

Jersey is the most popular amongst Restful web service development. Latest Jersey 2.x version has been developed by Oracle/Glassfish team in accordance with JAX-RS 2.0 specification. Earlier Jersey 1.x version was developed and supported by Oracle/Sun team

Latest Jersey release version is 2.12 see here and look documentation and API for details. We will implement Jersey examples in the following articles based on latest 2.x version

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 InputStream & FormDataContentDisposition from input parameter and process to get actual filename and pass inputstream to write to file server
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
Jersey-2.12
Jersey-multipart-2.12
Apache Maven 3.2.1
Apache Tomcat 8.0.54
Glassfish-4.1

Mavenize or download required jars

Add jersey-2.12 & jersey-multipart-2.12 dependencies to pom.xml

	<properties>
		<jersey.version>2.12</jersey.version>
		<jersey.scope>compile</jersey.scope>
		<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>
		<!-- Jersey core Servlet 2.x implementation -->
		<dependency>
			<groupId>org.glassfish.jersey.containers</groupId>
			<artifactId>jersey-container-servlet-core</artifactId>
			<version>${jersey.version}</version>
			<scope>${jersey.scope}</scope>
		</dependency>

		<!-- Jersey Multipart entity providers support module -->
		<dependency>
			<groupId>org.glassfish.jersey.media</groupId>
			<artifactId>jersey-media-multipart</artifactId>
			<version>${jersey.version}</version>
			<scope>${jersey.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 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)

Jars Libraries Used in the Project (Maven Dependencies)

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 Jersey JAX-RS Restful web service

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

This web.xml file describes,

Like any JEE web framework register org.glassfish.jersey.servlet.ServletContainer with servlet container
http requests with URL pattern “/rest/*” will be sent to the registered servlet called “jersey-servlet” i.e.; (org.glassfish.jersey.servlet.ServletContainer)
set <init-param> with <param-name> as “jersey.config.server.provider.packages” and <param-value> describing the qualified package name of the JAX-RS annotated Resource/Provider classes. In this example, “com.jersey.series.upload.download.service”
set another <init-param> for file uploading/downloading support with <param-name> as “jersey.config.server.provider.classnames” and <param-value> as “org.glassfish.jersey.media.multipart.MultiPartFeature”
<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>Jersey-UP-DOWN-Excel-File</display-name>

	<!-- Jersey Servlet -->
	<servlet>
		<servlet-name>jersey-servlet</servlet-name>
		<servlet-class>org.glassfish.jersey.servlet.ServletContainer</servlet-class>
		<!-- Register resources and providers -->
		<init-param>
			<param-name>jersey.config.server.provider.packages</param-name>
			<param-value>com.jersey.series.upload.download.service</param-value>
		</init-param>
		<init-param>
			<param-name>jersey.config.server.provider.classnames</param-name>
			<param-value>org.glassfish.jersey.media.multipart.MultiPartFeature</param-value>
		</init-param>
		<load-on-startup>1</load-on-startup>
	</servlet>

	<servlet-mapping>
		<servlet-name>jersey-servlet</servlet-name>
		<url-pattern>/rest/*</url-pattern>
	</servlet-mapping>

	<!-- 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 8.0 server so our server and port are localhost and 8080 respectively. Context root is the project name i.e.; Jersey-UP-DOWN-Excel-File. Initial path for this application is http://localhost:8080/Jersey-UP-DOWN-Excel-File

We have configured “/rest/*” as url-pattern for the “jersey-servlet” servlet in web.xml and at 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

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

IFileService.java

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

import java.io.InputStream;

import javax.ws.rs.core.Response;

import org.glassfish.jersey.media.multipart.FormDataContentDisposition;

public interface IFileService {

	public Response downloadExcelFile();
	public Response uploadExcelFile(InputStream fileInputStream, FormDataContentDisposition fileFormDataContentDisposition);
}

File Service implementation

Implements above interface to download/upload files

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

Get InputStream & FormDataContentDisposition and write to UPLOAD_FILE_SERVER using simple file handling operations. Use Content Disposition to get actual file name

Note: Jersey doesn’t inherit JAX-RS annotations. So we are annotating Resource/Provider classes and then defining qualified package name in web.xml

FileServiceImpl.java

package com.jersey.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 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 javax.ws.rs.core.Response.ResponseBuilder;

import org.glassfish.jersey.media.multipart.FormDataContentDisposition;
import org.glassfish.jersey.media.multipart.FormDataParam;

@Path("/fileservice")
public class FileServiceImpl implements IFileService {

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

	// http://localhost:8080/Jersey-UP-DOWN-Excel-File/rest/fileservice/download/xls
	@GET
	@Path("/download/xls")
	@Produces("application/vnd.ms-excel")
	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=\"MyJerseyExcelFile.xlsx\"");
		return responseBuilder.build();
	}

	// http://localhost:8080/Jersey-UP-DOWN-Excel-File/rest/fileservice/upload/xls
	@POST
	@Path("/upload/xls")
	@Consumes(MediaType.MULTIPART_FORM_DATA)
	public Response uploadExcelFile(
			@FormDataParam("uploadFile") InputStream fileInputStream,
			@FormDataParam("uploadFile") FormDataContentDisposition fileFormDataContentDisposition) {

		// local variables
		String fileName = null;
		String uploadFilePath = null;

		try {
			fileName = fileFormDataContentDisposition.getFileName();
			uploadFilePath = writeToFileServer(fileInputStream, fileName);
		}
		catch(IOException ioe){
			ioe.printStackTrace();
		}
		finally{
			// release resources, if any
		}
		return Response.ok("File uploaded successfully at " + uploadFilePath).build();
	}

	/**
	 * write input stream to file server
	 * @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;
	}
}

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>Jersey 2.x : File Upload</title>
</head>
<body>
	<center>
		<b>Jersey 2.x : 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="rest/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="uploadFile" 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>

Tomcat-8.0.12 Deployment

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

Glassfish-4.1 Deployment

Run maven command to build the war: mvn clean install (use command prompt or integrated maven in eclipse IDE
Once you see “BUILD SUCCESS” after running maven command, keep the war file ready to be deployed
There are two ways to deploy war file into Glassfish-4.1
1. Online
2. Offline
Click here to understand above deployments process in detail

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

1. HTML page in web browser

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

Result in web browser: upload success

1.2 download excel file
Enter URL: http://localhost:8080/Jersey-UP-DOWN-Excel-File/rest/fileservice/download/xls into web browser

Allows downloading users to open/save xlsx file

2. Java client

Uses Client, ClientBuilder, WebTarget and Response classes from core JAX-RS package javax.ws.rs.client for invoking Restful web service

Note: Commented lines will help out us to try (set) various http request header parameters

2.1 Upload Excel file

Invoking Restful web service to upload .xlsx file

TestUploadFileService.java

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

import java.io.File;

import javax.ws.rs.client.Client;
import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.client.Entity;
import javax.ws.rs.client.Invocation;
import javax.ws.rs.client.WebTarget;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response;

import org.glassfish.jersey.client.ClientConfig;
import org.glassfish.jersey.media.multipart.FormDataMultiPart;
import org.glassfish.jersey.media.multipart.MultiPartFeature;
import org.glassfish.jersey.media.multipart.file.FileDataBodyPart;

public class TestUploadFileService {

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

		// set file upload parameters
		String httpURL = "http://localhost:8080/Jersey-UP-DOWN-Excel-File/rest/fileservice/upload/xls";
		File filePath = new File("D:/Demo/download/Microbiology.xlsx");

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

	/**
	 * uploads excel file using the input HTTP URL
	 * @param httpURL
	 * @param filePath
	 * @param filename
	 * @return
	 * @throws Exception
	 */
	public static String testUploadService(String httpURL, File filePath)  throws Exception {

		// local variables
		ClientConfig clientConfig = null;
		Client client = null;
		WebTarget webTarget = null;
		Invocation.Builder invocationBuilder = null;
		Response response = null;
		FileDataBodyPart fileDataBodyPart = null;
		FormDataMultiPart formDataMultiPart = null;
		int responseCode;
		String responseMessageFromServer = null;
		String responseString = null;

		try{
			// invoke service after setting necessary parameters
			clientConfig = new ClientConfig();
			clientConfig.register(MultiPartFeature.class);
			client =  ClientBuilder.newClient(clientConfig);
			webTarget = client.target(httpURL);

			// set file upload values
			fileDataBodyPart = new FileDataBodyPart("uploadFile", filePath, MediaType.APPLICATION_OCTET_STREAM_TYPE);
			formDataMultiPart = new FormDataMultiPart();
			formDataMultiPart.bodyPart(fileDataBodyPart);

			// invoke service
			invocationBuilder = webTarget.request();
			//			invocationBuilder.header("Authorization", "Basic " + authorization);
			response = invocationBuilder.post(Entity.entity(formDataMultiPart, 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
			fileDataBodyPart.cleanup();
			formDataMultiPart.cleanup();
			formDataMultiPart.close();
			response.close();
			client.close();
		}
		return responseString;
	}
}

Output in Console (upload .xlsx file)

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

2.2 Download Excel file

To invoke Restful web service to download .xlsx file

TestDownloadFileService.java

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

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

import javax.ws.rs.client.Client;
import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.client.Invocation;
import javax.ws.rs.client.WebTarget;
import javax.ws.rs.core.Response;

import org.glassfish.jersey.client.ClientConfig;
import org.glassfish.jersey.media.multipart.MultiPartFeature;

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/Jersey-UP-DOWN-Excel-File/rest/fileservice/download/xls";
		String responseString = testDownloadService(httpURL);
		System.out.println("responseString : " + responseString);
	}

	/**
	 * downloads excel file using the input HTTP URL
	 * @param httpURL
	 * @return
	 * @throws IOException
	 */
	public static String testDownloadService(String httpURL) throws IOException {

		// local variables
		ClientConfig clientConfig = null;
		Client client = null;
		WebTarget webTarget = null;
		Invocation.Builder invocationBuilder = 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 necessary parameters
			clientConfig = new ClientConfig();
			clientConfig.register(MultiPartFeature.class);
			client =  ClientBuilder.newClient(clientConfig);
			client.property("accept", "application/vnd.ms-excel");
			webTarget = client.target(httpURL);

			// invoke service
			invocationBuilder = webTarget.request();
			//			invocationBuilder.header("Authorization", "Basic " + authorization);
			response = invocationBuilder.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 + "MyJerseyExcelFile.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();
			client.close();
		}
		return responseString;
	}
}

Output in Console (download .xlsx file)

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

Conclusion: It’s quite easy to implement download & upload file 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

Download project

Jersey-2x-UP-DOWN-Excel-File (11kB)

Happy Coding !!
Happy Learning !!

BenchResources.Net

Java tutorial for beginners

Jersey 2.x web service for uploading/downloading Excel file + Java client

Download

Upload

Annotation Used

Technology Used

Mavenize or download required jars

Directory Structure

Project Structure (Package Explorer view in Eclipse)

Jars Libraries Used in the Project (Maven Dependencies)

Web application

web.xml

Let’s see coding in action

URL Pattern

File Service interface

IFileService.java

File Service implementation

Download

Upload

FileServiceImpl.java

View Technologies

uploadXlsFile.html

Tomcat-8.0.12 Deployment

Glassfish-4.1 Deployment

Testing

1. HTML page in web browser

2. Java client

2.1 Upload Excel file

TestUploadFileService.java

2.2 Download Excel file

TestDownloadFileService.java

Download project

Related

Download

Upload

Annotation Used

Technology Used

Mavenize or download required jars

Directory Structure

Project Structure (Package Explorer view in Eclipse)

Jars Libraries Used in the Project (Maven Dependencies)

Web application

web.xml

Let’s see coding in action

URL Pattern

File Service interface

IFileService.java

File Service implementation

Download

Upload

FileServiceImpl.java

View Technologies

uploadXlsFile.html

Tomcat-8.0.12 Deployment

Glassfish-4.1 Deployment

Testing

1. HTML page in web browser

2. Java client

2.1 Upload Excel file

TestUploadFileService.java

2.2 Download Excel file

TestDownloadFileService.java

Download project

Related

Related posts: