Java Doc for AttachmentPart.java in  » 6.0-JDK-Modules » saaj » javax » xml » soap » Java Source Code / Java DocumentationJava Source Code and Java Documentation

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 reading from the returned InputStream would result in consuming the data in the stream.

Note that RFC822 headers can contain only US-ASCII characters.
Parameters:
  name - a String giving the name of the header to be added
Parameters:
  value - a String giving the value of the header to be added
exception:
  IllegalArgumentException - if there was a problem withthe specified mime header name or value

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 SAAJ-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.stream.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 AttachmentPartobject
exception:
  SOAPException - if there is no content set into thisAttachmentPart object or if there was a datatransformation error

Note that reading from the returned InputStream would result in consuming the data in the stream. It is the responsibility of the caller to reset the InputStream appropriately before calling a Subsequent API. If a copy of the raw attachment content is required then the AttachmentPart.getRawContentBytes API should be used instead. an InputStream from which the raw data contained bythe AttachmentPart can be accessed.
throws:
  SOAPException - if there is no content set into this AttachmentPart object or if there was a data transformation error.
since:
   SAAJ 1.3
See Also:   AttachmentPart.getRawContentBytes

A subsequent call to getSize() may not be an exact measure of the content size.
Parameters:
  content - the base64 encoded data to add to the attachment part
Parameters:
  contentType - the value to set into the Content-Type header
exception:
  SOAPException - if an there is an error in setting the content
exception:
  NullPointerException - if content is null
since:
   SAAJ 1.3

Note that RFC822 headers can only contain US-ASCII characters.
Parameters:
  name - a String giving the name of the header for which to search
Parameters:
  value - a String giving the value to be set forthe header whose name matches the given name
exception:
  IllegalArgumentException - if there was a problem withthe specified mime header name or value

A subsequent call to getSize() may not be an exact measure of the content size.
Parameters:
  content - the raw data to add to the attachment part
Parameters:
  contentType - the value to set into the Content-Type header
exception:
  SOAPException - if an there is an error in setting the content
exception:
  NullPointerException - if content is null
since:
   SAAJ 1.3