1 /*
2 * Copyright (c) 2004, 2013, Oracle and/or its affiliates. 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. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
33
34 /**
35 * A single attachment to a {@code SOAPMessage} object. A {@code SOAPMessage}
36 * object may contain zero, one, or many {@code AttachmentPart} objects.
37 * Each {@code AttachmentPart} object consists of two parts,
38 * application-specific content and associated MIME headers. The
39 * MIME headers consists of name/value pairs that can be used to
40 * identify and describe the content.
41 * <p>
42 * An {@code AttachmentPart} object must conform to certain standards.
43 * <OL>
44 * <LI>It must conform to <a href="http://www.ietf.org/rfc/rfc2045.txt">
45 * MIME [RFC2045] standards</a>
46 * <LI>It MUST contain content
47 * <LI>The header portion MUST include the following header:
48 * <UL>
49 * <LI>{@code Content-Type}<br>
50 * This header identifies the type of data in the content of an
51 * {@code AttachmentPart} object and MUST conform to [RFC2045].
52 * The following is an example of a Content-Type header:
53 * <PRE>
54 * Content-Type: application/xml
55 * </PRE>
56 * The following line of code, in which {@code ap} is an
57 * {@code AttachmentPart} object, sets the header shown in
58 * the previous example.
59 * <PRE>
60 * ap.setMimeHeader("Content-Type", "application/xml");
61 * </PRE>
62 * </UL>
63 * </OL>
64 * <p>
65 * There are no restrictions on the content portion of an {@code
66 * AttachmentPart} object. The content may be anything from a
67 * simple plain text object to a complex XML document or image file.
68 *
69 * <p>
70 * An {@code AttachmentPart} object is created with the method
71 * {@code SOAPMessage.createAttachmentPart}. After setting its MIME headers,
72 * the {@code AttachmentPart} object is added to the message
73 * that created it with the method {@code SOAPMessage.addAttachmentPart}.
74 *
75 * <p>
76 * The following code fragment, in which {@code m} is a
77 * {@code SOAPMessage} object and {@code contentStringl} is a
78 * {@code String}, creates an instance of {@code AttachmentPart},
79 * sets the {@code AttachmentPart} object with some content and
80 * header information, and adds the {@code AttachmentPart} object to
81 * the {@code SOAPMessage} object.
82 * <PRE>
83 * AttachmentPart ap1 = m.createAttachmentPart();
84 * ap1.setContent(contentString1, "text/plain");
85 * m.addAttachmentPart(ap1);
86 * </PRE>
87 *
88 *
89 * <p>
90 * The following code fragment creates and adds a second
91 * {@code AttachmentPart} instance to the same message. {@code jpegData}
92 * is a binary byte buffer representing the jpeg file.
93 * <PRE>
94 * AttachmentPart ap2 = m.createAttachmentPart();
95 * byte[] jpegData = ...;
96 * ap2.setContent(new ByteArrayInputStream(jpegData), "image/jpeg");
97 * m.addAttachmentPart(ap2);
98 * </PRE>
99 * <p>
100 * The {@code getContent} method retrieves the contents and header from
101 * an {@code AttachmentPart} object. Depending on the
102 * {@code DataContentHandler} objects present, the returned
103 * {@code Object} can either be a typed Java object corresponding
104 * to the MIME type or an {@code InputStream} object that contains the
105 * content as bytes.
106 * <PRE>
107 * String content1 = ap1.getContent();
108 * java.io.InputStream content2 = ap2.getContent();
109 * </PRE>
110 *
111 * The method {@code clearContent} removes all the content from an
112 * {@code AttachmentPart} object but does not affect its header information.
113 * <PRE>
114 * ap1.clearContent();
115 * </PRE>
116 *
117 * @since 1.6
118 */
119
120 public abstract class AttachmentPart {
121 /**
122 * Returns the number of bytes in this {@code AttachmentPart}
123 * object.
124 *
125 * @return the size of this {@code AttachmentPart} object in bytes
126 * or -1 if the size cannot be determined
127 * @exception SOAPException if the content of this attachment is
128 * corrupted of if there was an exception while trying
129 * to determine the size.
130 */
131 public abstract int getSize() throws SOAPException;
132
133 /**
134 * Clears out the content of this {@code AttachmentPart} object.
135 * The MIME header portion is left untouched.
|
1 /*
2 * Copyright (c) 2004, 2015, Oracle and/or its affiliates. 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. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
33
34 /**
35 * A single attachment to a {@code SOAPMessage} object. A {@code SOAPMessage}
36 * object may contain zero, one, or many {@code AttachmentPart} objects.
37 * Each {@code AttachmentPart} object consists of two parts,
38 * application-specific content and associated MIME headers. The
39 * MIME headers consists of name/value pairs that can be used to
40 * identify and describe the content.
41 * <p>
42 * An {@code AttachmentPart} object must conform to certain standards.
43 * <OL>
44 * <LI>It must conform to <a href="http://www.ietf.org/rfc/rfc2045.txt">
45 * MIME [RFC2045] standards</a>
46 * <LI>It MUST contain content
47 * <LI>The header portion MUST include the following header:
48 * <UL>
49 * <LI>{@code Content-Type}<br>
50 * This header identifies the type of data in the content of an
51 * {@code AttachmentPart} object and MUST conform to [RFC2045].
52 * The following is an example of a Content-Type header:
53 * {@code
54 * Content-Type: application/xml
55 * }
56 * The following line of code, in which {@code ap} is an
57 * {@code AttachmentPart} object, sets the header shown in
58 * the previous example.
59 * {@code
60 * ap.setMimeHeader("Content-Type", "application/xml");
61 * }
62 * </UL>
63 * </OL>
64 * <p>
65 * There are no restrictions on the content portion of an {@code
66 * AttachmentPart} object. The content may be anything from a
67 * simple plain text object to a complex XML document or image file.
68 *
69 * <p>
70 * An {@code AttachmentPart} object is created with the method
71 * {@code SOAPMessage.createAttachmentPart}. After setting its MIME headers,
72 * the {@code AttachmentPart} object is added to the message
73 * that created it with the method {@code SOAPMessage.addAttachmentPart}.
74 *
75 * <p>
76 * The following code fragment, in which {@code m} is a
77 * {@code SOAPMessage} object and {@code contentStringl} is a
78 * {@code String}, creates an instance of {@code AttachmentPart},
79 * sets the {@code AttachmentPart} object with some content and
80 * header information, and adds the {@code AttachmentPart} object to
81 * the {@code SOAPMessage} object.
82 * {@code
83 * AttachmentPart ap1 = m.createAttachmentPart();
84 * ap1.setContent(contentString1, "text/plain");
85 * m.addAttachmentPart(ap1);
86 * }
87 *
88 *
89 * <p>
90 * The following code fragment creates and adds a second
91 * {@code AttachmentPart} instance to the same message. {@code jpegData}
92 * is a binary byte buffer representing the jpeg file.
93 * {@code
94 * AttachmentPart ap2 = m.createAttachmentPart();
95 * byte[] jpegData = ...;
96 * ap2.setContent(new ByteArrayInputStream(jpegData), "image/jpeg");
97 * m.addAttachmentPart(ap2);
98 * }
99 * <p>
100 * The {@code getContent} method retrieves the contents and header from
101 * an {@code AttachmentPart} object. Depending on the
102 * {@code DataContentHandler} objects present, the returned
103 * {@code Object} can either be a typed Java object corresponding
104 * to the MIME type or an {@code InputStream} object that contains the
105 * content as bytes.
106 * {@code
107 * String content1 = ap1.getContent();
108 * java.io.InputStream content2 = ap2.getContent();
109 * }
110 *
111 * The method {@code clearContent} removes all the content from an
112 * {@code AttachmentPart} object but does not affect its header information.
113 * {@code
114 * ap1.clearContent();
115 * }
116 *
117 * @since 1.6
118 */
119
120 public abstract class AttachmentPart {
121 /**
122 * Returns the number of bytes in this {@code AttachmentPart}
123 * object.
124 *
125 * @return the size of this {@code AttachmentPart} object in bytes
126 * or -1 if the size cannot be determined
127 * @exception SOAPException if the content of this attachment is
128 * corrupted of if there was an exception while trying
129 * to determine the size.
130 */
131 public abstract int getSize() throws SOAPException;
132
133 /**
134 * Clears out the content of this {@code AttachmentPart} object.
135 * The MIME header portion is left untouched.
|