Package: MimePart

MimePart

Coverage

1: /*
2: * Copyright (c) 1997, 2023 Oracle and/or its affiliates. All rights reserved.
3: *
4: * This program and the accompanying materials are made available under the
5: * terms of the Eclipse Public License v. 2.0, which is available at
6: * http://www.eclipse.org/legal/epl-2.0.
7: *
8: * This Source Code may also be made available under the following Secondary
9: * Licenses when the conditions for such availability set forth in the
10: * Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
11: * version 2 with the GNU Classpath Exception, which is available at
12: * https://www.gnu.org/software/classpath/license.html.
13: *
14: * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
15: */
16:
17: package jakarta.mail.internet;
18:
19: import jakarta.mail.IllegalWriteException;
20: import jakarta.mail.MessagingException;
21: import jakarta.mail.Part;
22:
23: import java.util.Enumeration;
24:
25: /**
26: * The MimePart interface models an <strong>Entity</strong> as defined
27: * by MIME (RFC2045, Section 2.4). <p>
28: *
29: * MimePart extends the Part interface to add additional RFC822 and MIME
30: * specific semantics and attributes. It provides the base interface for
31: * the MimeMessage and MimeBodyPart classes
32: *
33: * <hr> <strong>A note on RFC822 and MIME headers</strong><p>
34: *
35: * RFC822 and MIME header fields <strong>must</strong> contain only
36: * US-ASCII characters. If a header contains non US-ASCII characters,
37: * it must be encoded as per the rules in RFC 2047. The MimeUtility
38: * class provided in this package can be used to to achieve this.
39: * Callers of the <code>setHeader</code>, <code>addHeader</code>, and
40: * <code>addHeaderLine</code> methods are responsible for enforcing
41: * the MIME requirements for the specified headers. In addition, these
42: * header fields must be folded (wrapped) before being sent if they
43: * exceed the line length limitation for the transport (1000 bytes for
44: * SMTP). Received headers may have been folded. The application is
45: * responsible for folding and unfolding headers as appropriate.
46: *
47: * @author John Mani
48: * @see MimeUtility
49: * @see jakarta.mail.Part
50: */
51:
52: public interface MimePart extends Part {
53:
54: /**
55: * Get the values of all header fields available for this header,
56: * returned as a single String, with the values separated by the
57: * delimiter. If the delimiter is <code>null</code>, only the
58: * first value is returned.
59: *
60: * @param name the name of this header
61: * @param delimiter delimiter between fields in returned string
62: * @return the value fields for all headers with
63: * this name
64: * @throws MessagingException for failures
65: */
66: String getHeader(String name, String delimiter)
67: throws MessagingException;
68:
69: /**
70: * Add a raw RFC822 header-line.
71: *
72: * @param line the line to add
73: * @throws IllegalWriteException if the underlying
74: * implementation does not support modification
75: * @throws IllegalStateException if this Part is
76: * obtained from a READ_ONLY folder
77: * @throws MessagingException for other failures
78: */
79: void addHeaderLine(String line) throws MessagingException;
80:
81: /**
82: * Get all header lines as an Enumeration of Strings. A Header
83: * line is a raw RFC822 header-line, containing both the "name"
84: * and "value" field.
85: *
86: * @return an Enumeration of Strings
87: * @throws MessagingException for failures
88: */
89: Enumeration<String> getAllHeaderLines() throws MessagingException;
90:
91: /**
92: * Get matching header lines as an Enumeration of Strings.
93: * A Header line is a raw RFC822 header-line, containing both
94: * the "name" and "value" field.
95: *
96: * @param names the headers to return
97: * @return an Enumeration of Strings
98: * @throws MessagingException for failures
99: */
100: Enumeration<String> getMatchingHeaderLines(String[] names)
101: throws MessagingException;
102:
103: /**
104: * Get non-matching header lines as an Enumeration of Strings.
105: * A Header line is a raw RFC822 header-line, containing both
106: * the "name" and "value" field.
107: *
108: * @param names the headers to not return
109: * @return an Enumeration of Strings
110: * @throws MessagingException for failures
111: */
112: Enumeration<String> getNonMatchingHeaderLines(String[] names)
113: throws MessagingException;
114:
115: /**
116: * Get the transfer encoding of this part.
117: *
118: * @return content-transfer-encoding
119: * @throws MessagingException for failures
120: */
121: String getEncoding() throws MessagingException;
122:
123: /**
124: * Get the Content-ID of this part. Returns null if none present.
125: *
126: * @return content-ID
127: * @throws MessagingException for failures
128: */
129: String getContentID() throws MessagingException;
130:
131: /**
132: * Get the Content-MD5 digest of this part. Returns null if
133: * none present.
134: *
135: * @return content-MD5
136: * @throws MessagingException for failures
137: */
138: String getContentMD5() throws MessagingException;
139:
140: /**
141: * Set the Content-MD5 of this part.
142: *
143: * @param md5 the MD5 value
144: * @throws IllegalWriteException if the underlying
145: * implementation does not support modification
146: * @throws IllegalStateException if this Part is
147: * obtained from a READ_ONLY folder
148: */
149: void setContentMD5(String md5) throws MessagingException;
150:
151: /**
152: * Get the language tags specified in the Content-Language header
153: * of this MimePart. The Content-Language header is defined by
154: * RFC 1766. Returns <code>null</code> if this header is not
155: * available.
156: *
157: * @return array of content language strings
158: * @throws MessagingException for failures
159: */
160: String[] getContentLanguage() throws MessagingException;
161:
162: /**
163: * Set the Content-Language header of this MimePart. The
164: * Content-Language header is defined by RFC1766.
165: *
166: * @param languages array of language tags
167: * @throws IllegalWriteException if the underlying
168: * implementation does not support modification
169: * @throws IllegalStateException if this Part is
170: * obtained from a READ_ONLY folder
171: */
172: void setContentLanguage(String[] languages)
173: throws MessagingException;
174:
175: /**
176: * Convenience method that sets the given String as this
177: * part's content, with a MIME type of "text/plain". If the
178: * string contains non US-ASCII characters. it will be encoded
179: * using the platform's default charset. The charset is also
180: * used to set the "charset" parameter. <p>
181: *
182: * Note that there may be a performance penalty if
183: * <code>text</code> is large, since this method may have
184: * to scan all the characters to determine what charset to
185: * use. <p>
186: *
187: * If the charset is already known, use the
188: * <code>setText</code> method that takes the charset parameter.
189: *
190: * @param text the text content to set
191: * @throws MessagingException if an error occurs
192: * @see #setText(String text, String charset)
193: */
194: @Override
195: void setText(String text) throws MessagingException;
196:
197: /**
198: * Convenience method that sets the given String as this part's
199: * content, with a MIME type of "text/plain" and the specified
200: * charset. The given Unicode string will be charset-encoded
201: * using the specified charset. The charset is also used to set
202: * "charset" parameter.
203: *
204: * @param text the text content to set
205: * @param charset the charset to use for the text
206: * @throws MessagingException if an error occurs
207: */
208: void setText(String text, String charset)
209: throws MessagingException;
210:
211: /**
212: * Convenience method that sets the given String as this part's
213: * content, with a primary MIME type of "text" and the specified
214: * MIME subtype. The given Unicode string will be charset-encoded
215: * using the specified charset. The charset is also used to set
216: * the "charset" parameter.
217: *
218: * @param text the text content to set
219: * @param charset the charset to use for the text
220: * @param subtype the MIME subtype to use (e.g., "html")
221: * @throws MessagingException if an error occurs
222: * @since JavaMail 1.4
223: */
224: void setText(String text, String charset, String subtype)
225: throws MessagingException;
226: }