Jersey(1.19.1) - XML Support

As you probably already know, Jersey uses MessageBodyWriters and MessageBodyReaders to parse incoming request and create outgoing responses. Every user can create its own representation but... this is not recommended way how to do things. XML is proven standard for interchanging information, especially in web services. Jerseys supports low level data types used for direct manipulation and JAXB XML entities.

Low level XML support

Jersey currently support several low level data types: StreamSourceSAXSourceDOMSource and Document. You can use these types as return type or method (resource) parameter. Lets say we want to test this feature and we have helloworld sample as starting point. All we need to do is add methods (resources) which consumes and produces XML and types mentioned above will be used.

@Path("1")
@POST
public StreamSource get1(StreamSource streamSource) {
    return streamSource;
}

@Path("2")
@POST
public SAXSource get2(SAXSource saxSource) {
    return saxSource;
}

@Path("3")
@POST
public DOMSource get3(DOMSource domSource) {
    return domSource;
}

@Path("4")
@POST
public Document get4(Document document) {
    return document;
}

Both MessageBodyReaders and MessageBodyWriters are used in this case, all we need is do POST request with some XML document as a request entity. I want to keep this as simple as possible so I‘m going to send only root element with no content: "<test />". You can create Jersey client to do that or use some other tool, for example curl as I did. (curl -v http://localhost:9998/helloworld/1 -d "<test />"). You should get exactly same XML from our service as is present in the request; in this case, XML headers are added to response but content stays. Feel free to iterate through all resources.

Getting started with JAXB

Good start for people which already have some experience with JAXB annotations is JAXB sample. You can see various usecases there. This text is mainly meant for those who don‘t have prior experience with JAXB. Don‘t expect that all possible annotations and their combinations will be covered in this chapter, JAXB (JSR 222 implementation) is pretty complex and comprehensive. But if you just want to know how you can interchange XML messages with your REST service, you are looking at right chapter.

Lets start with simple example. Lets say we have class Planet and service which produces "Planets":

// Planet class
@XmlRootElement
public class Planet {
    public int id;
    public String name;
    public double radius;
}

// Resource class
@Path("planet")
public class Resource {

    @GET
    @Produces(MediaType.APPLICATION_XML)
    public Planet getPlanet() {
        Planet p = new Planet();
        p.id = 1;
        p.name = "Earth";
        p.radius = 1.0;

        return p;
    }
} 

You can see there is some extra annotation declared on Planet class. Concretely XmlRootelement. What it does? This is a JAXB annotation which maps java class to XML element. We don‘t need specify anything else, because Planet is very simple class and all fields are public. In this case, XML element name will be derived from class name or you can set name property: @XmlRootElement(name="yourName").

Our resource class will respond to GET /planet with

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<planet>
    <id>1</id>
    <name>Earth</name>
    <radius>1.0</radius>
</planet> 

which might be exactly what we want... or not. Or we might not really care, because we can use Jersey client for making requests to this resource and this is easy as: Planet planet = webResource.path("planet").accept(MediaType.APPLICATION_XML_TYPE).get(Planet.class);. There is pre-created WebResource object which points to our applications context root and we simpli add path (in our clase its "planet"), accept header (not mandatory, but service could provide different content based on this header; for example text/html can be served for web browsers) and at the end we specify that we are expecting Planet class via GET request.

There may be need for not just producing XML, we might want to consume it as well.

@POST
@Consumes(MediaType.APPLICATION_XML)
public void setPlanet(Planet p) {
    System.out.println("setPlanet " + p);
}

After valid request is made (with Jersey client you can do webResource.path("planet").post(p);), service will print out string representation of Planet, which can look like Planet{id=2, name=‘Mars‘, radius=1.51}.

If there is a need for some other (non default) XML representation, other JAXB annotations would need to be used. This process is usually simplified by generating java source from XML Schema which is done by xjc. Xjc is XML to java compiler and is part of JAXB. See JAXB home page for further details.

POJOs

Sometimes you can‘t / don‘t want to add JAXB annotations to source code and you still want to have resources consuming and producing XML representation of your classes. In this case, JAXBElement class should help you. Let‘s redo planet resource but this time we won‘t have XmlRootElement annotation on Planet class.

@Path("planet")
public class Resource {

    @GET
    @Produces(MediaType.APPLICATION_XML)
    public JAXBElement<Planet> getPlanet() {
        Planet p = new Planet();
        p.id = 1;
        p.name = "Earth";
        p.radius = 1.0;

        return new JAXBElement<Planet>(new QName("planet"), Planet.class, p);
    }

    @POST
    @Consumes(MediaType.APPLICATION_XML)
    public void setPlanet(JAXBElement<Planet> p) {
        System.out.println("setPlanet " + p.getValue());
    }
} 

As you can see, everything is little more complicated with JAXBElement. This is because now you need to explicitly set element name for Planet class XML representation. Client side is even more ugly than server side because you can‘t do JAXBElement<Planet>.class so Jersey client API provides way how to workaround it by declaring subclass of GenericType.

// GET
GenericType<JAXBElement<Planet>> planetType = new GenericType<JAXBElement<Planet>>() {};

Planet planet = (Planet) webResource.path("planet").accept(MediaType.APPLICATION_XML_TYPE).get(planetType).getValue();
System.out.println("### " + planet);

// POST
Planet p = new Planet();
// ...

webResource.path("planet").post(new JAXBElement<Planet>(new QName("planet"), Planet.class, p));

Using custom JAXBContext

In some scenarios you can take advantage of using custom JAXBContext. Creating JAXBContext is expensive operation and if you already have one created, same instance can be used by Jersey. Other possible usecase for this is when you need to set some specific things to JAXBContext, for example set different classloader.

@Provider
public class PlanetJAXBContextProvider implements ContextResolver<JAXBContext> {
    private JAXBContext context = null;

    public JAXBContext getContext(Class<?> type) {
        if(type != Planet.class)
            return null; // we don‘t support nothing else than Planet

        if(context == null) {
            try {
                context = JAXBContext.newInstance(Planet.class);
            } catch (JAXBException e) {
                // log warning/error; null will be returned which indicates that this
                // provider won‘t/can‘t be used.
            }
        }
        return context;
    }
}

Sample above shows simple JAXBContext creation, all you need to do is put this @Provider annotated class somewhere where Jersey can find it. Users sometimes have problems with using provider classes on client side, so just for reminder - you have to declare them in client config (cliend does not anything like package scanning done by server).

ClientConfig cc = new DefaultClientConfig();
cc.getClasses().add(PlanetJAXBContextProvider.class);
Client c = Client.create(cc);
时间: 2024-10-10 15:38:56

Jersey(1.19.1) - XML Support的相关文章

Jersey(1.19.1) - Hello World

1. Maven Dependency <properties> <jersey.version>1.19.1</jersey.version> </properties> <dependencies> <dependency> <groupId>com.sun.jersey</groupId> <artifactId>jersey-core</artifactId> <versi

Jersey(1.19.1) - Hello World, Get started with Jersey using the embedded Grizzly server

Maven Dependencies The following Maven dependencies need to be added to the pom: <dependency> <groupId>com.sun.jersey</groupId> <artifactId>jersey-server</artifactId> <version>1.19.1</version> </dependency>

Jersey(1.19.1) - Deploying a RESTful Web Service

JAX-RS provides a deployment agnostic abstract class Application for declaring root resource and provider classes, and root resource and provider singleton instances. A Web service may extend this class to declare root resource and provider classes.

Jersey(1.19.1) - Security with Http(s)URLConnection

With Http(s)URLConnection The support for security, specifically HTTP authentication and/or cookie management with Http(s)URLConnection is limited due to constraints in the API. There are currently no specific features or properties on the Client cla

Jersey(1.19.1) - Sub-resources

@Path may be used on classes and such classes are referred to as root resource classes. @Path may also be used on methods of root resource classes. This enables common functionality for a number of resources to be grouped together and potentially reu

Jersey(1.19.1) - Building Responses

Sometimes it is necessary to return additional information in response to a HTTP request. Such information may be built and returned using Response and Response.ResponseBuilder. For example, a common RESTful pattern for the creation of a new resource

Jersey(1.19.1) - Ease of use and reusing JAX-RS artifacts

Since a resource is represented as a Java type it makes it easy to configure, pass around and inject in ways that is not so intuitive or possible with other client-side APIs. The Jersey Client API reuses many aspects of the JAX-RS and the Jersey impl

Jersey(1.19.1) - Conditional GETs and Returning 304 (Not Modified) Responses

Conditional GETs are a great way to reduce bandwidth, and potentially server-side performance, depending on how the information used to determine conditions is calculated. A well-designed web site may return 304 (Not Modified) responses for the many

Jersey(1.19.1) - WebApplicationException and Mapping Exceptions to Responses

Previous sections have shown how to return HTTP responses and it is possible to return HTTP errors using the same mechanism. However, sometimes when programming in Java it is more natural to use exceptions for HTTP errors. The following example shows