| 
 | J2EE1.4 SDK | |||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
java.lang.Objectjavax.xml.soap.AttachmentPart
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.
 
Content-TypeAttachmentPart 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();
 
 The method clearContent removes all the content from an
 AttachmentPart object but does not affect its header information.
 
     ap1.clearContent();
 
| Constructor Summary | |
| AttachmentPart() | |
| Method Summary | |
| abstract  void | addMimeHeader(java.lang.String name,
              java.lang.String value)Adds a MIME header with the specified name and value to this AttachmentPartobject. | 
| abstract  void | clearContent()Clears out the content of this AttachmentPartobject. | 
| abstract  java.util.Iterator | getAllMimeHeaders()Retrieves all the headers for this AttachmentPartobject
 as an iterator over theMimeHeaderobjects. | 
| abstract  java.lang.Object | getContent()Gets the content of this AttachmentPartobject as a Java
 object. | 
|  java.lang.String | getContentId()Gets the value of the MIME header whose name is "Content-Id". | 
|  java.lang.String | getContentLocation()Gets the value of the MIME header whose name is "Content-Location". | 
|  java.lang.String | getContentType()Gets the value of the MIME header whose name is "Content-Type". | 
| abstract  DataHandler | getDataHandler()Gets the DataHandlerobject for thisAttachmentPartobject. | 
| abstract  java.util.Iterator | getMatchingMimeHeaders(java.lang.String[] names)Retrieves all MimeHeaderobjects that match a name in
 the given array. | 
| abstract  java.lang.String[] | getMimeHeader(java.lang.String name)Gets all the values of the header identified by the given String. | 
| abstract  java.util.Iterator | getNonMatchingMimeHeaders(java.lang.String[] names)Retrieves all MimeHeaderobjects whose name does
 not match a name in the given array. | 
| abstract  int | getSize()Returns the number of bytes in this AttachmentPartobject. | 
| abstract  void | removeAllMimeHeaders()Removes all the MIME header entries. | 
| abstract  void | removeMimeHeader(java.lang.String header)Removes all MIME headers that match the given name. | 
| abstract  void | setContent(java.lang.Object object,
           java.lang.String contentType)Sets the content of this attachment part to that of the given Objectand sets the value of theContent-Typeheader to the given type. | 
|  void | setContentId(java.lang.String contentId)Sets the MIME header whose name is "Content-Id" with the given value. | 
|  void | setContentLocation(java.lang.String contentLocation)Sets the MIME header whose name is "Content-Location" with the given value. | 
|  void | setContentType(java.lang.String contentType)Sets the MIME header whose name is "Content-Type" with the given value. | 
| abstract  void | setDataHandler(DataHandler dataHandler)Sets the given DataHandlerobject as the data handler
 for thisAttachmentPartobject. | 
| abstract  void | setMimeHeader(java.lang.String name,
              java.lang.String value)Changes the first header entry that matches the given name to the given value, adding a new header if no existing header matches. | 
| Methods inherited from class java.lang.Object | 
| clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait | 
| Constructor Detail | 
public AttachmentPart()
| Method Detail | 
public abstract int getSize()
                     throws SOAPException
AttachmentPart
 object.
AttachmentPart object in bytes
         or -1 if the size cannot be determined
SOAPException - if the content of this attachment is
            corrupted of if there was an exception while trying
            to determine the size.public abstract void clearContent()
AttachmentPart object.
 The MIME header portion is left untouched.
public abstract java.lang.Object getContent()
                                     throws SOAPException
AttachmentPart object as a Java
 object. The type of the returned Java object depends on (1) the
 DataContentHandler object that is used to interpret the bytes
 and (2) the Content-Type given in the header.
 
 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.
AttachmentPart
         object
SOAPException - if there is no content set into this
            AttachmentPart object or if there was a data
            transformation error
public abstract void setContent(java.lang.Object object,
                                java.lang.String contentType)
Object and sets the value of the Content-Type
 header to the given type. The type of the
 Object should correspond to the value given for the
 Content-Type. This depends on the particular
 set of DataContentHandler objects in use.
object - the Java object that makes up the content for
               this attachment partcontentType - the MIME string that specifies the type of
                  the content
java.lang.IllegalArgumentException - if the contentType does not
            match the type of the content object, or if there
            was no DataContentHandler object for this
            content objectgetContent()
public abstract DataHandler getDataHandler()
                                    throws SOAPException
DataHandler object for this AttachmentPart
 object.
DataHandler object associated with this
         AttachmentPart object
SOAPExceptionAttachmentPart object
SOAPExceptionpublic abstract void setDataHandler(DataHandler dataHandler)
DataHandler object as the data handler
 for this AttachmentPart object. Typically, on an incoming
 message, the data handler is automatically set. When
 a message is being created and populated with content, the
 setDataHandler method can be used to get data from
 various data sources into the message.
dataHandler - the DataHandler object to be set
java.lang.IllegalArgumentException - if there was a problem with
            the specified DataHandler objectpublic java.lang.String getContentId()
String giving the value of the
          "Content-Id" header or null if there
          is nonesetContentId(java.lang.String)public java.lang.String getContentLocation()
String giving the value of the
          "Content-Location" header or null if there
          is nonepublic java.lang.String getContentType()
String giving the value of the
          "Content-Type" header or null if there
          is nonepublic void setContentId(java.lang.String contentId)
contentId - a String giving the value of the
          "Content-Id" header
java.lang.IllegalArgumentException - if there was a problem with
            the specified contentId valuegetContentId()public void setContentLocation(java.lang.String contentLocation)
contentLocation - a String giving the value of the
          "Content-Location" header
java.lang.IllegalArgumentException - if there was a problem with
            the specified content locationpublic void setContentType(java.lang.String contentType)
contentType - a String giving the value of the
          "Content-Type" header
java.lang.IllegalArgumentException - if there was a problem with
            the specified content typepublic abstract void removeMimeHeader(java.lang.String header)
header - the string name of the MIME header/s to
               be removedpublic abstract void removeAllMimeHeaders()
public abstract java.lang.String[] getMimeHeader(java.lang.String name)
String.
name - the name of the header; example: "Content-Type"
String array giving the value for the
         specified headersetMimeHeader(java.lang.String, java.lang.String)
public abstract void setMimeHeader(java.lang.String name,
                                   java.lang.String value)
Note that RFC822 headers can only contain US-ASCII characters.
name - a String giving the name of the header 
                  for which to searchvalue - a String giving the value to be set for
                  the header whose name matches the given name
java.lang.IllegalArgumentException - if there was a problem with
            the specified mime header name or value
public abstract void addMimeHeader(java.lang.String name,
                                   java.lang.String value)
AttachmentPart object.
 Note that RFC822 headers can contain only US-ASCII characters.
name - a String giving the name of the header 
                  to be addedvalue - a String giving the value of the header 
                  to be added
java.lang.IllegalArgumentException - if there was a problem with
            the specified mime header name or valuepublic abstract java.util.Iterator getAllMimeHeaders()
AttachmentPart object
 as an iterator over the MimeHeader objects.
Iterator object with all of the Mime
          headers for this AttachmentPart objectpublic abstract java.util.Iterator getMatchingMimeHeaders(java.lang.String[] names)
MimeHeader objects that match a name in
 the given array.
names - a String array with the name(s) of the
        MIME headers to be returned
Iterator objectpublic abstract java.util.Iterator getNonMatchingMimeHeaders(java.lang.String[] names)
MimeHeader objects whose name does
 not match a name in the given array.
names - a String array with the name(s) of the
        MIME headers not to be returned
AttachmentPart object
          except those that match one of the names in the
           given array.  The nonmatching MIME headers are returned as an 
           Iterator object.| 
 | J2EE1.4 SDK | |||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
Copyright 2003 Sun Microsystems, Inc. All rights reserved.