The SOAP messaging protocol allows you to send MIME attachments viaSOAP messages. WSDL provides a description of these attachments.JAX-RPC provides a mapping of the WSDL description of attachments intoJava artifacts. This tip describes how to use those JAX-RPC mappings tosend attachments in SOAP messages.
The WSDL description of attachments is, unfortunately, not particularly straightforward. Take a look at the WSDL in Listing 1, particularly the highlighted elements of the binding.
<?xml version="1.0" encoding="utf-8"?> <definitions xmlns="http://schemas.xmlsoap.org/wsdl/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/" targetNamespace="urn:attachment.tip" xmlns:tns="urn:attachment.tip"> <message name="empty"/> <message name="imageMsg"> <part name="image" type="xsd:hexBinary"/> </message> <message name="octetMsg"> <part name="octet" type="xsd:hexBinary"/> </message> <portType name="AttachmentTip"> <operation name="sendImage"> <input message="tns:imageMsg"/> <output message="tns:empty"/> </operation> <operation name="sendOctet"> <input message="tns:octetMsg"/> <output message="tns:empty"/> </operation> </portType> <binding name="AttachmentBinding" type="tns:AttachmentTip"> <soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/> <operation name="sendImage"> <soap:operation soapAction=""/> <input> <mime:multipartRelated> <mime:part> <soap:body use="literal"/> </mime:part> <mime:part> <mime:content part="image" type="image/jpeg"/> </mime:part> </mime:multipartRelated> </input> <output> <soap:body use="literal"/> </output> </operation> <operation name="sendOctet"> <soap:operation soapAction=""/> <input> <mime:multipartRelated> <mime:part> <soap:body use="literal"/> </mime:part> <mime:part> <mime:content part="octet" type="application/octet-stream"/> </mime:part> </mime:multipartRelated> </input> <output> <soap:body use="literal"/> </output> </operation> </binding> <service name="AttachmentService"> <port name="AttachmentTip" binding="tns:AttachmentBinding"> <soap:address location="http://localhost:9080/attachment/services/AttachmentTip"/> </port> </service> </definitions> |
Thefirst thing to note is that there is no MIME information until you getall the way down to the binding. If you ignore the binding for a momentand only look at the WSDL's 'interface' (portType and messages), you'llsee two operations - sendImage and sendOctet. Each of these has a hexBinary input. hexBinary maps to byte[].Using only this information, you could reasonably guess that thisportType would map to a Java language Service Endpoint Interface (SEI)which would have two methods, each of which would have a single byte[]parameter. This is a good guess, and for anything but MIME types,you'd be correct. But for MIME types you must inspect the binding todetermine the real parameter types.
In the binding you'll see that the inputs for the operations are really MIME content types -- image/jpeg and application/octet-stream -- instead of hexBinary. JAX-RPC defines these to map to java.awt.Image and javax.activation.DataHandler, respectively.
The Service Endpoint Interface
Listing 2 contains a Java language SEI generated from the WSDL in Listing 1.
package tip.attachment; import java.awt.Image; import java.rmi.Remote; import java.rmi.RemoteException; import javax.activation.DataHandler; public interface AttachmentTip extends Remote { public void sendImage(Image image) throws RemoteException; public void sendOctet(DataHandler octet) throws RemoteException; } |
The WSDL's sendImage operation, which the binding says has a MIME content of image/jpeg, becomes a Java program method with a java.awt.Image parameter. Very straightforward. Nice and tidy. Table 1 lists all of the nice-and-tidy mappings of MIME types to Java types.
| MIME Type | Java Type |
| image/gif, image/jpeg | java.awt.Image |
| text/plain | java.lang.String |
| multipart/* | javax.mail.internet.MimeMultipart |
| text/xml, application/xml | javax.xml.transform.Source |
If you define a MIME type that is not in this table, as I did in the sendOctet operation, then a JAX-RPC implementation will map your type to javax.activation.DataHandler. The DataHandler type is defined in the Java Activation Framework (JAF -- see more details below, and also a link to the JAF pages in the Resources section).
Fromthis point on, I assume that you have used your favorite JAX-RPCimplementation to generate all the client-side mappings from theAttachmentTip WSDL. The client implementation will depend on thesemappings, particularly the AttachmentTip SEI from Listing 2.
Theclient implementation of attachments must first acquire animplementation of the SEI from a Service. You can see how this is donein Listing 3 in the getTip method (a discussion of the ServiceFactory and Service is beyond the scope of this tip, see Resources for more information).
Onceyou have an SEI implementation, you can call its methods with yourattachment (which for this example is in a file whose name you provide).In the case of sendImage, that attachment is a java.awt.Image.That's all there is to it. The JAX-RPC implementation knows that allimages are sent as attachments and it constructs the SOAP messageaccordingly. The client programmer need not even be aware thatattachments are involved. See the highlighted code in Listing 3 for the call to sendImage.
package tip.attachment; import java.awt.Image; import java.awt.Toolkit; import java.net.URL; import java.rmi.RemoteException; import javax.xml.namespace.QName; import javax.xml.rpc.Service; import javax.xml.rpc.ServiceFactory; public class AttachmentTipClient { static AttachmentTip getTip() throws Exception { QName serviceName = new QName( "urn:attachment.tip", "AttachmentService"); URL wsdlLocation = new URL( "http://localhost:9080/attachment/services/AttachmentTip?wsdl"); ServiceFactory factory = ServiceFactory.newInstance(); Service service = factory.createService(wsdlLocation, serviceName); QName portName = new QName("", "AttachmentTip"); return (AttachmentTip) service.getPort( portName, AttachmentTip.class); } static void sendImage(AttachmentTip tip, String fileName) throws RemoteException { Toolkit toolkit = Toolkit.getDefaultToolkit(); Image image = toolkit.createImage(fileName); tip.sendImage(image); } public static void main(String[] args) { try { AttachmentTip tip = getTip(); sendImage(tip, args[0]); } catch (Throwable t) { t.printStackTrace(); } } } |
Forthose few MIME types for which JAX-RPC has defined a mapping (see Table1), life is fairly easy. For those MIME types for which there is noexplicit JAX-RPC mapping, you're left with a javax.activation.DataHandler object. This class is part of the Java Activation Framework (JAF -- see Resources), so you have to know something about the JAF, but it's not too difficult. A DataHandler contains a javax.activation.DataSourcewhich, in turn, contains input and output streams. Most Javaprogramming types can be converted fairly easily to/from streams, sothis is fairly straightforward. Moreover, the activation frameworkitself even helps a little. If your attachment data is in a file, asthis one is, the activation framework provides the javax.activation.FileDataSource class, so you can bypass the stream step. Listing 4 is the code from Listing 3 with the addition of a new method to call sendOctet and pass it a DataHandler.
package tip.attachment; import java.awt.Image; import java.awt.Toolkit; import java.net.URL; import java.rmi.RemoteException; import javax.activation.DataHandler; import javax.activation.FileDataSource; import javax.xml.namespace.QName; import javax.xml.rpc.Service; import javax.xml.rpc.ServiceFactory; public class AttachmentTipClient { static AttachmentTip getTip() throws Exception { QName serviceName = new QName( "urn:attachment.tip", "AttachmentService"); URL wsdlLocation = new URL( "http://localhost:9080/attachment/services/AttachmentTip?wsdl"); ServiceFactory factory = ServiceFactory.newInstance(); Service service = factory.createService(wsdlLocation, serviceName); QName portName = new QName("", "AttachmentTip"); return (AttachmentTip) service.getPort( portName, AttachmentTip.class); } static void sendImage(AttachmentTip tip, String fileName) throws RemoteException { Toolkit toolkit = Toolkit.getDefaultToolkit(); Image image = toolkit.createImage(fileName); tip.sendImage(image); } static void sendOctet(AttachmentTip tip, String fileName) throws RemoteException { FileDataSource fds = new FileDataSource(fileName); DataHandler dh = new DataHandler(fds); tip.sendOctet(dh); } public static void main(String[] args) { try { AttachmentTip tip = getTip(); sendImage(tip, args[0]); sendOctet(tip, args[0]); } catch (Throwable t) { t.printStackTrace(); } } } |
Note that I used the same file as the data for both attachment operations, but as far as sendOctet is concerned, the contents of the file is merely an application/octet-stream. It doesn't know, or care, that it's really an image. application/octet-stream is the default content type for FileDataSource,which is why I used it. It did everything for me. If you aren't solucky to have your data in a file, and you have to send it as somethingother than an application/octet-stream, then you have to create your own implementation of DataSource, but it's a simple interface, so it shouldn't take too much effort. (This is left as an exercise to the reader!)
聯(lián)系客服
