In the modern day transition from a service oriented architecture to a resource oriented architecture the tools are only just catching up. Here’s a very brief and simple example of a REST service using CXF 2.2-SNAPSHOT, JAX-RS 1.0 and Spring 2.5.6. A few key points to note are as below.
- The maven pom file imports a cxf jax-rs bundle which in turn imports all prerequisites - this saves individual cxf imports.
- The getUsers() call demonstrates a rather unorthodox use of a dto as a replacement for a standard collection due to the fact that jaxb cannot handle collections as first class citizens.
- A snapshot version (2.2) is being used of CXF which supports the final version of JAX-RS (1.0) whereas CXF 2.1.x supports only JAX-RS 0.8.
- Annotations have been applied to the implementation but can be applied to the interface.
- Annotations are inherited from interface to implementation and from class level to method level and can be overridden at method level.
Maven dependencies (pom.xml)
<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/maven-v4_0_0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>cxf-rest-example</groupId>
<artifactId>cxf-rest-example</artifactId>
<version>1.0</version>
<packaging>war</packaging>
<name>cxf-rest-example</name>
<description>cxf-rest-example</description>
<organization>
<name>dhruba.name</name>
<url>http://dhruba.name</url>
</organization>
<build>
<finalName>cxf-rest-example</finalName>
<plugins>
<!-- enable java 6 -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<configuration>
<source>1.6</source>
<target>1.6</target>
</configuration>
</plugin>
<!-- skip tests -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<version>2.4.2</version>
<configuration>
<skipTests>true</skipTests>
</configuration>
</plugin>
<!-- automatically clean before build -->
<plugin>
<artifactId>maven-clean-plugin</artifactId>
<executions>
<execution>
<id>auto-clean</id>
<phase>validate</phase>
<goals>
<goal>clean</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
<dependencies>
<dependency>
<groupId>org.apache.cxf</groupId>
<artifactId>cxf-bundle-jaxrs</artifactId>
<version>2.2-SNAPSHOT</version>
</dependency>
<dependency>
<groupId>org.springframework</groupId>
<artifactId>spring-core</artifactId>
<version>2.5.6</version>
</dependency>
<dependency>
<groupId>org.springframework</groupId>
<artifactId>spring-test</artifactId>
<version>2.5.6</version>
</dependency>
<dependency>
<groupId>org.springframework</groupId>
<artifactId>spring-beans</artifactId>
<version>2.5.6</version>
</dependency>
<dependency>
<groupId>org.springframework</groupId>
<artifactId>spring-context</artifactId>
<version>2.5.6</version>
</dependency>
<dependency>
<groupId>junit</groupId>
<artifactId>junit</artifactId>
<version>4.5</version>
<scope>test</scope>
</dependency>
<dependency>
<groupId>log4j</groupId>
<artifactId>log4j</artifactId>
<version>1.2.15</version>
<exclusions>
<exclusion>
<groupId>com.sun.jmx</groupId>
<artifactId>jmxri</artifactId>
</exclusion>
<exclusion>
<groupId>javax.jms</groupId>
<artifactId>jms</artifactId>
</exclusion>
<exclusion>
<groupId>com.sun.jdmk</groupId>
<artifactId>jmxtools</artifactId>
</exclusion>
</exclusions>
</dependency>
</dependencies>
<repositories>
<repository>
<id>java.net.2</id>
<name>Java Net 2 Repository</name>
<url>http://download.java.net/maven/2</url>
</repository>
<repository>
<id>apache.incubating</id>
<name>Apache Incubating Repository</name>
<url>http://people.apache.org/repo/m2-incubating-repository</url>
</repository>
<repository>
<id>apache.snapshot</id>
<name>Apache Snapshot Repository</name>
<url>http://people.apache.org/repo/m2-snapshot-repository</url>
</repository>
</repositories>
</project>
Container descriptor file (web.xml)
<?xml version="1.0" encoding="UTF-8"?>
<web-app version="2.5" xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">
<display-name>CXF REST Example</display-name>
<description>CXF REST Example</description>
<context-param>
<param-name>webAppRootKey</param-name>
<param-value>cxf.rest.example.root</param-value>
</context-param>
<context-param>
<param-name>log4jConfigLocation</param-name>
<param-value>/WEB-INF/classes/log4j.properties</param-value>
</context-param>
<listener>
<listener-class>org.springframework.web.util.Log4jConfigListener</listener-class>
</listener>
<context-param>
<param-name>contextConfigLocation</param-name>
<param-value>/WEB-INF/deploy-context.xml</param-value>
</context-param>
<listener>
<listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
</listener>
<servlet>
<servlet-name>CXFServlet</servlet-name>
<servlet-class>org.apache.cxf.transport.servlet.CXFServlet</servlet-class>
<load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
<servlet-name>CXFServlet</servlet-name>
<url-pattern>/*</url-pattern>
</servlet-mapping>
</web-app>
Spring context file (deploy-context.xml)
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:jaxrs="http://cxf.apache.org/jaxrs"
xsi:schemaLocation="
http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd
http://cxf.apache.org/jaxrs
http://cxf.apache.org/schemas/jaxrs.xsd"
default-lazy-init="false">
<import resource="classpath:META-INF/cxf/cxf.xml" />
<import resource="classpath:META-INF/cxf/cxf-extension-jaxrs-binding.xml" />
<import resource="classpath:META-INF/cxf/cxf-servlet.xml" />
<jaxrs:server id="myService" address="/">
<jaxrs:serviceBeans>
<ref bean="serviceImpl" />
</jaxrs:serviceBeans>
<jaxrs:extensionMappings>
<entry key="xml" value="application/xml" />
</jaxrs:extensionMappings>
</jaxrs:server>
<bean id="serviceImpl" class="service.ServiceImpl" />
</beans>
User pojo
package pojo;
import javax.xml.bind.annotation.XmlRootElement;
@XmlRootElement(name = "user")
public class User {
private Integer id;
private String name;
public User() {
}
public User(Integer id, String name) {
this.id = id;
this.name = name;
}
public Integer getId() {
return id;
}
public void setId(Integer id) {
this.id = id;
}
public void setName(String name) {
this.name = name;
}
public String getName() {
return name;
}
@Override
public String toString() {
return String.format("{id=%s,name=%s}", id, name);
}
}
User DTO
package pojo;
import java.util.Collection;
import javax.xml.bind.annotation.XmlElement;
import javax.xml.bind.annotation.XmlElementWrapper;
import javax.xml.bind.annotation.XmlRootElement;
@XmlRootElement
public class UserCollection {
private Collection users;
public UserCollection() {
}
public UserCollection(Collection users) {
this.users = users;
}
@XmlElement(name="user")
@XmlElementWrapper(name="users")
public Collection getUsers() {
return users;
}
}
Service interface
package service;
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.core.Response;
import pojo.User;
import pojo.UserCollection;
public interface ServiceDefn {
UserCollection getUsers();
User getCustomer(Integer id);
Response getBadRequest();
}
Service implementation
package service;
import java.util.HashMap;
import java.util.Map;
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.Produces;
import javax.ws.rs.core.Response;
import javax.ws.rs.core.Response.Status;
import pojo.User;
import pojo.UserCollection;
@Path("/myservice/")
@Produces("application/xml")
public class ServiceImpl implements ServiceDefn {
private static Map users = new HashMap();
static {
users.put(1, new User(1, "foo"));
users.put(2, new User(2, "bar"));
users.put(3, new User(3, "baz"));
}
public ServiceImpl() {
}
@GET
@Path("/users")
@Override
public UserCollection getUsers() {
return new UserCollection(users.values());
}
@GET
@Path("/user/{id}")
@Override
public User getUser(@PathParam("id") Integer id) {
return users.get(id);
}
@GET
@Path("/users/bad")
@Override
public Response getBadRequest() {
return Response.status(Status.BAD_REQUEST).build();
}
}
REST Service
The following urls should now show the expected REST output.
http://localhost:8080/cxf-rest-example/myservice/users/http://localhost:8080/cxf-rest-example/myservice/user/1
Users REST output
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<userCollection>
<users>
<user>
<id>1</id>
<name>foo</name>
</user>
<user>
<id>2</id>
<name>bar</name>
</user>
<user>
<id>3</id>
<name>baz</name>
</user>
</users>
</userCollection>
Single user REST output
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<user>
<id>1</id>
<name>foo</name>
</user>
Discussion
It’s a little rough around the edges (the bad request call doesn’t respond in the expected fashion) but the REST service works using CXF 2.2-SNAPSHOT, JAXB 2.1.7, JAX-RS 1.0 and Spring 2.5.6. CXF can do a lot more but here I’ve created only a simple skeleton project. If you are using CXF 2.1 which supports JAX-RS 0.8 then this example will use @ProduceMime and @ConsumeMime instead of @Produces and @Consumes - a full migration list is provided by CXF. When I get a chance I’ll create an equivalent using Spring 3.0 - they’ve just released M1 which I’m hoping has REST.
The eclipse project is available for download. Build using mvn package. The maven build file automatically cleans before build and skips tests. To compile on Mac OS X you must tell maven where Java lives.
Update: Made correction - removed all annotations from interface as not necessary for the purposes of this example.
Update2: [15/12/2008] Made user collection rest xml a bit more semantic by fixing singular and plurals.
Questions
If anyone knows how to enable xml formatting in the jaxb marshalling output when using cxf please let me know. I know how to do this in jaxb but because the use of jaxb and its marshaller is embedded within cxf it is not immediately clear how this would be done.
Has this been helpful to you? Please say so. What other topics would you like to see? Let me know and I’ll do my best.
Standard Entity Providers
Update3 [25/12/2008]: In comment #1 to this post Victor asked why it is not necessary to implement MessageBodyReader or MessageBodyWriter and annotate with @Provider which are types from the api of the jax-rs 1.0 specification. In order to answer this, first, I quote the relevant section (4.2.4) of the jax-rs 1.0 specification. The CXF manual also sheds much light on what it supports and how.
An implementation MUST include pre-packaged MessageBodyReader and MessageBodyWriter implementations for the following Java and media type combinations:
- byte[] All media types (*/*).
- java.lang.String All media types (*/*).
- java.io.InputStream All media types (*/*).
- java.io.Reader All media types (*/*).
- java.io.File All media types (*/*).
- javax.activation.DataSource All media types (*/*).
- javax.xml.transform.Source XML types (text/xml, application/xml and application/*+xml).
- javax.xml.bind.JAXBElement and application-supplied JAXB classes XML media types (text/xml, application/xml and application/*+xml).
- MultivaluedMap Form content (application/x-www-form-urlencoded).
- StreamingOutput All media types (*/*), MessageBodyWriter only.
As the spec says above a jax-rs implementation must provide reader and writer implementations for the above types out of the box and ready to use which cxf does provide. It is only necessary to implement a reader or writer if you want to support a custom type or would like to provide a more efficient implementation of an existing type but luckily most of the work has already been done for you. If you look at the cxf source you’ll see provider implementations for the above minimum set of types already as below.
$ ls -1 Downloads/apache-cxf-2.2-SNAPSHOT-src/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/provider/ AbstractAegisProvider.java AbstractConfigurableProvider.java AbstractJAXBProvider.java AegisElementProvider.java AtomEntryProvider.java AtomFeedProvider.java BinaryDataProvider.java FormEncodingReaderProvider.java FormValidator.java JAXBElementProvider.java JSONProvider.java Messages.properties PrimitiveTextProvider.java ProviderFactory.java SourceProvider.java StringProvider.java XMLBeanStreamSerializer.java XMLBeansElementProvider.java XMLBeansJSONProvider.java
With particular reference to jaxb as a data binding technology the specification also mentions the following.
The implementation-supplied entity provider(s) for javax.xml.bind.JAXBElement and application supplied JAXB classes MUST use JAXBContextinstances provided by application-supplied context resolvers, see section 4.3. If an application does not supply a JAXBContext for a particular type, the implementation-supplied entity provider MUST use its own default context instead. [...]. An implementation MUST support application-provided entity providers and MUST use those in preference to its own pre-packaged providers when either could handle the same request.
The crux of it is that if you supply a JAXBContextResolver then CXF will use it otherwise it will create its own. An example JAXBContextResolver is provided below.
package context;
import javax.ws.rs.ext.ContextResolver;
import javax.ws.rs.ext.Provider;
import javax.xml.bind.JAXBContext;
import javax.xml.bind.JAXBException;
@Provider
public class JAXBContextResolver implements ContextResolver {
private final static String annotatedPackages = "pojo";
private final static JAXBContext context = initContext();
private static JAXBContext initContext() {
JAXBContext context = null;
try {
context = JAXBContext.newInstance(annotatedPackages);
} catch (JAXBException e) {
throw new RuntimeException(e);
}
return context;
}
@Override
public JAXBContext getContext(Class clazz) {
return context;
}
}
The specification mentions that an implementation must detect automatically any classes which are annotated as providers. However CXF does not yet support it and expresses a definite preference for explicit definition of providers as below.
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:jaxrs="http://cxf.apache.org/jaxrs"
xsi:schemaLocation="
http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd
http://cxf.apache.org/jaxrs
http://cxf.apache.org/schemas/jaxrs.xsd"
default-lazy-init="false">
<import resource="classpath:META-INF/cxf/cxf.xml" />
<import resource="classpath:META-INF/cxf/cxf-extension-jaxrs-binding.xml" />
<import resource="classpath:META-INF/cxf/cxf-servlet.xml" />
<jaxrs:server id="myService" address="/">
<jaxrs:serviceBeans>
<ref bean="serviceImpl" />
</jaxrs:serviceBeans>
<jaxrs:providers>
<ref bean="jaxbContextResolver" />
</jaxrs:providers>
</jaxrs:server>
<bean id="jaxbContextResolver" class="context.JAXBContextResolver" />
<bean id="serviceImpl" class="service.ServiceImpl" />
</beans>
However it seems that CXF does not in fact recognise the provider even with this configuration and I’m still trying to work out why. It would be nice to provide one’s own context and one’s own marshaller properties. This is left as a task for the reader for the time being and I’ll also continue to look into it.
1611
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
