smash-it.de

Motivation:

Der SOA Zug rollt bzw. ist eigentlich schon lange lange unterwegs und WebServices sind ein Trendthema. Ein Web Service lässt sich mit dem SOAP basierten Ansatz oder mit der REST Idee realisieren. Auf SOAP und Frameworks wie Axis2 werde ich hier nicht eingehen. Nun eine kurze Erklärung zu REST: Der größte Unterschied zu dem SOAP basierten Ansatz ist, dass es die HTTP Methoden wie GET, POST, PUT, DELETE, HEADER benutzt. In dem Glaubenskrieg zwischen den “Seifenliebhabern” und den REST-Anhängern wird das immer als Argument gebracht, dass REST als Web Service viel näher am Internet (HTTP) ist. Denn REST arbeitet wie gesagt mit den HTTP Methoden und die Daten des Service sind per Link erreichbar.

Ich habe mich vor kurzem mit der Materie auseinandergesetzt und versucht eine leichte Erklärung zu finden, die mir zeigt wie ich ein REST Projekt erstelle, es auf dem Tomcat Server zum laufen bringe und anschließend benutze. Weil ich die Ergebnisse bei der Suche nach solchen Tutorials nicht besonders befriedigend fand, dachte ich mir, es wäre an der Zeit so ein einfaches Tutorial zu schreiben.

Projekt Setup:

• Eclipse JavaEE 3.4 (Ganymede)
• Tomcat 6.0.18
• Jersey (REST Referenz Implementierung)

Außerdem verwende ich das Kommandozeilentool Curl zum Testen der Anwendung. Mit dem Tool können einfach Request an eine URL geschickt und die Antwort ausgewertet werden.

Nun kann man direkt in Eclipse loslegen indem man ein neues Dynamisches Web Projekt anlegt.

Nach dem Anlegen des Projektes habe ich lediglich das Paket de.smashit.resources angelegt und die Datei web.xml im Ordner WEB-INF erstellt. Den Inhalt der web.xml findet Ihr weiter unten.

Für das Entwickeln eines RESTful Webservice sind auch einige Bibliotheken von Nöten, die im Ordner WEB-INF/lib liegen müssen. Hier erhaltet ihr die von mir verwendete libs.

Das folgende Listing zeigt eine einfache Ressourcenklasse, die im Paket de.smashit.resources liegt. Diese Ressource ist über die URL http://localhost/RestDemo/helloworld erreichbar. Die Annotation @Path konfiguriert die URL für die Ressource. Die Annotation @GET und @POST zeichnen die einzelnen Java Methoden aus und sorgen für ein Mapping zu den Http Methoden (GET, POST, PUT, DELETE, HEAD). Die @Produces Annotation gibt an welche Output von der Methode zurückgeliefert wird. In diesem einfachen Beispiel ist es nur einfacher Text aber es gibt noch andere Typen wie: application/xml, text/html, application/json.

package de.smashit.resources;

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

//The resource (Java class) will be hosted at the URI path "/helloworld"
@Path("/helloworld")
public class HelloRestResource {

// The method will be invoked by HTTP GET requests
// The method will produce content of MIME Media type "text/plain"
@GET
@Produces("text/plain")
public String getClichedMessage() {
return "Hello Rest (GET)";
}

@POST
@Produces("text/plain")
public String setSomething() {
return "Hello Rest (Post)";
}
}

Im Ordner WEB-INF die Datei web.xml anlegen und mit folgendem XML Code füllen. In der web.xml wird ein sogenanntes Servlet gemappt (RestServlet), das von der Wurzel Url aus aufrufbar ist (siehe url-pattern). Die Ressourcenklassen müssen sich in den Paketen de.smashit.resources oder test befinden. Jersey sucht sich die Resourcen aus den Paketen raus.

< ?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">

RestDemo


RestServlet

com.sun.jersey.spi.container.servlet.ServletContainer




com.sun.jersey.config.property.resourceConfigClass


com.sun.jersey.api.core.PackagesResourceConfig





com.sun.jersey.config.property.packages


de.smashit.resources;test



1


RestServlet
/*

Das Projekt wird als WebArchive (.war) auf dem Tomcat deployed. Dazu wählt man die Export Funktion von Eclipse und exportiert die war-Datei in den Ordner Webapps des Tomcats. Falls der Tomcat Server bereits läuft, wird die Anwendung automatisch deployed/gestartet und wenn nicht muss nun noch der Server gestartet werden.

Das Projekt wurde erfolgreich auf dem Tomcat deployed, wenn die Meldung in der Konsole des Tomcat in etwa die Nachricht “Root resource classes found” steht. Dann hat der Server die Resource-Klassen in den einzelnen Paketen gefunden und sie erfolgreich geladen.

Anschließen kann man die Anwendung bequem per Browser oder dem Kommandozeilentool curl testen, indem man eine Anfrage an die Adresse stellt. Sowohl der Browser als auch curl versenden standardmäßig GET-Anfragen. So dass in diesem Fall eine Methode der Ressource ansgesprochen wird, die mit @GET annotiert ist.

Mit Browser:

oder ein GET Request mit curl:

oder ein POST Zugriff mit der Option -F

Hat euch dieses einfache Tutorial gefallen oder geholfen? Ich denke nun sollte jeder die Grundlage von REST verstanden haben und ist in der Lage die vielen Details und Möglichkeiten von REST zu erforschen. In meinen Augen ist der schwierigste Teil der Arbeit im Entwurf eines WebServices mit REST. Den die verwendeten URIs sollten möglichst lange gültig sein und alle gewünschten Anforderungen abdecken. Werden neue Funktionen gewünscht, kommen meist schnell Ressourcen hinzu weil die begrenzte Anzahl der HTTP Methoden nicht viel Spielraum pro Ressource lässt. Also investiert in den Entwurf und Definition der Ressourcen möglichst viel Zeit um eine spätere Änderung wenn möglich zu vermeiden.

Und nun wünsche ich viel Spaß beim Entwickeln von Anwendungen mit REST WebService.

Links:

• http://java.dzone.com/articles/putting-java-rest