Home » xml-commons-external-1.4.01-src » javax » xml » soap » [javadoc | source]

    1   /*
    2    * Copyright 2005-2006 Sun Microsystems, Inc.  All Rights Reserved.
    3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
    4    *
    5    * This code is free software; you can redistribute it and/or modify it
    6    * under the terms of the GNU General Public License version 2 only, as
    7    * published by the Free Software Foundation.  Sun designates this
    8    * particular file as subject to the "Classpath" exception as provided
    9    * by Sun in the LICENSE file that accompanied this code.
   10    *
   11    * This code is distributed in the hope that it will be useful, but WITHOUT
   12    * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
   13    * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
   14    * version 2 for more details (a copy is included in the LICENSE file that
   15    * accompanied this code).
   16    *
   17    * You should have received a copy of the GNU General Public License version
   18    * 2 along with this work; if not, write to the Free Software Foundation,
   19    * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
   20    *
   21    * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
   22    * CA 95054 USA or visit www.sun.com if you need additional information or
   23    * have any questions.
   24    */
   25   /*
   26    * $Id: AttachmentPart.java,v 1.13 2006/03/30 00:59:38 ofung Exp $
   27    * $Revision: 1.13 $
   28    * $Date: 2006/03/30 00:59:38 $
   29    */
   30   
   31   
   32   package javax.xml.soap;
   33   
   34   import java.io.InputStream;
   35   import java.io.Reader;
   36   import java.util.Iterator;
   37   
   38   import javax.activation.DataHandler;
   39   
   40   /**
   41    * A single attachment to a <code>SOAPMessage</code> object. A <code>SOAPMessage</code>
   42    * object may contain zero, one, or many <code>AttachmentPart</code> objects.
   43    * Each <code>AttachmentPart</code> object consists of two parts,
   44    * application-specific content and associated MIME headers. The
   45    * MIME headers consists of name/value pairs that can be used to
   46    * identify and describe the content.
   47    * <p>
   48    * An <code>AttachmentPart</code> object must conform to certain standards.
   49    * <OL>
   50    * <LI>It must conform to <a href="http://www.ietf.org/rfc/rfc2045.txt">
   51    *     MIME [RFC2045] standards</a>
   52    * <LI>It MUST contain content
   53    * <LI>The header portion MUST include the following header:
   54    *  <UL>
   55    *   <LI><code>Content-Type</code><br>
   56    *       This header identifies the type of data in the content of an
   57    *       <code>AttachmentPart</code> object and MUST conform to [RFC2045].
   58    *       The following is an example of a Content-Type header:
   59    *       <PRE>
   60    *       Content-Type:  application/xml
   61    *       </PRE>
   62    *       The following line of code, in which <code>ap</code> is an
   63    *       <code>AttachmentPart</code> object, sets the header shown in
   64    *       the previous example.
   65    *       <PRE>
   66    *       ap.setMimeHeader("Content-Type", "application/xml");
   67    *       </PRE>
   68    * <p>
   69    *  </UL>
   70    * </OL>
   71    * <p>
   72    * There are no restrictions on the content portion of an <code>
   73    * AttachmentPart</code> object. The content may be anything from a
   74    * simple plain text object to a complex XML document or image file.
   75    *
   76    * <p>
   77    * An <code>AttachmentPart</code> object is created with the method
   78    * <code>SOAPMessage.createAttachmentPart</code>. After setting its MIME headers,
   79    *  the <code>AttachmentPart</code> object is added to the message
   80    * that created it with the method <code>SOAPMessage.addAttachmentPart</code>.
   81    *
   82    * <p>
   83    * The following code fragment, in which <code>m</code> is a
   84    * <code>SOAPMessage</code> object and <code>contentStringl</code> is a
   85    * <code>String</code>, creates an instance of <code>AttachmentPart</code>,
   86    * sets the <code>AttachmentPart</code> object with some content and
   87    * header information, and adds the <code>AttachmentPart</code> object to
   88    * the <code>SOAPMessage</code> object.
   89    * <PRE>
   90    *     AttachmentPart ap1 = m.createAttachmentPart();
   91    *     ap1.setContent(contentString1, "text/plain");
   92    *     m.addAttachmentPart(ap1);
   93    * </PRE>
   94    *
   95    *
   96    * <p>
   97    * The following code fragment creates and adds a second
   98    * <code>AttachmentPart</code> instance to the same message. <code>jpegData</code>
   99    * is a binary byte buffer representing the jpeg file.
  100    * <PRE>
  101    *     AttachmentPart ap2 = m.createAttachmentPart();
  102    *     byte[] jpegData =  ...;
  103    *     ap2.setContent(new ByteArrayInputStream(jpegData), "image/jpeg");
  104    *     m.addAttachmentPart(ap2);
  105    * </PRE>
  106    * <p>
  107    * The <code>getContent</code> method retrieves the contents and header from
  108    * an <code>AttachmentPart</code> object. Depending on the
  109    * <code>DataContentHandler</code> objects present, the returned
  110    * <code>Object</code> can either be a typed Java object corresponding
  111    * to the MIME type or an <code>InputStream</code> object that contains the
  112    * content as bytes.
  113    * <PRE>
  114    *     String content1 = ap1.getContent();
  115    *     java.io.InputStream content2 = ap2.getContent();
  116    * </PRE>
  117    *
  118    * The method <code>clearContent</code> removes all the content from an
  119    * <code>AttachmentPart</code> object but does not affect its header information.
  120    * <PRE>
  121    *     ap1.clearContent();
  122    * </PRE>
  123    */
  124   
  125   public abstract class AttachmentPart {
  126       /**
  127        * Returns the number of bytes in this <code>AttachmentPart</code>
  128        * object.
  129        *
  130        * @return the size of this <code>AttachmentPart</code> object in bytes
  131        *         or -1 if the size cannot be determined
  132        * @exception SOAPException if the content of this attachment is
  133        *            corrupted of if there was an exception while trying
  134        *            to determine the size.
  135        */
  136       public abstract int getSize() throws SOAPException;
  137   
  138       /**
  139        * Clears out the content of this <code>AttachmentPart</code> object.
  140        * The MIME header portion is left untouched.
  141        */
  142       public abstract void clearContent();
  143   
  144       /**
  145        * Gets the content of this <code>AttachmentPart</code> object as a Java
  146        * object. The type of the returned Java object depends on (1) the
  147        * <code>DataContentHandler</code> object that is used to interpret the bytes
  148        * and (2) the <code>Content-Type</code> given in the header.
  149        * <p>
  150        * For the MIME content types "text/plain", "text/html" and "text/xml", the
  151        * <code>DataContentHandler</code> object does the conversions to and
  152        * from the Java types corresponding to the MIME types.
  153        * For other MIME types,the <code>DataContentHandler</code> object
  154        * can return an <code>InputStream</code> object that contains the content data
  155        * as raw bytes.
  156        * <p>
  157        * A SAAJ-compliant implementation must, as a minimum, return a
  158        * <code>java.lang.String</code> object corresponding to any content
  159        * stream with a <code>Content-Type</code> value of
  160        * <code>text/plain</code>, a
  161        * <code>javax.xml.transform.stream.StreamSource</code> object corresponding to a
  162        * content stream with a <code>Content-Type</code> value of
  163        * <code>text/xml</code>, a <code>java.awt.Image</code> object
  164        * corresponding to a content stream with a
  165        * <code>Content-Type</code> value of <code>image/gif</code> or
  166        * <code>image/jpeg</code>.  For those content types that an
  167        * installed <code>DataContentHandler</code> object does not understand, the
  168        * <code>DataContentHandler</code> object is required to return a
  169        * <code>java.io.InputStream</code> object with the raw bytes.
  170        *
  171        * @return a Java object with the content of this <code>AttachmentPart</code>
  172        *         object
  173        *
  174        * @exception SOAPException if there is no content set into this
  175        *            <code>AttachmentPart</code> object or if there was a data
  176        *            transformation error
  177        */
  178       public abstract Object getContent() throws SOAPException;
  179   
  180       /**
  181        * Gets the content of this <code>AttachmentPart</code> object as an
  182        * InputStream as if a call had been made to <code>getContent</code> and no
  183        * <code>DataContentHandler</code> had been registered for the
  184        * <code>content-type</code> of this <code>AttachmentPart</code>.
  185        *<p>
  186        * Note that reading from the returned InputStream would result in consuming
  187        * the data in the stream. It is the responsibility of the caller to reset
  188        * the InputStream appropriately before calling a Subsequent API. If a copy
  189        * of the raw attachment content is required then the {@link #getRawContentBytes} API
  190        * should be used instead.
  191        *
  192        * @return an <code>InputStream</code> from which the raw data contained by
  193        *      the <code>AttachmentPart</code> can be accessed.
  194        *
  195        * @throws SOAPException if there is no content set into this
  196        *      <code>AttachmentPart</code> object or if there was a data
  197        *      transformation error.
  198        *
  199        * @since SAAJ 1.3
  200        * @see #getRawContentBytes
  201        */
  202       public abstract InputStream getRawContent() throws SOAPException;
  203   
  204       /**
  205        * Gets the content of this <code>AttachmentPart</code> object as a
  206        * byte[] array as if a call had been made to <code>getContent</code> and no
  207        * <code>DataContentHandler</code> had been registered for the
  208        * <code>content-type</code> of this <code>AttachmentPart</code>.
  209        *
  210        * @return a <code>byte[]</code> array containing the raw data of the
  211        *      <code>AttachmentPart</code>.
  212        *
  213        * @throws SOAPException if there is no content set into this
  214        *      <code>AttachmentPart</code> object or if there was a data
  215        *      transformation error.
  216        *
  217        * @since SAAJ 1.3
  218        */
  219       public abstract byte[] getRawContentBytes() throws SOAPException;
  220   
  221       /**
  222        * Returns an <code>InputStream</code> which can be used to obtain the
  223        * content of <code>AttachmentPart</code>  as Base64 encoded
  224        * character data, this method would base64 encode the raw bytes
  225        * of the attachment and return.
  226        *
  227        * @return an <code>InputStream</code> from which the Base64 encoded
  228        *       <code>AttachmentPart</code> can be read.
  229        *
  230        * @throws SOAPException if there is no content set into this
  231        *      <code>AttachmentPart</code> object or if there was a data
  232        *      transformation error.
  233        *
  234        * @since SAAJ 1.3
  235        */
  236       public abstract InputStream getBase64Content() throws SOAPException;
  237   
  238       /**
  239        * Sets the content of this attachment part to that of the given
  240        * <code>Object</code> and sets the value of the <code>Content-Type</code>
  241        * header to the given type. The type of the
  242        * <code>Object</code> should correspond to the value given for the
  243        * <code>Content-Type</code>. This depends on the particular
  244        * set of <code>DataContentHandler</code> objects in use.
  245        *
  246        *
  247        * @param object the Java object that makes up the content for
  248        *               this attachment part
  249        * @param contentType the MIME string that specifies the type of
  250        *                  the content
  251        *
  252        * @exception IllegalArgumentException may be thrown if the contentType
  253        *            does not match the type of the content object, or if there
  254        *            was no <code>DataContentHandler</code> object for this
  255        *            content object
  256        *
  257        * @see #getContent
  258        */
  259       public abstract void setContent(Object object, String contentType);
  260   
  261       /**
  262        * Sets the content of this attachment part to that contained by the
  263        * <code>InputStream</code> <code>content</code> and sets the value of the
  264        * <code>Content-Type</code> header to the value contained in
  265        * <code>contentType</code>.
  266        * <P>
  267        *  A subsequent call to getSize() may not be an exact measure
  268        *  of the content size.
  269        *
  270        * @param content the raw data to add to the attachment part
  271        * @param contentType the value to set into the <code>Content-Type</code>
  272        * header
  273        *
  274        * @exception SOAPException if an there is an error in setting the content
  275        * @exception NullPointerException if <code>content</code> is null
  276        * @since SAAJ 1.3
  277        */
  278       public abstract void setRawContent(InputStream content, String contentType) throws SOAPException;
  279   
  280       /**
  281        * Sets the content of this attachment part to that contained by the
  282        * <code>byte[]</code> array <code>content</code> and sets the value of the
  283        * <code>Content-Type</code> header to the value contained in
  284        * <code>contentType</code>.
  285        *
  286        * @param content the raw data to add to the attachment part
  287        * @param contentType the value to set into the <code>Content-Type</code>
  288        * header
  289        * @param offset the offset in the byte array of the content
  290        * @param len the number of bytes that form the content
  291        *
  292        * @exception SOAPException if an there is an error in setting the content
  293        * or content is null
  294        * @since SAAJ 1.3
  295        */
  296       public abstract void setRawContentBytes(
  297           byte[] content, int offset, int len,  String contentType)
  298           throws SOAPException;
  299   
  300   
  301       /**
  302        * Sets the content of this attachment part from the Base64 source
  303        * <code>InputStream</code>  and sets the value of the
  304        * <code>Content-Type</code> header to the value contained in
  305        * <code>contentType</code>, This method would first decode the base64
  306        * input and write the resulting raw bytes to the attachment.
  307        * <P>
  308        *  A subsequent call to getSize() may not be an exact measure
  309        *  of the content size.
  310        *
  311        * @param content the base64 encoded data to add to the attachment part
  312        * @param contentType the value to set into the <code>Content-Type</code>
  313        * header
  314        *
  315        * @exception SOAPException if an there is an error in setting the content
  316        * @exception NullPointerException if <code>content</code> is null
  317        *
  318        * @since SAAJ 1.3
  319        */
  320       public abstract void setBase64Content(
  321           InputStream content, String contentType) throws SOAPException;
  322   
  323   
  324       /**
  325        * Gets the <code>DataHandler</code> object for this <code>AttachmentPart</code>
  326        * object.
  327        *
  328        * @return the <code>DataHandler</code> object associated with this
  329        *         <code>AttachmentPart</code> object
  330        *
  331        * @exception SOAPException if there is no data in
  332        * this <code>AttachmentPart</code> object
  333        */
  334       public abstract DataHandler getDataHandler()
  335           throws SOAPException;
  336   
  337       /**
  338        * Sets the given <code>DataHandler</code> object as the data handler
  339        * for this <code>AttachmentPart</code> object. Typically, on an incoming
  340        * message, the data handler is automatically set. When
  341        * a message is being created and populated with content, the
  342        * <code>setDataHandler</code> method can be used to get data from
  343        * various data sources into the message.
  344        *
  345        * @param dataHandler the <code>DataHandler</code> object to be set
  346        *
  347        * @exception IllegalArgumentException if there was a problem with
  348        *            the specified <code>DataHandler</code> object
  349        */
  350       public abstract void setDataHandler(DataHandler dataHandler);
  351   
  352   
  353       /**
  354        * Gets the value of the MIME header whose name is "Content-ID".
  355        *
  356        * @return a <code>String</code> giving the value of the
  357        *          "Content-ID" header or <code>null</code> if there
  358        *          is none
  359        * @see #setContentId
  360        */
  361       public String getContentId() {
  362           String[] values = getMimeHeader("Content-ID");
  363           if (values != null && values.length > 0)
  364               return values[0];
  365           return null;
  366       }
  367   
  368       /**
  369        * Gets the value of the MIME header whose name is "Content-Location".
  370        *
  371        * @return a <code>String</code> giving the value of the
  372        *          "Content-Location" header or <code>null</code> if there
  373        *          is none
  374        */
  375       public String getContentLocation() {
  376           String[] values = getMimeHeader("Content-Location");
  377           if (values != null && values.length > 0)
  378               return values[0];
  379           return null;
  380       }
  381   
  382       /**
  383        * Gets the value of the MIME header whose name is "Content-Type".
  384        *
  385        * @return a <code>String</code> giving the value of the
  386        *          "Content-Type" header or <code>null</code> if there
  387        *          is none
  388        */
  389       public String getContentType() {
  390           String[] values = getMimeHeader("Content-Type");
  391           if (values != null && values.length > 0)
  392               return values[0];
  393           return null;
  394       }
  395   
  396       /**
  397        * Sets the MIME header whose name is "Content-ID" with the given value.
  398        *
  399        * @param contentId a <code>String</code> giving the value of the
  400        *          "Content-ID" header
  401        *
  402        * @exception IllegalArgumentException if there was a problem with
  403        *            the specified <code>contentId</code> value
  404        * @see #getContentId
  405        */
  406       public void setContentId(String contentId)
  407       {
  408           setMimeHeader("Content-ID", contentId);
  409       }
  410   
  411   
  412       /**
  413        * Sets the MIME header whose name is "Content-Location" with the given value.
  414        *
  415        *
  416        * @param contentLocation a <code>String</code> giving the value of the
  417        *          "Content-Location" header
  418        * @exception IllegalArgumentException if there was a problem with
  419        *            the specified content location
  420        */
  421       public void setContentLocation(String contentLocation)
  422       {
  423           setMimeHeader("Content-Location", contentLocation);
  424       }
  425   
  426       /**
  427        * Sets the MIME header whose name is "Content-Type" with the given value.
  428        *
  429        * @param contentType a <code>String</code> giving the value of the
  430        *          "Content-Type" header
  431        *
  432        * @exception IllegalArgumentException if there was a problem with
  433        *            the specified content type
  434        */
  435       public void setContentType(String contentType)
  436       {
  437           setMimeHeader("Content-Type", contentType);
  438       }
  439   
  440       /**
  441        * Removes all MIME headers that match the given name.
  442        *
  443        * @param header the string name of the MIME header/s to
  444        *               be removed
  445        */
  446       public abstract void removeMimeHeader(String header);
  447   
  448       /**
  449        * Removes all the MIME header entries.
  450        */
  451       public abstract void removeAllMimeHeaders();
  452   
  453   
  454       /**
  455        * Gets all the values of the header identified by the given
  456        * <code>String</code>.
  457        *
  458        * @param name the name of the header; example: "Content-Type"
  459        * @return a <code>String</code> array giving the value for the
  460        *         specified header
  461        * @see #setMimeHeader
  462        */
  463       public abstract String[] getMimeHeader(String name);
  464   
  465   
  466       /**
  467        * Changes the first header entry that matches the given name
  468        * to the given value, adding a new header if no existing header
  469        * matches. This method also removes all matching headers but the first. <p>
  470        *
  471        * Note that RFC822 headers can only contain US-ASCII characters.
  472        *
  473        * @param   name    a <code>String</code> giving the name of the header
  474        *                  for which to search
  475        * @param   value   a <code>String</code> giving the value to be set for
  476        *                  the header whose name matches the given name
  477        *
  478        * @exception IllegalArgumentException if there was a problem with
  479        *            the specified mime header name or value
  480        */
  481       public abstract void setMimeHeader(String name, String value);
  482   
  483   
  484       /**
  485        * Adds a MIME header with the specified name and value to this
  486        * <code>AttachmentPart</code> object.
  487        * <p>
  488        * Note that RFC822 headers can contain only US-ASCII characters.
  489        *
  490        * @param   name    a <code>String</code> giving the name of the header
  491        *                  to be added
  492        * @param   value   a <code>String</code> giving the value of the header
  493        *                  to be added
  494        *
  495        * @exception IllegalArgumentException if there was a problem with
  496        *            the specified mime header name or value
  497        */
  498       public abstract void addMimeHeader(String name, String value);
  499   
  500       /**
  501        * Retrieves all the headers for this <code>AttachmentPart</code> object
  502        * as an iterator over the <code>MimeHeader</code> objects.
  503        *
  504        * @return  an <code>Iterator</code> object with all of the Mime
  505        *          headers for this <code>AttachmentPart</code> object
  506        */
  507       public abstract Iterator getAllMimeHeaders();
  508   
  509       /**
  510        * Retrieves all <code>MimeHeader</code> objects that match a name in
  511        * the given array.
  512        *
  513        * @param names a <code>String</code> array with the name(s) of the
  514        *        MIME headers to be returned
  515        * @return  all of the MIME headers that match one of the names in the
  516        *           given array as an <code>Iterator</code> object
  517        */
  518       public abstract Iterator getMatchingMimeHeaders(String[] names);
  519   
  520       /**
  521        * Retrieves all <code>MimeHeader</code> objects whose name does
  522        * not match a name in the given array.
  523        *
  524        * @param names a <code>String</code> array with the name(s) of the
  525        *        MIME headers not to be returned
  526        * @return  all of the MIME headers in this <code>AttachmentPart</code> object
  527        *          except those that match one of the names in the
  528        *           given array.  The nonmatching MIME headers are returned as an
  529        *           <code>Iterator</code> object.
  530        */
  531       public abstract Iterator getNonMatchingMimeHeaders(String[] names);
  532   }

Home » xml-commons-external-1.4.01-src » javax » xml » soap » [javadoc | source]