02.02.2013

Client-API - JAX-RS 2.0 (JSR-339) - Java Enterprise Edition 7 (JEE7)

Im Folgenden wird an einem sehr einfachen REST-Service gezeigt, wie der JAX-RS Client prinzipiell benutzt werden kann, um auf einen WebService zuzugreifen. Um das zu demonstrieren wird ein Webservice erstellt, der einen String zurück liefert. Mögliche Formate sind text/plain, application/json und application/xml.

Der hier erstellte WebServie wird in den weiteren Teilen dieses Tutorials sukzessive erweitert.

Auf der Abbildung sieht man, wie der Client einen Request an den Service /itemService/itemstring des Servers absetzt. Die Response mit dem Ergebnis Item 1 wird vom Server zurück an den Client geliefert, sobald sie vorliegt.

Die folgende Klasse wird in dem Projekt JAXRSServer unter dem Namen ItemService.class abgespeichert und deployed.

package org.hameister.itemservice;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.Produces;
import javax.ws.rs.container.AsyncResponse;
import javax.ws.rs.container.Suspended;

@Path("/itemservice")
public class ItemService {

    @GET
    @Path("itemstring")
    @Produces({"text/plain, application/json, application/xml"})
    public String itemstring() {
        return "Item 1";
    }
}

In dem Beispiel REST-Service wird eine Methode itemstring angelegt, die als einfacher HTTP-GET (@GET) realisiert ist und einen festen Rückgabewert Item 1 hat. Erreichbar ist die Methode über den Pfad (@Path) /itemstring. Mögliche Rückgabeformate sind text/plain, application/json und application/xml, die über die Annotation @Produces definiert werden. Der REST-Serice allgemein ist über den Pfad (@Path) /itemservice erreichbar.

Nach dem Deployment lautet die URL zum Ansprechen des REST-Service gewöhnlich: http://localhost:8080/JAXRSServer/webresources/itemservice/itemstring. (Bei der Verwendung von NetBeans sind die Web-Services unter webresources zu erreichen. Dieser Wert läßt sich aber auch verändern.)

Anschließend werden drei JUnit-Tests erstellt, die den JAX-RS Client verwenden, um die drei unterschiedlichen Formate abzufragen. (Bei einem String als Rückgabewert macht das normalerweise wenig Sinn, aber hier geht es um die Client-API von JAX-RS.)

Die folgende Klasse wird in dem Projekt JAXRSClient unter dem Namen JAXRESTClientTest.class als JUnit-Test abgespeichert.

public class JAXRESTClientTest {

    Client client;
    private static final String SERVER = "http://localhost:8080/JAXRSServer/webresources";

    public JAXRESTClientTest() {
    }

    @BeforeClass
    public static void setUpClass() {
    }

    @AfterClass
    public static void tearDownClass() {
    }

    @Before
    public void setUp() {
        client = ClientFactory.newClient();
    }

    @After
    public void tearDown() {
        client.close();
    }
    
    @Test
    public void itemstringTextPlain() {
    	// WebTarget target = client.target(SERVER + "/itemservice/itemstring");
    	// String returnValue = target.request("text/plain").get(String.class);
    	
        String returnValue = client.target(SERVER + "/itemservice/itemstring").request("text/plain").get(String.class);
        Logger.getLogger(JAXRESTClientTest.class.getName()).log(Level.INFO, "Return value ''itemstring'':{0}", returnValue);
        Assert.assertEquals("Item 1", returnValue);
    }

    @Test
    public void itemstringJSON() {
        String returnValue = client.target(SERVER + "/itemservice/itemstring").request("application/json").get(String.class);
        Logger.getLogger(JAXRESTClientTest.class.getName()).log(Level.INFO, "Return value ''itemstring'':{0}", returnValue);
        Assert.assertEquals("Item 1", returnValue);
    }

    @Test
    public void itemstringXML() {
        String returnValue = client.target(SERVER + "/itemservice/itemstring").request("application/xml").get(String.class);
        Logger.getLogger(JAXRESTClientTest.class.getName()).log(Level.INFO, "Return value 'itemstring':{0}", returnValue);
        Assert.assertEquals("Item 1", returnValue);
    }

Mit dem Aufruf ClientFactory.newClient() wird in der Methode setUp() eine neue Instanz eines Clients erstellt. Da im Hintergrund Jersey als JAX-RS Implementierung verwendet wird, erstellt die Factory-Klasse auch genau eine Instanz eines Jersey-Clients. Dies geschied völlig transparent für den Benutzer.

Der Aufruf client.target(SERVER + "/itemservice/itemstring") erstellt ein WebTarget, auf dem ein request mit Formatangabe und Klassenname des Resultats (get(String.class)) abgesetzt wird. Zum Zusammenbauen des Aufrufs wird der Invocation.Builder verwendet.

Für jedes Format (text/plain, application/json und application/xml) wird ein JUnit-Test erstellt, der den REST-Service aufruft und das Ergebnis überprüft.

Im nächsten Teil, dieses Tutorials wird der REST-Service erweitert und es werden Objekte (Pojos/Beans) übertragen.