First restful web service with maven

Project description

Goal is to create simple rest web service, which you can write and test (see the results) quickly.


Important informations

Technologies that are used

  1. Maven (building, organizing tool)
  2. Glassfish (Application Server)
  3. JAX-RS [Jersey implementation] (Java API for RESTful Web Services)
  4. Git (Source Code Management)
  5. Eclipse IDE (irrelevant)

Project repository

You can checkout the project using git from my google.code, project is here.
First app is under tag v1.0.0.
git clone https://code.google.com/p/restful-webservice-training/ -b v1.0.0


Getting started with pom

I will start with configuring maven .pom file. The whole file looks like this:

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
	<modelVersion>4.0.0</modelVersion>
	<groupId>com.morcinek.server</groupId>
	<artifactId>restful-webservice-training</artifactId>
	<version>0.0.1</version>
	<name>restful-service</name>
	<packaging>war</packaging>

	<build>
		<plugins>
			<!-- gets specified java version to compile -->
			<plugin>
				<groupId>org.apache.maven.plugins</groupId>
				<artifactId>maven-compiler-plugin</artifactId>
				<version>2.3.2</version>
				<configuration>
					<source>1.6</source>
					<target>1.6</target>
				</configuration>
			</plugin>
			<!-- glassfish container plugin -->
			<plugin>
				<groupId>org.glassfish</groupId>
				<artifactId>maven-embedded-glassfish-plugin</artifactId>
				<version>3.1</version>
				<configuration>
					<goalPrefix>glassfish</goalPrefix>
					<app>target/${project.artifactId}-${project.version}.${packaging}</app>
					<port>8080</port>
					<contextRoot>${project.name}</contextRoot>
					<name>${project.name}</name>
				</configuration>
				<executions>
					<!-- executes run goal from plugin durring install of project. -->
					<execution>
						<phase>install</phase>
						<goals>
							<goal>run</goal>
						</goals>
					</execution>
				</executions>
			</plugin>
		</plugins>
	</build>

	<dependencies>
		<dependency>
			<groupId>com.sun.jersey</groupId>
			<artifactId>jersey-server</artifactId>
			<version>1.0.3.1</version>
			<scope>compile</scope>
		</dependency>
		<!-- this is responsible for JAX-RS interface, but it is already included 
			in jersey-server -->
<!-- 		<dependency> -->
<!-- 			<groupId>javax.ws.rs</groupId> -->
<!-- 			<artifactId>jsr311-api</artifactId> -->
<!-- 			<version>1.0</version> -->
<!-- 		</dependency> -->
	</dependencies>

	<repositories>
		<repository>
			<id>maven2-repository.dev.java.net</id>
			<name>Java.net Repository for Maven</name>
			<url>http://download.java.net/maven/2/</url>
		</repository>
		<repository>
			<id>glassfish-repository</id>
			<name>Java.net Repository for Glassfish</name>
			<url>http://download.java.net/maven/glassfish</url>
		</repository>
	</repositories>

	<pluginRepositories>
		<pluginRepository>
			<id>maven.java.net</id>
			<name>Java.net Maven2 Repository</name>
			<url>http://download.java.net/maven/2</url>
		</pluginRepository>
		<!-- you can find maven-embedded-glassfish-plugin in this repository -->
		<pluginRepository>
			<id>glassfish-repository</id>
			<name>Java.net Repository for Glassfish</name>
			<url>http://download.java.net/maven/glassfish</url>
		</pluginRepository>
	</pluginRepositories>

</project>

Plugin configuration

Important section is inside maven-embedded-glassfish-plugin configuration section.

<app>target/${project.artifactId}-${project.version}.${packaging}</app>
<port>8080</port>
<contextRoot>${project.name}</contextRoot>

app – points to location of builded war app.
port – http port under which the server will be available.
contextRoot – first part of the url under which the service will be available.

Starting server

There are two ways to start the glassfish server and deploy an .war application on it.

  • First is to call:
    mvn org.glassfish:maven-embedded-glassfish-plugin:3.1:run
    (start server with built app deployed on it)
  • Second is to call:
    mvn install
    (builds project and start server with built app deployed on it)
    Part that is responsible for this happening is following:

    <execution>
    	<phase>install</phase>
    	<goals>
    		<goal>run</goal>
    	</goals>
    </execution>
    



More about maven embedded glassfish plugin is here.


Jersey settings

For Jersey restful service to work you need to create a file web.xml in src/main/webapp/WEB-INF/. Content of this file is below:

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xmlns="http://java.sun.com/xml/ns/javaee" xmlns:web="http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
	xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
	id="WebApp_ID" version="2.5">
	<display-name>com.morcinek.server</display-name>
	<servlet>
		<servlet-name>Jersey Servlet</servlet-name>
		<servlet-class>com.sun.jersey.spi.container.servlet.ServletContainer</servlet-class>
		<init-param>
			<param-name>com.sun.jersey.config.property.packages</param-name>
			<param-value>com.morcinek.server</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>
</web-app>

Relevant informations are:

  • Package name in which are services defined.
    <param-value>com.morcinek.server</param-value>
  • Second part of the url under which the service will be available.
    <url-pattern>/rest/*</url-pattern>


Webservice in Java

package com.morcinek.server;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;

@Path("/notes")
@Produces({"application/xml"})
public class NotesHandler {

    @GET
    public String list() {
        return "<b>Hello World, I still need some work to be useful!</b>";
    }

}
    @Path – describes last part of url under which this service will be available.
    @Produces – in what format is the content returned.
    @GET – point that this is REST GET operation.


How to use

Building and starting server:
mvn install
Checking the service with default browser, under following url:
http://localhost:8080/restful-service/rest/notes


Useful Links

Reklamy

3 uwagi do wpisu “First restful web service with maven

Skomentuj

Wprowadź swoje dane lub kliknij jedną z tych ikon, aby się zalogować:

Logo WordPress.com

Komentujesz korzystając z konta WordPress.com. Wyloguj / Zmień )

Zdjęcie z Twittera

Komentujesz korzystając z konta Twitter. Wyloguj / Zmień )

Facebook photo

Komentujesz korzystając z konta Facebook. Wyloguj / Zmień )

Google+ photo

Komentujesz korzystając z konta Google+. Wyloguj / Zmień )

Connecting to %s