Das REST in RESTful-Service steht für Representational State Transfer. Ein RESTful-Service stellt eine Ressource zur Verfügung, die durch ihre URI eindeutig identifiziert wird.

• JAX-RS: Jersey
• Erster Testlauf: REST-Projekt mit Eclipse
• Test Datenaustausch mit einem String
• Datenaustausch mit XML
• Objektaustausch an Jersey-Client mit XML
• CRUD und die REST-API
• Die Schnittstellen-Klasse für CRUD
  • Die Datenverwaltung DAO
  • Der Jersey-Client für REST
  • Der HttpURL-Client für REST

REST stellt einen Verzeichnisbaum für die Ressourcen einer Anwendung zur Verfügung. Eine Klasse dieses Verzeichnisbaums wird durch eine eindeutige URL gekennzeichnet.

Auf jede dieser Klassen können HTTP-Methoden wie GET, PUT, POST und DELETE angewandt werden. Dabei haben diese Methoden folgende semantische Bedeutung:

• GET: Die Ressource wird gelesen und dabei nicht verändert.
• POST: Eine Ressource wird erstellt.
• PUT: Eine Ressource wird anhand ihrer ID erstellt oder geändert.
• DELETE: Eine Ressource wird gelöscht.

REST-Server sind stateless, eine Anfrage kann also nicht auf einer vorhergehenden Anfrage aufbauen. Entsprechend gibt es keine Transaktionen wie bei Datenbanken.

Da ein REST-Server über HTTP liefert, werden die Daten typischerweise für die serialisierte Übertragung konvertiert. Typisch sind dabei XML und JSON.

• XML (text/xml oder application/xml)
• JSON (application/json)
• Roher Text (text/plain): Es findet keine Umwandlung statt.
• HTML (text/html oder bei Sendung von Formularen application/x-www-form-urlencoded)

JAX-RS: Jersey

Ein RESTful Service wird in Java auf der Basis eines Application-Servers aufgesetzt, gehört also zum Thema Jakarta bzw. Java Enterprise Edition. Dieser Artikel beschreibt, wie ein solcher Service programmiert wird und wie man ihn mit Java-Clients nutzt.

Erster Testlauf: REST-Projekt mit Eclipse

• Starten Sie Eclipse und erzeugen ein neues Projekt Dynamic Web Project. File|New|Project|Web|Dynamic Web Project
• Der Projektname sollte wohl bedacht sein, denn standardmäßig wird auch die erzeugte WAR-Datei so heißen und damit geht der Projektname als erster Pfad in die spätere URL ein, hier als Beispiel: TestRest
• Zwei Mal Next klicken und dann Generate web.xml deployment descriptor anwählen. Finish.

Download der Jersey-Bibliotheken

Der darunter liegende Link verweist auf auf eine http://-Seite. Allerdings muss hier eine https://-Adresse verwendet werden, sonst kann die Datei nicht heruntergeladen werden.

Ändern Sie die URL entsprechend oder verwenden Sie diesen Link für den Download von jaxrs-ri-2.30.1.zip

Integration der Jersey-Jars in das Projekt

• Kopieren Sie die Jar-Dateien aus allen Unterverzeichnissen in das Projektverzeichnis WebContent/WEB-INF/lib.
• Nun klicken Sie das Projekt mit der rechten Maustaste und wählen Properties.
• Unter Java Build Path klicken Sie auf die Lasche Libraries
• Klicken Sie auf Add JARs
• Im Dialog klicken Sie das eigene Projekt und hangeln sich zum Verzeichnis WebContent/WEB-INF/lib durch.
• Markieren Sie alle Jar-Dateien und klicken OK. Der Dialog endet.
• Schließen Sie den Properties-Dialog durch Klick auf Apply and Close.

Application und @ApplicationPath

import javax.ws.rs.ApplicationPath;
import javax.ws.rs.core.Application;

@ApplicationPath("app")
public class HalloApplication extends Application {
}

Service-Klasse

• Mit der rechten Maustaste das dynamische Web-Projekt anklicken.
• New| RESTful Web Service from Pattern
• In dem Dialog wird der Class name eingegeben: Hallo
• MIME type steht auf application/xml, kann auch auf application/json umgestellt werden.
• Unter Path wird der Pfad des Service eingestellt. Wir ändern ihn von generic auf service. Er erscheint dann unter @Path im Listing.
• Abschließen mit Finish.

import javax.ws.rs.Consumes;
import javax.ws.rs.GET;
import javax.ws.rs.PUT;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.core.Context;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.UriInfo;

@Path("service")
public class Hallo {
    @SuppressWarnings("unused")
    @Context
    private UriInfo uriInfo;

    /**
     * Default constructor. 
     */
    public Hallo() {
        // TODO Auto-generated constructor stub
    }
    
    /**
     * Retrieves representation of an instance of Hallo
     * @return an instance of String
     */
    @GET
    @Produces("application/xml")
    public String getXml() {
        // TODO return proper representation object
        throw new UnsupportedOperationException();
    }

    /**
     * PUT method for updating or creating an instance of Hallo
     * @param content representation for the resource
     * @return an HTTP response with content of the updated or created resource.
     */
    @PUT
    @Consumes("application/xml")
    public void putXml(String content) {
    }
}

Um zu testen, ob diese Klasse arbeitet und auf Anfragen reagiert, bauen wir noch eine zusätzliche Methode ein, die auf eine GET-HTML-Anfrage reagiert.

@GET
@Produces(MediaType.TEXT_HTML)
public String sagHtml() {
    return "<html><body><h1>Hallo!</h1></body></html>";
}

• Das Projekt mit der rechten Maustaste anklicken und Run As|Run on Server auswählen.
• Der Server fährt hoch und es erscheint ein Browser mit Fehlermeldung 404.
• Ändern der URL in http://localhost:8080/TestRest/app/service
• Jetzt sollte Hallo erscheinen.

Test Datenaustausch mit einem String

Dazu wird in der Server-Klasse die getXml-Methode geändert. Sie liefert nun einen wiedererkennbaren String.

@GET
@Produces("application/xml")
public String getXml() {
    // throw new UnsupportedOperationException();
    return "XML-String";
}

Dazu wird ein zusätzliches Java-Projekt angelegt und die Klasse RestClientHttp angelegt.

• Die URL ist http://localhost:8080/TestRest/app/service
• Request-Methode wird auf GET gesetzt.
• Accept wird auf application/xml gesetzt.

import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;

public class RestClientHttp {
    public static void get(String url) {
        try {
            HttpURLConnection verbind =
                    (HttpURLConnection) new URL(url).openConnection();
            verbind.setRequestProperty("Accept", "application/xml");
            verbind.setRequestMethod("GET");
            InputStream inStream = verbind.getInputStream();
            BufferedReader in = new BufferedReader(
                    new InputStreamReader(inStream));
            String empfangeneZeile;
            StringBuffer antwort = new StringBuffer();

            while ((empfangeneZeile = in.readLine()) != null) {
                antwort.append(empfangeneZeile + "\n");
            }
            in.close();
            System.out.println(antwort.toString());
        } catch (IOException e) {
            e.printStackTrace();
        }
    }

    public static void main(String[] args) {
        String url = "http://localhost:8080/TestRest/app/service";
        get(url);
    }
}

Für einen Datenaustausch könnte man hier beliebige Daten zu XML konvertieren, auf der Client-Seite einlesen und wieder zu den ursprünglichen Daten zurück konvertieren.

Datenaustausch mit XML

Als Beispiel erzeugen wir ein Projekt RestXml und verwenden darin eine Wohnung. Damit sie in XML umgewandelt werden kann, muss sie mit @XmlRootElement gekennzeichnet werden.

package data; // Wichtig: Muss in einem package liegen!

import javax.xml.bind.annotation.XmlRootElement;

@XmlRootElement
public class Wohnung {
    private String bez;
    private int qm;
    private double miete;
...

import javax.ws.rs.ApplicationPath;
import javax.ws.rs.core.Application;

@ApplicationPath("app")
public class XmlApp extends Application {
}

• Class name: ServiceWohnung
• MIME type: application/xml
• Representation class: Hier auf Browse klicken
• In das Suchfeld Wohnung eintippen. Es erscheint eine Liste, in der die Wohnung im Projekt RestXml/src auftaucht.
• Auswählen und OK. Der Dialog verschwindet und data.Wohnung wird in Representation class übernommen.
• Finish

@Path("wohnung")
public class ServiceWohnung {
    @SuppressWarnings("unused")
    @Context
    private UriInfo uriInfo;

    public ServiceWohnung() {
    }

    @GET
    @Produces("application/xml")
    public Wohnung getXml() {
        // TODO return proper representation object
        throw new UnsupportedOperationException();
    }

    @PUT
    @Consumes("application/xml")
    public void putXml(Wohnung content) {
    }
}

    @GET
    @Produces("application/xml")
    public Wohnung getXml() {
        Wohnung w = new Wohnung();
        w.setBez("Parterre");
        w.setMiete(500.0);
        w.setQm(80);
        return w;
    }

public static void main(String[] args) {
    String url = "http://localhost:8080/RestXml/app/wohnung";
    get(url);
}

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<wohnung>
    <bez>Parterre</bez>
    <miete>500.0</miete>
    <qm>80</qm>
</wohnung>

Objektaustausch an Jersey-Client mit XML

Jersey-Bibliotheken in ein Java-Projekt einfügen

• Neues Java-Projekt anlegen, mit rechter Maustaste anklicken.
• New|Folder
• den Ordnernamen lib angeben. Finish
• Alle JAR-Dateien wie beim Rest-Projekt in diesen Ordner kopieren.
• Projekt rechts anklicken. Properties|Java Build|Libraries
• Add Jars anklicken. JAR-Dateien im lib-Verzeichnis auswählen.
• Apply and Close

Die Wohnung anlegen

Ein Jersey-Client

import javax.ws.rs.client.Client;
import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.client.WebTarget;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.UriBuilder;
import org.glassfish.jersey.client.ClientConfig;
import data.Wohnung;

public class RestClient {

    static final String PACKAGE = "RestXml";
    static final String URL = "app";
    static final String PATH = "wohnung";

    public static void main(String[] args) {
        ClientConfig clientconfig = new ClientConfig();
        Client client = ClientBuilder.newClient(clientconfig);
        WebTarget target = client.target(UriBuilder
                .fromUri("http://localhost:8080/"+PACKAGE).build());
        Wohnung wohnung = target.path(URL).path(PATH).request()
                .accept(MediaType.APPLICATION_XML).get(Wohnung.class);
        System.out.println(wohnung.getBez());
    }
}

Jersey-Client-API

• Zunächst wird ein Client-Objekt aus einer Standard-ClientConfig erstellt.
• WebTarget stellt die Verbindung zum Server dar, die für den Client erstellt wird.
• Über WebTarget wird mit path-Aufrufen das Ziel spezifiziert.
• request bietet folgende Methoden:
  • accept bestimmt den MIME-Typ
  • Der Parameter von get gibt den Rückgabetyp an

CRUD und die REST-API

Diese vier Operationen werden durch die HTTP-Methoden GET, POST, DELETE und PUT angesteuert.

Die Klasse Kunde

package kunde;

import java.io.Serializable;
import javax.xml.bind.annotation.XmlRootElement;

@XmlRootElement
public class Kunde implements Serializable {
    private static final long serialVersionUID = 1L;
    private String nr;
    private String name;
    private String adresse;

    public Kunde() {
    }

    public Kunde(String nr, String name, String adresse) {
        this.nr=nr; this.name=name; this.adresse=adresse;
    }

    public String toString() {
        String out = "";
        out += getNr() + ":" + getName() + ":" + getAdresse();
        return out;
    }
    public String getNr() {    return nr; }
    public void setNr(String nr) { this.nr = nr; }
    public String getName() { return name; }
    public String getAdresse() { return adresse; }
    public void setName(String name) {this.name=name; }
    public void setAdresse(String adresse) {this.adresse=adresse; }
}

Application

package kunde;

import javax.ws.rs.ApplicationPath;
import javax.ws.rs.core.Application;

@ApplicationPath("app")
public class KundeApplication extends Application {
}

Die Schnittstellen-Klasse für CRUD

Die Klasse besitzt eine Instanz auf die DAO-Klasse, die sich um die Speicherung der Kunden kümmern soll. Wichtig ist, dass es sich um eine statische Variable handelt.

package kunde;

@Path("kunde")
public class KundenServer {
    static KundeDao kundeDao = new KundeDao();

    @Context
    private UriInfo uriInfo;

GET-Methoden

Hole eine Liste

    @GET
    @Produces(MediaType.APPLICATION_XML)
    public List<Kunde> getKundenXml() {
        System.out.println("get application/xml angefragt");
        return kundeDao.getKunden();
    }

Das DAO kümmert sich später darum, wo die Kunden genau herkommen. Dadurch kann der Service hier schlank bleiben.

Einen einzelnen Kunden holen

Die Methode getEinenKundenXml weist den Parameter hinter id dem String id zu und übergibt ihn an die Methode getKunde der DAO-Klasse.

    @GET
    @Produces(MediaType.APPLICATION_XML)
    @Path("{id}")
    public Kunde getEinenKundenXml(@PathParam("id") String id) {
        Kunde kunde = kundeDao.getKunde(id);
        if (kunde==null)
            throw new NotFoundException();
        return kunde;
    }

HTML für Testzwecke

    @GET
    @Produces(MediaType.TEXT_HTML)
    public String getKundenHtml() {
        String out = "";
        List<Kunde> kunden = kundeDao.getKunden();
        for (Kunde kunde : kunden) {
            out += kunde.toString() + "<br>";
        }
        return out;
    }

POST-Methoden

War alles in Ordnung, möchte der Client sicher gern wissen, unter welcher ID der Kunde abgelegt wurde.

    @POST
    @Consumes(MediaType.APPLICATION_XML)
    public Response postKunde(Kunde kunde) {
        String pos = kundeDao.neuKunde(kunde);
        if (pos==null || pos.isEmpty()) {
            throw new WebApplicationException(
                    Response.status(400).entity("Not created.").build());
        }
        URI location = uriInfo.getAbsolutePathBuilder().path("" + pos).build();
        return Response.created(location).build();
    }

Wirklich interessant ist hier, wie die Parameter der Eingabefelder in Parametervariable mit der Annotation @FormParam übernommen werden.

    @POST
    @Consumes(MediaType.APPLICATION_FORM_URLENCODED)
    // Für die Erzeugung über ein Browserformular
    public Response postKunde(
            @FormParam("nr") String nr,
            @FormParam("name") String name,
            @FormParam("adresse") String adresse) {

        if (name == null || nr == null || adresse == null) {
            throw new WebApplicationException(
                Response.status(400).entity("Could not be created.").build());
        }
        Kunde kunde = new Kunde(nr, name, adresse);
        String pos = kundeDao.neuKunde(kunde);
        URI location = uriInfo.getAbsolutePathBuilder().path("" + pos).build();
        return Response.created(location).build();
    }

DELETE-Methode

    @DELETE
    @Path("{id}")
    public Response deleteKunden(@PathParam("id") String id) {
        if (kundeDao.deleteKunde(id)) {
            return Response.accepted().build();
        }
        throw new NotFoundException();
    }
}

Die Datenverwaltung DAO

Für dieses Beispiel werden die Daten einfach in ArrayLists abgelegt.

package kunde;

import java.util.ArrayList;
import java.util.Iterator;
import java.util.List;

public class KundeDao {

    private List<Kunde> kunden = new ArrayList<Kunde>();
    
    public List<Kunde> getKunden() {
        return kunden;
    }

    public Kunde getKunde(String id) {
        for (Kunde k : kunden) {
            if (k.getNr().equals(id))
                return k;
        }
        return null;
    }

    public String neuKunde(Kunde kunde) {
        kunden.add(kunde);
        return ""+kunde.getNr();
    }

    public boolean deleteKunde(String id) {
        boolean found =false;
        Iterator<Kunde> k = kunden.iterator();
        while (k.hasNext()) {
            Kunde kunde = k.next();
            if (kunde.getNr().equals(id)) {
                k.remove();
                found = true;
            }
        }
        return found;
    }
}

Der Jersey-Client für REST

Im ersten Teil werden die Importe erledigt. Da hilft Eclipse gern mit [Strg]+[Shift]+[O]. Manchmal fragt Eclipse dabei nach, welche Bibliothek es sein soll. Da sind diejenigen richtig, die mit javax.ws.rs anfangen.

import javax.ws.rs.client.Client;
import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.client.Entity;
import javax.ws.rs.client.WebTarget;
import javax.ws.rs.core.Form;
import javax.ws.rs.core.GenericType;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response;
import javax.ws.rs.core.UriBuilder;
import org.glassfish.jersey.client.ClientConfig;

import data.Kunde;
import java.util.List;

public class JerseyClientKunde {
    static final String RESOURCE = "RestKunde";
    static final String URL = "app";
    static final String PATH = "kunde";

    public static void main(String[] args) {
        ClientConfig config = new ClientConfig();
        Client client = ClientBuilder.newClient(config);
        WebTarget service = client.target(
                UriBuilder.fromUri("http://localhost:8080/" + RESOURCE).build());
        Response response = null;

        // Kunden anlegen per POST versenden
        Kunde kunde = new Kunde("007", "James Bond", "London");
        response = service.path(URL).path(PATH)
                .request(MediaType.APPLICATION_XML)
                .post(Entity.entity(kunde, MediaType.APPLICATION_XML),
                Response.class);
        System.out.println("Der POST-Befehl sollte 201 liefern, es ist: "
                +response.getStatus());

        // Simuliere ein HTML-Formular und sende neuen Kunden
        Form form = new Form();
        form.param("nr", "4");
        form.param("name", "Batman");
        form.param("adresse", "Gotham");
        response = service.path(URL).path(PATH).request()
                .post(Entity.entity(form,
                MediaType.APPLICATION_FORM_URLENCODED),
                Response.class);
        System.out.println("Form sollte 201 liefern, es ist: "
                + response.getStatus());

        // Zeige alle Kunden an
        List<Kunde> liste =  service.path(URL).path(PATH).request()
                .accept(MediaType.APPLICATION_XML)
                .get(new GenericType<List<Kunde>>() {});
        System.out.println("--- Liste aller Kunden ---");
        for (Kunde k : liste) {
            System.out.println(k.getNr()+": "+k.getName()+","+k.getAdresse());
        }

        // Prüfe, ob es 007 noch gibt
        String suchstr = "/007";
        Response checkKunde = service.path(URL).path(PATH + suchstr).request()
                .accept(MediaType.APPLICATION_XML).get();
        System.out.println("Suche nach "+suchstr+ " Status: "+checkKunde.getStatus());

        // Hole den Kunden 007
        Kunde james = service.path(URL).path(PATH + suchstr).request()
                .accept(MediaType.APPLICATION_XML).get(Kunde.class);
        System.out.println(james.getName()+" wohnt in "+james.getAdresse());

        // Den Kunde mit der id 007 ausschalten
        service.path(URL).path(PATH + suchstr).request().delete();

        // Zeige noch einmal alle Kunden
        System.out.println(service.path(URL).path(PATH).request()
                .accept(MediaType.APPLICATION_XML).get(String.class));
    }
}

Der POST-Befehl sollte 201 liefern, es ist: 201
Form sollte 201 liefern, es ist: 201
--- Liste aller Kunden ---
007: James Bond,London
4: Batman,Gotham
Suche nach /007 Status: 200
James Bond wohnt in London
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><kundes>
  <kunde><adresse>Gotham</adresse><name>Batman</name><nr>4</nr></kunde>
</kundes>

Der HttpURL-Client für REST

Das ist grundsätzlich kein Problem, da REST über HTTP spricht und mit jedem Client korrespondiert, der HTTP versteht. Das ginge sogar zur Not mit einem reinen Socket-Client.

Ganz so weit wollen wir es nicht treiben. Wir verwenden die HttpURLConnection-Klasse. Allerdings bleibt Ihnen dann die Aufgabe, die XML-Strings zu wandeln. Für dieses Problem gibt es allerdings reichlich Lösungen und Bibliotheken.

import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.io.OutputStream;
import java.io.OutputStreamWriter;
import java.net.HttpURLConnection;
import java.net.URL;

public class RestClientHttp {

    public static void get(String url) {
        try {
            HttpURLConnection verbind = (HttpURLConnection)
                    new URL(url).openConnection();
            verbind.setRequestProperty("Accept", "application/xml");
            verbind.setRequestMethod("GET");
            InputStream inStream = verbind.getInputStream();
            BufferedReader in = new BufferedReader(
                    new InputStreamReader(inStream));
            String empfangeneZeile;
            StringBuffer antwort = new StringBuffer();

            while ((empfangeneZeile = in.readLine()) != null) {
                antwort.append(empfangeneZeile + "\n");
            }
            in.close();
            System.out.println(antwort.toString());
        } catch (IOException e) {
            e.printStackTrace();
        }
    }

In diesem Fall wurde der XML-Code von Hand zusammengesetzt. Bei größeren Strukturen würde man eher eine Bibliothek zuhilfe nehmen.

    static boolean post(String url, String id, String name, String adresse) {
        try {
            HttpURLConnection verbind = (HttpURLConnection)
                    new URL(url).openConnection();
            verbind.setRequestProperty("Accept", "application/xml");
            verbind.setRequestProperty("Content-Type", "application/xml");
            verbind.setRequestMethod("POST");
            verbind.setDoOutput(true);
            verbind.setDoInput(true);
            String command = "<kunde>"
                    + "<nr>"+id+"</nr>"
                    + "<name>"+name+"</name>"
                    + "<adresse>"+adresse+"</adresse>"
                    + "</kunde>";
            OutputStream os = verbind.getOutputStream();
            OutputStreamWriter osw = new OutputStreamWriter(os, "UTF-8");
            osw.write(command);
            osw.flush();
            osw.close();
            System.out.println("ResponseCode: " + verbind.getResponseCode());
            return (verbind.getResponseCode() == HttpURLConnection.HTTP_CREATED);
        } catch (IOException e) {
            e.printStackTrace();
        }
        return false;
    }

    static boolean delete(String url, String id) {
        try {
            HttpURLConnection verbind = (HttpURLConnection)
                    new URL(url+"/"+id).openConnection();
            verbind.setRequestMethod("DELETE");
            verbind.setDoOutput(true);
            verbind.setDoInput(true);
            System.out.println("DELETE ResponseCode: "
                    + verbind.getResponseCode());
            return verbind.getResponseCode()
                    == HttpURLConnection.HTTP_ACCEPTED;
        } catch (IOException e) {
            e.printStackTrace();
        }
        return false;
    }

    public static void main(String[] args) {
        String url = "http://localhost:8080/RestKunde/app/kunde";
        get(url);
        post(url, "32", "Albert Tross", "Weltweit");
        post(url, "35", "Nikita", "Moskau");
        delete(url, "35");
        get(url);
    }
}

• Mittwald: RESTful Webservices Teil 1
• Torsten Horn: REST Web Services mit JAX-RS