1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/src/share/jaxws_classes/javax/xml/soap/AttachmentPart.java Wed Apr 27 01:27:09 2016 +0800
1.3 @@ -0,0 +1,526 @@
1.4 +/*
1.5 + * Copyright (c) 2004, 2012, Oracle and/or its affiliates. All rights reserved.
1.6 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
1.7 + *
1.8 + * This code is free software; you can redistribute it and/or modify it
1.9 + * under the terms of the GNU General Public License version 2 only, as
1.10 + * published by the Free Software Foundation. Oracle designates this
1.11 + * particular file as subject to the "Classpath" exception as provided
1.12 + * by Oracle in the LICENSE file that accompanied this code.
1.13 + *
1.14 + * This code is distributed in the hope that it will be useful, but WITHOUT
1.15 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
1.16 + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
1.17 + * version 2 for more details (a copy is included in the LICENSE file that
1.18 + * accompanied this code).
1.19 + *
1.20 + * You should have received a copy of the GNU General Public License version
1.21 + * 2 along with this work; if not, write to the Free Software Foundation,
1.22 + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
1.23 + *
1.24 + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
1.25 + * or visit www.oracle.com if you need additional information or have any
1.26 + * questions.
1.27 + */
1.28 +
1.29 +package javax.xml.soap;
1.30 +
1.31 +import java.io.InputStream;
1.32 +import java.io.Reader;
1.33 +import java.util.Iterator;
1.34 +
1.35 +import javax.activation.DataHandler;
1.36 +
1.37 +/**
1.38 + * A single attachment to a <code>SOAPMessage</code> object. A <code>SOAPMessage</code>
1.39 + * object may contain zero, one, or many <code>AttachmentPart</code> objects.
1.40 + * Each <code>AttachmentPart</code> object consists of two parts,
1.41 + * application-specific content and associated MIME headers. The
1.42 + * MIME headers consists of name/value pairs that can be used to
1.43 + * identify and describe the content.
1.44 + * <p>
1.45 + * An <code>AttachmentPart</code> object must conform to certain standards.
1.46 + * <OL>
1.47 + * <LI>It must conform to <a href="http://www.ietf.org/rfc/rfc2045.txt">
1.48 + * MIME [RFC2045] standards</a>
1.49 + * <LI>It MUST contain content
1.50 + * <LI>The header portion MUST include the following header:
1.51 + * <UL>
1.52 + * <LI><code>Content-Type</code><br>
1.53 + * This header identifies the type of data in the content of an
1.54 + * <code>AttachmentPart</code> object and MUST conform to [RFC2045].
1.55 + * The following is an example of a Content-Type header:
1.56 + * <PRE>
1.57 + * Content-Type: application/xml
1.58 + * </PRE>
1.59 + * The following line of code, in which <code>ap</code> is an
1.60 + * <code>AttachmentPart</code> object, sets the header shown in
1.61 + * the previous example.
1.62 + * <PRE>
1.63 + * ap.setMimeHeader("Content-Type", "application/xml");
1.64 + * </PRE>
1.65 + * <p>
1.66 + * </UL>
1.67 + * </OL>
1.68 + * <p>
1.69 + * There are no restrictions on the content portion of an <code>
1.70 + * AttachmentPart</code> object. The content may be anything from a
1.71 + * simple plain text object to a complex XML document or image file.
1.72 + *
1.73 + * <p>
1.74 + * An <code>AttachmentPart</code> object is created with the method
1.75 + * <code>SOAPMessage.createAttachmentPart</code>. After setting its MIME headers,
1.76 + * the <code>AttachmentPart</code> object is added to the message
1.77 + * that created it with the method <code>SOAPMessage.addAttachmentPart</code>.
1.78 + *
1.79 + * <p>
1.80 + * The following code fragment, in which <code>m</code> is a
1.81 + * <code>SOAPMessage</code> object and <code>contentStringl</code> is a
1.82 + * <code>String</code>, creates an instance of <code>AttachmentPart</code>,
1.83 + * sets the <code>AttachmentPart</code> object with some content and
1.84 + * header information, and adds the <code>AttachmentPart</code> object to
1.85 + * the <code>SOAPMessage</code> object.
1.86 + * <PRE>
1.87 + * AttachmentPart ap1 = m.createAttachmentPart();
1.88 + * ap1.setContent(contentString1, "text/plain");
1.89 + * m.addAttachmentPart(ap1);
1.90 + * </PRE>
1.91 + *
1.92 + *
1.93 + * <p>
1.94 + * The following code fragment creates and adds a second
1.95 + * <code>AttachmentPart</code> instance to the same message. <code>jpegData</code>
1.96 + * is a binary byte buffer representing the jpeg file.
1.97 + * <PRE>
1.98 + * AttachmentPart ap2 = m.createAttachmentPart();
1.99 + * byte[] jpegData = ...;
1.100 + * ap2.setContent(new ByteArrayInputStream(jpegData), "image/jpeg");
1.101 + * m.addAttachmentPart(ap2);
1.102 + * </PRE>
1.103 + * <p>
1.104 + * The <code>getContent</code> method retrieves the contents and header from
1.105 + * an <code>AttachmentPart</code> object. Depending on the
1.106 + * <code>DataContentHandler</code> objects present, the returned
1.107 + * <code>Object</code> can either be a typed Java object corresponding
1.108 + * to the MIME type or an <code>InputStream</code> object that contains the
1.109 + * content as bytes.
1.110 + * <PRE>
1.111 + * String content1 = ap1.getContent();
1.112 + * java.io.InputStream content2 = ap2.getContent();
1.113 + * </PRE>
1.114 + *
1.115 + * The method <code>clearContent</code> removes all the content from an
1.116 + * <code>AttachmentPart</code> object but does not affect its header information.
1.117 + * <PRE>
1.118 + * ap1.clearContent();
1.119 + * </PRE>
1.120 + */
1.121 +
1.122 +public abstract class AttachmentPart {
1.123 + /**
1.124 + * Returns the number of bytes in this <code>AttachmentPart</code>
1.125 + * object.
1.126 + *
1.127 + * @return the size of this <code>AttachmentPart</code> object in bytes
1.128 + * or -1 if the size cannot be determined
1.129 + * @exception SOAPException if the content of this attachment is
1.130 + * corrupted of if there was an exception while trying
1.131 + * to determine the size.
1.132 + */
1.133 + public abstract int getSize() throws SOAPException;
1.134 +
1.135 + /**
1.136 + * Clears out the content of this <code>AttachmentPart</code> object.
1.137 + * The MIME header portion is left untouched.
1.138 + */
1.139 + public abstract void clearContent();
1.140 +
1.141 + /**
1.142 + * Gets the content of this <code>AttachmentPart</code> object as a Java
1.143 + * object. The type of the returned Java object depends on (1) the
1.144 + * <code>DataContentHandler</code> object that is used to interpret the bytes
1.145 + * and (2) the <code>Content-Type</code> given in the header.
1.146 + * <p>
1.147 + * For the MIME content types "text/plain", "text/html" and "text/xml", the
1.148 + * <code>DataContentHandler</code> object does the conversions to and
1.149 + * from the Java types corresponding to the MIME types.
1.150 + * For other MIME types,the <code>DataContentHandler</code> object
1.151 + * can return an <code>InputStream</code> object that contains the content data
1.152 + * as raw bytes.
1.153 + * <p>
1.154 + * A SAAJ-compliant implementation must, as a minimum, return a
1.155 + * <code>java.lang.String</code> object corresponding to any content
1.156 + * stream with a <code>Content-Type</code> value of
1.157 + * <code>text/plain</code>, a
1.158 + * <code>javax.xml.transform.stream.StreamSource</code> object corresponding to a
1.159 + * content stream with a <code>Content-Type</code> value of
1.160 + * <code>text/xml</code>, a <code>java.awt.Image</code> object
1.161 + * corresponding to a content stream with a
1.162 + * <code>Content-Type</code> value of <code>image/gif</code> or
1.163 + * <code>image/jpeg</code>. For those content types that an
1.164 + * installed <code>DataContentHandler</code> object does not understand, the
1.165 + * <code>DataContentHandler</code> object is required to return a
1.166 + * <code>java.io.InputStream</code> object with the raw bytes.
1.167 + *
1.168 + * @return a Java object with the content of this <code>AttachmentPart</code>
1.169 + * object
1.170 + *
1.171 + * @exception SOAPException if there is no content set into this
1.172 + * <code>AttachmentPart</code> object or if there was a data
1.173 + * transformation error
1.174 + */
1.175 + public abstract Object getContent() throws SOAPException;
1.176 +
1.177 + /**
1.178 + * Gets the content of this <code>AttachmentPart</code> object as an
1.179 + * InputStream as if a call had been made to <code>getContent</code> and no
1.180 + * <code>DataContentHandler</code> had been registered for the
1.181 + * <code>content-type</code> of this <code>AttachmentPart</code>.
1.182 + *<p>
1.183 + * Note that reading from the returned InputStream would result in consuming
1.184 + * the data in the stream. It is the responsibility of the caller to reset
1.185 + * the InputStream appropriately before calling a Subsequent API. If a copy
1.186 + * of the raw attachment content is required then the {@link #getRawContentBytes} API
1.187 + * should be used instead.
1.188 + *
1.189 + * @return an <code>InputStream</code> from which the raw data contained by
1.190 + * the <code>AttachmentPart</code> can be accessed.
1.191 + *
1.192 + * @throws SOAPException if there is no content set into this
1.193 + * <code>AttachmentPart</code> object or if there was a data
1.194 + * transformation error.
1.195 + *
1.196 + * @since SAAJ 1.3
1.197 + * @see #getRawContentBytes
1.198 + */
1.199 + public abstract InputStream getRawContent() throws SOAPException;
1.200 +
1.201 + /**
1.202 + * Gets the content of this <code>AttachmentPart</code> object as a
1.203 + * byte[] array as if a call had been made to <code>getContent</code> and no
1.204 + * <code>DataContentHandler</code> had been registered for the
1.205 + * <code>content-type</code> of this <code>AttachmentPart</code>.
1.206 + *
1.207 + * @return a <code>byte[]</code> array containing the raw data of the
1.208 + * <code>AttachmentPart</code>.
1.209 + *
1.210 + * @throws SOAPException if there is no content set into this
1.211 + * <code>AttachmentPart</code> object or if there was a data
1.212 + * transformation error.
1.213 + *
1.214 + * @since SAAJ 1.3
1.215 + */
1.216 + public abstract byte[] getRawContentBytes() throws SOAPException;
1.217 +
1.218 + /**
1.219 + * Returns an <code>InputStream</code> which can be used to obtain the
1.220 + * content of <code>AttachmentPart</code> as Base64 encoded
1.221 + * character data, this method would base64 encode the raw bytes
1.222 + * of the attachment and return.
1.223 + *
1.224 + * @return an <code>InputStream</code> from which the Base64 encoded
1.225 + * <code>AttachmentPart</code> can be read.
1.226 + *
1.227 + * @throws SOAPException if there is no content set into this
1.228 + * <code>AttachmentPart</code> object or if there was a data
1.229 + * transformation error.
1.230 + *
1.231 + * @since SAAJ 1.3
1.232 + */
1.233 + public abstract InputStream getBase64Content() throws SOAPException;
1.234 +
1.235 + /**
1.236 + * Sets the content of this attachment part to that of the given
1.237 + * <code>Object</code> and sets the value of the <code>Content-Type</code>
1.238 + * header to the given type. The type of the
1.239 + * <code>Object</code> should correspond to the value given for the
1.240 + * <code>Content-Type</code>. This depends on the particular
1.241 + * set of <code>DataContentHandler</code> objects in use.
1.242 + *
1.243 + *
1.244 + * @param object the Java object that makes up the content for
1.245 + * this attachment part
1.246 + * @param contentType the MIME string that specifies the type of
1.247 + * the content
1.248 + *
1.249 + * @exception IllegalArgumentException may be thrown if the contentType
1.250 + * does not match the type of the content object, or if there
1.251 + * was no <code>DataContentHandler</code> object for this
1.252 + * content object
1.253 + *
1.254 + * @see #getContent
1.255 + */
1.256 + public abstract void setContent(Object object, String contentType);
1.257 +
1.258 + /**
1.259 + * Sets the content of this attachment part to that contained by the
1.260 + * <code>InputStream</code> <code>content</code> and sets the value of the
1.261 + * <code>Content-Type</code> header to the value contained in
1.262 + * <code>contentType</code>.
1.263 + * <P>
1.264 + * A subsequent call to getSize() may not be an exact measure
1.265 + * of the content size.
1.266 + *
1.267 + * @param content the raw data to add to the attachment part
1.268 + * @param contentType the value to set into the <code>Content-Type</code>
1.269 + * header
1.270 + *
1.271 + * @exception SOAPException if an there is an error in setting the content
1.272 + * @exception NullPointerException if <code>content</code> is null
1.273 + * @since SAAJ 1.3
1.274 + */
1.275 + public abstract void setRawContent(InputStream content, String contentType) throws SOAPException;
1.276 +
1.277 + /**
1.278 + * Sets the content of this attachment part to that contained by the
1.279 + * <code>byte[]</code> array <code>content</code> and sets the value of the
1.280 + * <code>Content-Type</code> header to the value contained in
1.281 + * <code>contentType</code>.
1.282 + *
1.283 + * @param content the raw data to add to the attachment part
1.284 + * @param contentType the value to set into the <code>Content-Type</code>
1.285 + * header
1.286 + * @param offset the offset in the byte array of the content
1.287 + * @param len the number of bytes that form the content
1.288 + *
1.289 + * @exception SOAPException if an there is an error in setting the content
1.290 + * or content is null
1.291 + * @since SAAJ 1.3
1.292 + */
1.293 + public abstract void setRawContentBytes(
1.294 + byte[] content, int offset, int len, String contentType)
1.295 + throws SOAPException;
1.296 +
1.297 +
1.298 + /**
1.299 + * Sets the content of this attachment part from the Base64 source
1.300 + * <code>InputStream</code> and sets the value of the
1.301 + * <code>Content-Type</code> header to the value contained in
1.302 + * <code>contentType</code>, This method would first decode the base64
1.303 + * input and write the resulting raw bytes to the attachment.
1.304 + * <P>
1.305 + * A subsequent call to getSize() may not be an exact measure
1.306 + * of the content size.
1.307 + *
1.308 + * @param content the base64 encoded data to add to the attachment part
1.309 + * @param contentType the value to set into the <code>Content-Type</code>
1.310 + * header
1.311 + *
1.312 + * @exception SOAPException if an there is an error in setting the content
1.313 + * @exception NullPointerException if <code>content</code> is null
1.314 + *
1.315 + * @since SAAJ 1.3
1.316 + */
1.317 + public abstract void setBase64Content(
1.318 + InputStream content, String contentType) throws SOAPException;
1.319 +
1.320 +
1.321 + /**
1.322 + * Gets the <code>DataHandler</code> object for this <code>AttachmentPart</code>
1.323 + * object.
1.324 + *
1.325 + * @return the <code>DataHandler</code> object associated with this
1.326 + * <code>AttachmentPart</code> object
1.327 + *
1.328 + * @exception SOAPException if there is no data in
1.329 + * this <code>AttachmentPart</code> object
1.330 + */
1.331 + public abstract DataHandler getDataHandler()
1.332 + throws SOAPException;
1.333 +
1.334 + /**
1.335 + * Sets the given <code>DataHandler</code> object as the data handler
1.336 + * for this <code>AttachmentPart</code> object. Typically, on an incoming
1.337 + * message, the data handler is automatically set. When
1.338 + * a message is being created and populated with content, the
1.339 + * <code>setDataHandler</code> method can be used to get data from
1.340 + * various data sources into the message.
1.341 + *
1.342 + * @param dataHandler the <code>DataHandler</code> object to be set
1.343 + *
1.344 + * @exception IllegalArgumentException if there was a problem with
1.345 + * the specified <code>DataHandler</code> object
1.346 + */
1.347 + public abstract void setDataHandler(DataHandler dataHandler);
1.348 +
1.349 +
1.350 + /**
1.351 + * Gets the value of the MIME header whose name is "Content-ID".
1.352 + *
1.353 + * @return a <code>String</code> giving the value of the
1.354 + * "Content-ID" header or <code>null</code> if there
1.355 + * is none
1.356 + * @see #setContentId
1.357 + */
1.358 + public String getContentId() {
1.359 + String[] values = getMimeHeader("Content-ID");
1.360 + if (values != null && values.length > 0)
1.361 + return values[0];
1.362 + return null;
1.363 + }
1.364 +
1.365 + /**
1.366 + * Gets the value of the MIME header whose name is "Content-Location".
1.367 + *
1.368 + * @return a <code>String</code> giving the value of the
1.369 + * "Content-Location" header or <code>null</code> if there
1.370 + * is none
1.371 + */
1.372 + public String getContentLocation() {
1.373 + String[] values = getMimeHeader("Content-Location");
1.374 + if (values != null && values.length > 0)
1.375 + return values[0];
1.376 + return null;
1.377 + }
1.378 +
1.379 + /**
1.380 + * Gets the value of the MIME header whose name is "Content-Type".
1.381 + *
1.382 + * @return a <code>String</code> giving the value of the
1.383 + * "Content-Type" header or <code>null</code> if there
1.384 + * is none
1.385 + */
1.386 + public String getContentType() {
1.387 + String[] values = getMimeHeader("Content-Type");
1.388 + if (values != null && values.length > 0)
1.389 + return values[0];
1.390 + return null;
1.391 + }
1.392 +
1.393 + /**
1.394 + * Sets the MIME header whose name is "Content-ID" with the given value.
1.395 + *
1.396 + * @param contentId a <code>String</code> giving the value of the
1.397 + * "Content-ID" header
1.398 + *
1.399 + * @exception IllegalArgumentException if there was a problem with
1.400 + * the specified <code>contentId</code> value
1.401 + * @see #getContentId
1.402 + */
1.403 + public void setContentId(String contentId)
1.404 + {
1.405 + setMimeHeader("Content-ID", contentId);
1.406 + }
1.407 +
1.408 +
1.409 + /**
1.410 + * Sets the MIME header whose name is "Content-Location" with the given value.
1.411 + *
1.412 + *
1.413 + * @param contentLocation a <code>String</code> giving the value of the
1.414 + * "Content-Location" header
1.415 + * @exception IllegalArgumentException if there was a problem with
1.416 + * the specified content location
1.417 + */
1.418 + public void setContentLocation(String contentLocation)
1.419 + {
1.420 + setMimeHeader("Content-Location", contentLocation);
1.421 + }
1.422 +
1.423 + /**
1.424 + * Sets the MIME header whose name is "Content-Type" with the given value.
1.425 + *
1.426 + * @param contentType a <code>String</code> giving the value of the
1.427 + * "Content-Type" header
1.428 + *
1.429 + * @exception IllegalArgumentException if there was a problem with
1.430 + * the specified content type
1.431 + */
1.432 + public void setContentType(String contentType)
1.433 + {
1.434 + setMimeHeader("Content-Type", contentType);
1.435 + }
1.436 +
1.437 + /**
1.438 + * Removes all MIME headers that match the given name.
1.439 + *
1.440 + * @param header the string name of the MIME header/s to
1.441 + * be removed
1.442 + */
1.443 + public abstract void removeMimeHeader(String header);
1.444 +
1.445 + /**
1.446 + * Removes all the MIME header entries.
1.447 + */
1.448 + public abstract void removeAllMimeHeaders();
1.449 +
1.450 +
1.451 + /**
1.452 + * Gets all the values of the header identified by the given
1.453 + * <code>String</code>.
1.454 + *
1.455 + * @param name the name of the header; example: "Content-Type"
1.456 + * @return a <code>String</code> array giving the value for the
1.457 + * specified header
1.458 + * @see #setMimeHeader
1.459 + */
1.460 + public abstract String[] getMimeHeader(String name);
1.461 +
1.462 +
1.463 + /**
1.464 + * Changes the first header entry that matches the given name
1.465 + * to the given value, adding a new header if no existing header
1.466 + * matches. This method also removes all matching headers but the first. <p>
1.467 + *
1.468 + * Note that RFC822 headers can only contain US-ASCII characters.
1.469 + *
1.470 + * @param name a <code>String</code> giving the name of the header
1.471 + * for which to search
1.472 + * @param value a <code>String</code> giving the value to be set for
1.473 + * the header whose name matches the given name
1.474 + *
1.475 + * @exception IllegalArgumentException if there was a problem with
1.476 + * the specified mime header name or value
1.477 + */
1.478 + public abstract void setMimeHeader(String name, String value);
1.479 +
1.480 +
1.481 + /**
1.482 + * Adds a MIME header with the specified name and value to this
1.483 + * <code>AttachmentPart</code> object.
1.484 + * <p>
1.485 + * Note that RFC822 headers can contain only US-ASCII characters.
1.486 + *
1.487 + * @param name a <code>String</code> giving the name of the header
1.488 + * to be added
1.489 + * @param value a <code>String</code> giving the value of the header
1.490 + * to be added
1.491 + *
1.492 + * @exception IllegalArgumentException if there was a problem with
1.493 + * the specified mime header name or value
1.494 + */
1.495 + public abstract void addMimeHeader(String name, String value);
1.496 +
1.497 + /**
1.498 + * Retrieves all the headers for this <code>AttachmentPart</code> object
1.499 + * as an iterator over the <code>MimeHeader</code> objects.
1.500 + *
1.501 + * @return an <code>Iterator</code> object with all of the Mime
1.502 + * headers for this <code>AttachmentPart</code> object
1.503 + */
1.504 + public abstract Iterator getAllMimeHeaders();
1.505 +
1.506 + /**
1.507 + * Retrieves all <code>MimeHeader</code> objects that match a name in
1.508 + * the given array.
1.509 + *
1.510 + * @param names a <code>String</code> array with the name(s) of the
1.511 + * MIME headers to be returned
1.512 + * @return all of the MIME headers that match one of the names in the
1.513 + * given array as an <code>Iterator</code> object
1.514 + */
1.515 + public abstract Iterator getMatchingMimeHeaders(String[] names);
1.516 +
1.517 + /**
1.518 + * Retrieves all <code>MimeHeader</code> objects whose name does
1.519 + * not match a name in the given array.
1.520 + *
1.521 + * @param names a <code>String</code> array with the name(s) of the
1.522 + * MIME headers not to be returned
1.523 + * @return all of the MIME headers in this <code>AttachmentPart</code> object
1.524 + * except those that match one of the names in the
1.525 + * given array. The nonmatching MIME headers are returned as an
1.526 + * <code>Iterator</code> object.
1.527 + */
1.528 + public abstract Iterator getNonMatchingMimeHeaders(String[] names);
1.529 +}
