jakarta.mail.util.StreamProvider Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of jakarta.mail Show documentation
The newest version!
/*
 * Copyright (c) 2021, 2023 Oracle and/or its affiliates. All rights reserved.
 *
 * This program and the accompanying materials are made available under the
 * terms of the Eclipse Public License v. 2.0, which is available at
 * http://www.eclipse.org/legal/epl-2.0.
 *
 * This Source Code may also be made available under the following Secondary
 * Licenses when the conditions for such availability set forth in the
 * Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
 * version 2 with the GNU Classpath Exception, which is available at
 * https://www.gnu.org/software/classpath/license.html.
 *
 * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
 */

package jakarta.mail.util;

import java.io.InputStream;
import java.io.OutputStream;
import java.security.AccessController;
import java.security.PrivilegedAction;
import java.util.ServiceLoader;

/**
 * Service lookup is used to find implementations of this interface.
 *
 * It contains the methods to instance different encoders/decoders and
 * other streams required by the API.
 *
 * @since JavaMail 2.1
 */
public interface StreamProvider {

    /**
     * Enumeration with the different encoder types supported by the Mail API.
     *
     * @since JavaMail 2.1
     */
    enum EncoderTypes {

        BASE_64("base64"),
        B_ENCODER("b"),
        Q_ENCODER("q"),
        BINARY_ENCODER("binary"),
        BIT7_ENCODER("7bit"),
        BIT8_ENCODER("8bit"),
        QUOTED_PRINTABLE_ENCODER("quoted-printable"),
        UU_ENCODER("uuencode"),
        X_UU_ENCODER("x-uuencode"),
        X_UUE("x-uue");

        private final String encoder;

        EncoderTypes(String encoder) {
            this.encoder = encoder;
        }

        public String getEncoder() {
            return encoder;
        }
    }

    /**
     * Creates a 'base64' decoder from the InputStream.
     *
     * @param in the InputStream
     * @return the decoder
     */
    InputStream inputBase64(InputStream in);

    /**
     * Creates a 'base64' encoder from the OutputStream.
     *
     * @param out the OutputStream
     * @return the encoder
     */
    OutputStream outputBase64(OutputStream out);

    /**
     * Creates a 'binary', '7bit' and '8bit' decoder from the InputStream.
     *
     * @param in the InputStream
     * @return the decoder
     */
    InputStream inputBinary(InputStream in);

    /**
     * Creates a 'binary', '7bit' and '8bit' encoder from the OutputStream.
     *
     * @param out the OutputStream
     * @return the encoder
     */
    OutputStream outputBinary(OutputStream out);

    /**
     * Creates a 'b' encoder from the OutputStream.
     *
     * @param out the OutputStream
     * @return the encoder
     */
    OutputStream outputB(OutputStream out);

    /**
     * Creates a 'q' decoder from the InputStream.
     *
     * @param in the InputStream
     * @return the decoder
     */
    InputStream inputQ(InputStream in);

    /**
     * Creates a 'q' encoder.
     *
     * @param out          the OutputStream
     * @param encodingWord true if we are Q-encoding a word within a phrase.
     * @return the encoder
     */
    OutputStream outputQ(OutputStream out, boolean encodingWord);

    /**
     * Creates a new LineInputStream that supports reading CRLF terminated lines
     * containing only US-ASCII characters from an input stream
     *
     * @param in        the InputStream
     * @param allowutf8 allow UTF-8 characters?
     * @return the LineInputStream
     */
    LineInputStream inputLineStream(InputStream in, boolean allowutf8);

    /**
     * Creates a new LineOutputStream that supports writing out Strings as a sequence of bytes terminated
     * by a CRLF sequence. The String must contain only US-ASCII characters.
     *
     * @param out       the OutputStream
     * @param allowutf8 allow UTF-8 characters?
     * @return the LineOutputStream
     */
    LineOutputStream outputLineStream(OutputStream out, boolean allowutf8);

    /**
     * Creates a 'quoted-printable' decoder from the InputStream.
     *
     * @param in the InputStream
     * @return the decoder
     */
    InputStream inputQP(InputStream in);

    /**
     * Creates a 'quoted-printable' encoder from the OutputStream.
     *
     * @param out the OutputStream
     * @return the encoder
     */
    OutputStream outputQP(OutputStream out);

    /**
     * Creates a new InputStream from the underlying byte array to be shared
     * between multiple readers.
     *
     * @param buff the byte array
     * @return the InputStream
     */
    InputStream inputSharedByteArray(byte[] buff);

    /**
     * Creates a 'uuencode', 'x-uuencode' and 'x-uue' decoder from the InputStream.
     *
     * @param in the InputStream
     * @return the decoder
     */
    InputStream inputUU(InputStream in);

    /**
     * Creates a 'uuencode', 'x-uuencode' and 'x-uue' encoder from the OutputStream.
     *
     * @param out      the OutputStream
     * @param filename Specifies a name for the encoded buffer. It can be null.
     * @return the encoder
     */
    OutputStream outputUU(OutputStream out, String filename);

    /**
     * Creates a stream provider object. The provider is loaded using the
     * {@link ServiceLoader#load(Class)} method. If there are no available
     * service providers, this method throws an IllegalStateException.
     * Users are recommended to cache the result of this method.
     *
     * @return a stream provider
     */
    static StreamProvider provider() {
        if (System.getSecurityManager() != null) {
            return AccessController.doPrivileged(new PrivilegedAction() {
                public StreamProvider run() {
                    return FactoryFinder.find(StreamProvider.class);
                }
            });
        } else {
            return FactoryFinder.find(StreamProvider.class);
        }
    }
}