This article was originally published as a Web services e-newsletter.

As a rule, Web services are usually built to move data in XML format. It’s easy enough to format, say, a purchase order as XML, but what about more complex types of data, such as a slide presentation or even a single image? Let’s look at how you can transmit files to your Web service using the Apache SOAP implementation.

A simple scenario: A file archive service
My Web service in this case is an archival system that stores files on a server. As a simple example, it’s okay, but in a real-world scenario, you might implement something this trivial using FTP. Within my example, I’ll create the service class that will accept an incoming file and store it on the server. I’ll also create a client class that can make calls to the Web service.

The archival service is implemented as a class called ArchiveService. This class is composed of a single method, StoreFile, which takes two parameters: a filename and a DataHandler object. The filename is obviously used to transmit the name of the file, while the DataHandler is responsible for transmission of the file contents. Listing A shows the file used to create the class.

When the StoreFile method is called, the incoming file contained in the DataHandler object is written to a particular location on the server (in this case, the C:\wsfiles directory). Then, a message is sent back to the client acknowledging receipt of the file.

The ArchiveClient
The ArchiveClient class is a little more complex than the service, as you can see in Listing B. This class uses the normal SOAP client setup, based around the Call object. The main difference is that here, I’m using a DataHandler to store the file data. The file contents are actually loaded into a DataSource object, which is used to create a new DataHandler. Then, I pass the DataHandler to the ArchiveService’s StoreFile method as a parameter.

The magic DataHandler
The DataHandler object really performs the magic in this example, because the Java Activation Framework provides serialization and deserialization of the data and attaches it automatically to the SOAP message. Your file data isn’t passed directly in the XML for the SOAP envelope, but rather as a reference to an attachment. The entire SOAP request is sent as a multipart MIME-encoded request. The first part is the SOAP envelope, and the second part is the attachment. This is basically the same format that allows you to send attachments in e-mail messages. When the server receives the multipart request, it automatically understands how to find the referenced attachments and make them available to the SOAP service.

From my examples, you can see how easy Apache SOAP makes it to send and receive files to and from a Web service. Though the examples I used here may be trivial, I’m sure you can easily come up with more interesting applications for this technique.