diff -r cb15fc6cc038 -r 9a2e5d103695 jaxws/src/java.xml.soap/share/classes/javax/xml/soap/AttachmentPart.java --- a/jaxws/src/java.xml.soap/share/classes/javax/xml/soap/AttachmentPart.java Thu Jan 15 11:18:14 2015 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,528 +0,0 @@ -/* - * Copyright (c) 2004, 2013, Oracle and/or its affiliates. All rights reserved. - * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. - * - * This code is free software; you can redistribute it and/or modify it - * under the terms of the GNU General Public License version 2 only, as - * published by the Free Software Foundation. Oracle designates this - * particular file as subject to the "Classpath" exception as provided - * by Oracle in the LICENSE file that accompanied this code. - * - * This code is distributed in the hope that it will be useful, but WITHOUT - * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or - * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License - * version 2 for more details (a copy is included in the LICENSE file that - * accompanied this code). - * - * You should have received a copy of the GNU General Public License version - * 2 along with this work; if not, write to the Free Software Foundation, - * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. - * - * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA - * or visit www.oracle.com if you need additional information or have any - * questions. - */ - -package javax.xml.soap; - -import java.io.InputStream; -import java.io.Reader; -import java.util.Iterator; - -import javax.activation.DataHandler; - -/** - * 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: - * - *
- *

- * 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();
- *
- * - * @since 1.6 - */ - -public abstract class AttachmentPart { - /** - * Returns the number of bytes in this AttachmentPart - * object. - * - * @return the size of this AttachmentPart object in bytes - * or -1 if the size cannot be determined - * @exception SOAPException if the content of this attachment is - * corrupted of if there was an exception while trying - * to determine the size. - */ - public abstract int getSize() throws SOAPException; - - /** - * Clears out the content of this AttachmentPart object. - * The MIME header portion is left untouched. - */ - public abstract void clearContent(); - - /** - * Gets the content of this 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. - * - * @return a Java object with the content of this AttachmentPart - * object - * - * @exception SOAPException if there is no content set into this - * AttachmentPart object or if there was a data - * transformation error - */ - public abstract Object getContent() throws SOAPException; - - /** - * Gets the content of this AttachmentPart object as an - * InputStream as if a call had been made to getContent and no - * DataContentHandler had been registered for the - * content-type of this AttachmentPart. - *

- * 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 {@link #getRawContentBytes} API - * should be used instead. - * - * @return an InputStream from which the raw data contained by - * the 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 1.6, SAAJ 1.3 - * @see #getRawContentBytes - */ - public abstract InputStream getRawContent() throws SOAPException; - - /** - * Gets the content of this AttachmentPart object as a - * byte[] array as if a call had been made to getContent and no - * DataContentHandler had been registered for the - * content-type of this AttachmentPart. - * - * @return a byte[] array containing the raw data of the - * AttachmentPart. - * - * @throws SOAPException if there is no content set into this - * AttachmentPart object or if there was a data - * transformation error. - * - * @since 1.6, SAAJ 1.3 - */ - public abstract byte[] getRawContentBytes() throws SOAPException; - - /** - * Returns an InputStream which can be used to obtain the - * content of AttachmentPart as Base64 encoded - * character data, this method would base64 encode the raw bytes - * of the attachment and return. - * - * @return an InputStream from which the Base64 encoded - * AttachmentPart can be read. - * - * @throws SOAPException if there is no content set into this - * AttachmentPart object or if there was a data - * transformation error. - * - * @since 1.6, SAAJ 1.3 - */ - public abstract InputStream getBase64Content() throws SOAPException; - - /** - * Sets the content of this attachment part to that of the given - * 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. - * - * - * @param object the Java object that makes up the content for - * this attachment part - * @param contentType the MIME string that specifies the type of - * the content - * - * @exception IllegalArgumentException may be thrown if the contentType - * does not match the type of the content object, or if there - * was no DataContentHandler object for this - * content object - * - * @see #getContent - */ - public abstract void setContent(Object object, String contentType); - - /** - * Sets the content of this attachment part to that contained by the - * InputStream content and sets the value of the - * Content-Type header to the value contained in - * contentType. - *

- * A subsequent call to getSize() may not be an exact measure - * of the content size. - * - * @param content the raw data to add to the attachment part - * @param 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 1.6, SAAJ 1.3 - */ - public abstract void setRawContent(InputStream content, String contentType) throws SOAPException; - - /** - * Sets the content of this attachment part to that contained by the - * byte[] array content and sets the value of the - * Content-Type header to the value contained in - * contentType. - * - * @param content the raw data to add to the attachment part - * @param contentType the value to set into the Content-Type - * header - * @param offset the offset in the byte array of the content - * @param len the number of bytes that form the content - * - * @exception SOAPException if an there is an error in setting the content - * or content is null - * @since 1.6, SAAJ 1.3 - */ - public abstract void setRawContentBytes( - byte[] content, int offset, int len, String contentType) - throws SOAPException; - - - /** - * Sets the content of this attachment part from the Base64 source - * InputStream and sets the value of the - * Content-Type header to the value contained in - * contentType, This method would first decode the base64 - * input and write the resulting raw bytes to the attachment. - *

- * A subsequent call to getSize() may not be an exact measure - * of the content size. - * - * @param content the base64 encoded data to add to the attachment part - * @param 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 1.6, SAAJ 1.3 - */ - public abstract void setBase64Content( - InputStream content, String contentType) throws SOAPException; - - - /** - * Gets the DataHandler object for this AttachmentPart - * object. - * - * @return the DataHandler object associated with this - * AttachmentPart object - * - * @exception SOAPException if there is no data in - * this AttachmentPart object - */ - public abstract DataHandler getDataHandler() - throws SOAPException; - - /** - * Sets the given 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. - * - * @param dataHandler the DataHandler object to be set - * - * @exception IllegalArgumentException if there was a problem with - * the specified DataHandler object - */ - public abstract void setDataHandler(DataHandler dataHandler); - - - /** - * Gets the value of the MIME header whose name is "Content-ID". - * - * @return a String giving the value of the - * "Content-ID" header or null if there - * is none - * @see #setContentId - */ - public String getContentId() { - String[] values = getMimeHeader("Content-ID"); - if (values != null && values.length > 0) - return values[0]; - return null; - } - - /** - * Gets the value of the MIME header whose name is "Content-Location". - * - * @return a String giving the value of the - * "Content-Location" header or null if there - * is none - */ - public String getContentLocation() { - String[] values = getMimeHeader("Content-Location"); - if (values != null && values.length > 0) - return values[0]; - return null; - } - - /** - * Gets the value of the MIME header whose name is "Content-Type". - * - * @return a String giving the value of the - * "Content-Type" header or null if there - * is none - */ - public String getContentType() { - String[] values = getMimeHeader("Content-Type"); - if (values != null && values.length > 0) - return values[0]; - return null; - } - - /** - * Sets the MIME header whose name is "Content-ID" with the given value. - * - * @param contentId a String giving the value of the - * "Content-ID" header - * - * @exception IllegalArgumentException if there was a problem with - * the specified contentId value - * @see #getContentId - */ - public void setContentId(String contentId) - { - setMimeHeader("Content-ID", contentId); - } - - - /** - * Sets the MIME header whose name is "Content-Location" with the given value. - * - * - * @param contentLocation a String giving the value of the - * "Content-Location" header - * @exception IllegalArgumentException if there was a problem with - * the specified content location - */ - public void setContentLocation(String contentLocation) - { - setMimeHeader("Content-Location", contentLocation); - } - - /** - * Sets the MIME header whose name is "Content-Type" with the given value. - * - * @param contentType a String giving the value of the - * "Content-Type" header - * - * @exception IllegalArgumentException if there was a problem with - * the specified content type - */ - public void setContentType(String contentType) - { - setMimeHeader("Content-Type", contentType); - } - - /** - * Removes all MIME headers that match the given name. - * - * @param header the string name of the MIME header/s to - * be removed - */ - public abstract void removeMimeHeader(String header); - - /** - * Removes all the MIME header entries. - */ - public abstract void removeAllMimeHeaders(); - - - /** - * Gets all the values of the header identified by the given - * String. - * - * @param name the name of the header; example: "Content-Type" - * @return a String array giving the value for the - * specified header - * @see #setMimeHeader - */ - public abstract String[] getMimeHeader(String name); - - - /** - * Changes the first header entry that matches the given name - * to the given value, adding a new header if no existing header - * matches. This method also removes all matching headers but the first.

- * - * Note that RFC822 headers can only contain US-ASCII characters. - * - * @param name a String giving the name of the header - * for which to search - * @param value a String giving the value to be set for - * the header whose name matches the given name - * - * @exception IllegalArgumentException if there was a problem with - * the specified mime header name or value - */ - public abstract void setMimeHeader(String name, String value); - - - /** - * Adds a MIME header with the specified name and value to this - * AttachmentPart object. - *

- * Note that RFC822 headers can contain only US-ASCII characters. - * - * @param name a String giving the name of the header - * to be added - * @param value a String giving the value of the header - * to be added - * - * @exception IllegalArgumentException if there was a problem with - * the specified mime header name or value - */ - public abstract void addMimeHeader(String name, String value); - - /** - * Retrieves all the headers for this AttachmentPart object - * as an iterator over the MimeHeader objects. - * - * @return an Iterator object with all of the Mime - * headers for this AttachmentPart object - */ - public abstract Iterator getAllMimeHeaders(); - - /** - * Retrieves all MimeHeader objects that match a name in - * the given array. - * - * @param names a String array with the name(s) of the - * MIME headers to be returned - * @return all of the MIME headers that match one of the names in the - * given array as an Iterator object - */ - public abstract Iterator getMatchingMimeHeaders(String[] names); - - /** - * Retrieves all MimeHeader objects whose name does - * not match a name in the given array. - * - * @param names a String array with the name(s) of the - * MIME headers not to be returned - * @return all of the MIME headers in this AttachmentPart object - * except those that match one of the names in the - * given array. The nonmatching MIME headers are returned as an - * Iterator object. - */ - public abstract Iterator getNonMatchingMimeHeaders(String[] names); -}