Java Doc for AttachmentPart.java in  » Web-Services-AXIS2 » saaj » javax » xml » soap » Java Source Code / Java DocumentationJava Source Code and Java Documentation

A single attachment to a SOAPMessage object. A SOAPMessage object may contain zero, one, or many AttachmentPart objects. Each AttachmentPart object consists of two parts, application-specific content and associated MIME headers. The MIME headers consists of name/value pairs that can be used to identify and describe the content.

An AttachmentPart object must conform to certain standards.

1. It must conform to MIME [RFC2045] standards
2. It MUST contain content
3. The header portion MUST include the following header:
   • Content-Type
     This header identifies the type of data in the content of an AttachmentPart object and MUST conform to [RFC2045]. The following is an example of a Content-Type header:

      Content-Type:  application/xml
      
     
      

     The following line of code, in which ap is an AttachmentPart object, sets the header shown in the previous example.

      ap.setMimeHeader("Content-Type",
      "application/xml");
      
     
      

There are no restrictions on the content portion of an AttachmentPart object. The content may be anything from a simple plain text object to a complex XML document or image file.

An AttachmentPart object is created with the method SOAPMessage.createAttachmentPart. After setting its MIME headers, the AttachmentPart object is added to the message that created it with the method SOAPMessage.addAttachmentPart.

The following code fragment, in which m is a SOAPMessage object and contentStringl is a String, creates an instance of AttachmentPart, sets the AttachmentPart object with some content and header information, and adds the AttachmentPart object to the SOAPMessage object.

 AttachmentPart ap1 = m.createAttachmentPart(); ap1.setContent(contentString1,
 "text/plain"); m.addAttachmentPart(ap1); 

The following code fragment creates and adds a second AttachmentPart instance to the same message. jpegData is a binary byte buffer representing the jpeg file.

 AttachmentPart ap2 = m.createAttachmentPart(); byte[] jpegData =  ...; ap2.setContent(new
 ByteArrayInputStream(jpegData), "image/jpeg"); m.addAttachmentPart(ap2); 

The getContent method retrieves the contents and header from an AttachmentPart object. Depending on the DataContentHandler objects present, the returned Object can either be a typed Java object corresponding to the MIME type or an InputStream object that contains the content as bytes.

 String content1 = ap1.getContent(); java.io.InputStream content2 = ap2.getContent(); 

 ap1.clearContent(); 

Note that RFC822 headers can contain only US-ASCII characters.

For the MIME content types "text/plain", "text/html" and "text/xml", the DataContentHandler object does the conversions to and from the Java types corresponding to the MIME types. For other MIME types,the DataContentHandler object can return an InputStream object that contains the content data as raw bytes.

A JAXM-compliant implementation must, as a minimum, return a java.lang.String object corresponding to any content stream with a Content-Type value of text/plain, a javax.xml.transform.StreamSource object corresponding to a content stream with a Content-Type value of text/xml, a java.awt.Image object corresponding to a content stream with a Content-Type value of image/gif or image/jpeg. For those content types that an installed DataContentHandler object does not understand, the DataContentHandler object is required to return a java.io.InputStream object with the raw bytes. a Java object with the content of this AttachmentPart object
throws:
  SOAPException - if there is no content set into this AttachmentPart objector if there was a data transformation error

Note that RFC822 headers can only contain US-ASCII characters.