Handling multiparts in Restful applications using CXF

Sergey recently implemented multipart support for CXF JAXRS implementation which is available in 2.2-SNAPSHOT. He talks more about the feature in his blog here. It certainly provides a simpler programming model like any other CXF frontends, which I always liked with the CXF project and prime reason for its growing popularity among developers. It supports multipart/related, multipart/alternative, multipart/mixed and multipart/form-data out-of-the-box. I gave it a spin and programming multiparts in CXF was like a piece of cake and you would know why by looking at the code shortly. The ability to reuse your code across SOAP and REST is the key differentiator for CXF when compared to Jersey and RESTEasy. I will leave this discussion for another blog post.

I will be reusing the same example which I used in my earlier blog entry for describing Jersey multiparts.

In this sample, I used the brand new HttpClient 4.0 API as the REST client for invoking restful services, as CXF does not ship one yet. HttpClient 4.0 API is completely redesigned and addresses most of the architectural shortcomings from its previous releases, and this version is not backwards compatible.

Here is my maven dependencies:

    
        
            org.apache.cxf
            cxf-rt-frontend-jaxrs
            2.2
        

        
            org.apache.cxf
            cxf-rt-transports-http-jetty
            2.2
        

        
            org.apache.httpcomponents
            httpclient
            4.0-beta2
        

        
            org.apache.httpcomponents
            httpmime
            4.0-beta2
        
    

Here is the Multipart resource, which processes two body parts and returns the entity with the rank set on the Project bean.

import org.apache.cxf.helpers.IOUtils;
import org.apache.cxf.io.CachedOutputStream;
import org.apache.cxf.jaxrs.ext.multipart.Attachment;
import org.apache.cxf.jaxrs.ext.multipart.MultipartBody;

import javax.activation.DataHandler;
import javax.ws.rs.*;
import javax.ws.rs.core.Response;
import javax.ws.rs.core.MediaType;
import javax.xml.bind.JAXBContext;
import javax.xml.bind.Unmarshaller;
import java.io.InputStream;
import java.util.List;

@Path("/multipart")
public class MultipartResource {
    @POST
    @Consumes(MediaType.MULTIPART_FORM_DATA)
    @Produces(MediaType.APPLICATION_XML)
    public Response processMultiparts(MultipartBody multipartBody) {
        List attachments = multipartBody.getAllAttachments();
        DataHandler dataHandler1 = attachments.get(0).getDataHandler();
        DataHandler dataHandler2 = attachments.get(1).getDataHandler();
        Project project = null;
        try {
            project = getProjectFromInputStream(dataHandler1.getInputStream());
            System.out.println("Processing Attachment 1 ...");
            System.out.println("name : " + project.getName());
            System.out.println("description : " + project.getDescription());
            System.out.println("license : " + project.getLicense());
            System.out.println("SVN URL : " + project.getSvnURL());
            System.out.println("homepage : " + project.getHomepage());

            System.out.println("Processing Attachment 2 ...");
            String comment = getStringFromInputStream(dataHandler2.getInputStream());
            System.out.println("Comment : " + comment);

        } catch (Exception e) {
            throw new WebApplicationException(500);
        }
        return Response.ok(project).build();
    }

    public static Project getProjectFromInputStream(InputStream is) throws Exception {
        JAXBContext c = JAXBContext.newInstance(new Class[]{Project.class});
        Unmarshaller u = c.createUnmarshaller();
        Project project = (Project) u.unmarshal(is);
        project.setRank(1);
        return project;
    }

    public static String getStringFromInputStream(InputStream in) throws Exception {
        CachedOutputStream bos = new CachedOutputStream();
        IOUtils.copy(in, bos);
        in.close();
        bos.close();
        return bos.getOut().toString();
    }

}

Start the Jetty based CXF JAXRS server which deploys the multipart resource as a singleton.

public class CXFRestServer {
    public static void main(String[] args) {
        JAXRSServerFactoryBean sf = new JAXRSServerFactoryBean();
        sf.setResourceClasses(MultipartResource.class);
        sf.setResourceProvider(MultipartResource.class,
                new SingletonResourceProvider(new MultipartResource()));
        sf.setAddress("http://localhost:8081/");
        sf.create();
        System.out.println("Server started.");
    }
}

HttpClient APIs are used to POST the multipart entites to the CXF multipart resource. The first part is a XML File and the second part is a String content. Finally, it processes the response received from the resource.

public class TestClient {

    public static void main(String[] args) throws Exception {
        HttpClient httpclient = new DefaultHttpClient();
        HttpPost httppost = new HttpPost("http://localhost:8081/multipart");
        FileBody bin = new FileBody(new File(TestClient.class.getResource("/project_summary.xml").getFile()));
        StringBody comment = new StringBody("Project summary.");

        MultipartEntity reqEntity = new MultipartEntity();
        reqEntity.addPart("project", bin);
        reqEntity.addPart("comment", comment);

        httppost.setEntity(reqEntity);

        System.out.println("executing request " + httppost.getRequestLine());
        HttpResponse response = httpclient.execute(httppost);
        HttpEntity resEntity = response.getEntity();

        System.out.println("---------------------------------------------------------------");
        System.out.println(response.getStatusLine());
        if (resEntity != null) {
            System.out.println("Response content length: " + resEntity.getContentLength());
            System.out.println("Response content type: " + resEntity.getContentType().getValue());
            System.out.println("Project Rank : " + MultipartResource.getProjectFromInputStream(resEntity.getContent()).getRank());
        }
        if (resEntity != null) {            
            resEntity.consumeContent();
        }
    }
}

Place project_summary.xml in your root classpath.

    CXF
    Apache CXF is an open source services framework.
    http://cxf.apache.org
    ASL 2.0
    http://svn.apache.org/repos/asf/cxf/trunk/

This is just one approach of doing multiparts with CXF JAXRS implementation. You can dig into the unit tests to see all possible approaches to handle multiparts with in restful resources. HttpClient 4.0 API is cleaner and flexible and could potentially become a standard API for accessing RESTful web services in Java.

Update (4/11): The sample is updated to use the 2.2 release. The sources can be downloaded from here.