Skip to contentMethod: run()
1: /*
2: * Copyright (c) 2021, 2022 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.util;
18:
19: import java.io.InputStream;
20: import java.io.OutputStream;
21: import java.security.AccessController;
22: import java.security.PrivilegedAction;
23: import java.util.Iterator;
24: import java.util.ServiceLoader;
25:
26: /**
27: * Service lookup is used to find implementations of this interface.
28: *
29: * It contains the methods to instance different encoders/decoders and
30: * other streams required by the API.
31: *
32: * @since JavaMail 2.1
33: */
34: public interface StreamProvider {
35:
36:         /**
37:          * Enumeration with the different encoder types supported by the Mail API.
38:          *
39:          * @since JavaMail 2.1
40:          */
41:         public static enum EncoderTypes {
42:                 
43:                 BASE_64("base64"),
44:                 B_ENCODER("b"),
45:                 Q_ENCODER("q"),
46:                 BINARY_ENCODER("binary"),
47:                 BIT7_ENCODER("7bit"),
48:                 BIT8_ENCODER("8bit"),
49:                 QUOTED_PRINTABLE_ENCODER("quoted-printable"),
50:                 UU_ENCODER("uuencode"),
51:                 X_UU_ENCODER("x-uuencode"),
52:                 X_UUE("x-uue");
53:                 
54:                 private final String encoder;
55:                 
56:                 private EncoderTypes(String encoder) {
57:                         this.encoder = encoder;
58:                 }
59:
60:                 public String getEncoder() {
61:                         return encoder;
62:                 }
63:         }
64:
65: /**
66: * Creates a 'base64' decoder from the InputStream.
67: * @param in the InputStream
68: * @return the decoder
69: */
70: InputStream inputBase64(InputStream in);
71:
72: /**
73: * Creates a 'base64' encoder from the OutputStream.
74: * @param out the OutputStream
75: * @return the encoder
76: */
77: OutputStream outputBase64(OutputStream out);
78:
79: /**
80: * Creates a 'binary', '7bit' and '8bit' decoder from the InputStream.
81: * @param in the InputStream
82: * @return the decoder
83: */
84: InputStream inputBinary(InputStream in);
85:
86: /**
87: * Creates a 'binary', '7bit' and '8bit' encoder from the OutputStream.
88: * @param out the OutputStream
89: * @return the encoder
90: */
91: OutputStream outputBinary(OutputStream out);
92:
93: /**
94: * Creates a 'b' encoder from the OutputStream.
95: * @param out the OutputStream
96: * @return the encoder
97: */
98:         OutputStream outputB(OutputStream out);
99:
100: /**
101: * Creates a 'q' decoder from the InputStream.
102: * @param in the InputStream
103: * @return the decoder
104: */
105:         InputStream inputQ(InputStream in);
106:
107:         /**
108:          * Creates a 'q' encoder.
109:          * @param out the OutputStream
110:          * @param encodingWord true if we are Q-encoding a word within a phrase.
111:          * @return the encoder
112:          */
113:         OutputStream outputQ(OutputStream out, boolean encodingWord);
114:
115:         /**
116:          * Creates a new LineInputStream that supports reading CRLF terminated lines
117:          * containing only US-ASCII characters from an input stream
118:          * @param in the InputStream
119:          * @param allowutf8        allow UTF-8 characters?
120:          * @return the LineInputStream
121:          */
122:         LineInputStream inputLineStream(InputStream in, boolean allowutf8);
123:
124:         /**
125:          * Creates a new LineOutputStream that supports writing out Strings as a sequence of bytes terminated
126:          * by a CRLF sequence. The String must contain only US-ASCII characters.
127:          * @param out the OutputStream
128:          * @param allowutf8        allow UTF-8 characters?
129:          * @return the LineOutputStream
130:          */
131:         LineOutputStream outputLineStream(OutputStream out, boolean allowutf8);
132:
133: /**
134: * Creates a 'quoted-printable' decoder from the InputStream.
135: * @param in the InputStream
136: * @return the decoder
137: */
138:         InputStream inputQP(InputStream in);
139:
140: /**
141: * Creates a 'quoted-printable' encoder from the OutputStream.
142: * @param out the OutputStream
143: * @return the encoder
144: */
145:         OutputStream outputQP(OutputStream out);
146:
147:         /**
148:          * Creates a new InputStream from the underlying byte array to be shared
149:          * between multiple readers.
150:          * @param buff the byte array
151:          * @return the InputStream
152:          */
153:         InputStream inputSharedByteArray(byte[] buff);
154:
155: /**
156: * Creates a 'uuencode', 'x-uuencode' and 'x-uue' decoder from the InputStream.
157: * @param in the InputStream
158: * @return the decoder
159: */
160:         InputStream inputUU(InputStream in);
161:
162:         /**
163:          * Creates a 'uuencode', 'x-uuencode' and 'x-uue' encoder from the OutputStream.
164:          * @param out the OutputStream
165:          * @param filename Specifies a name for the encoded buffer. It can be null.
166:          * @return the encoder
167:          */
168:         OutputStream outputUU(OutputStream out, String filename);
169:
170:         /**
171: * Creates a stream provider object. The provider is loaded using the
172: * {@link ServiceLoader#load(Class)} method. If there are no available
173: * service providers, this method throws an IllegalStateException.
174: * Users are recommended to cache the result of this method.
175: *
176: * @return a stream provider
177: */
178: public static StreamProvider provider() {
179: if (System.getSecurityManager() != null) {
180: return AccessController.doPrivileged(new PrivilegedAction<StreamProvider>() {
181: public StreamProvider run() {
182: return FactoryFinder.find(StreamProvider.class);
183: }
184: });
185: } else {
186: return FactoryFinder.find(StreamProvider.class);
187: }
188: }
189: }