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