Transport.java revision e4a7cc440f081ef9c4375a2bd2f82680cc11b152 
1/*
2 * Copyright (C) 2008 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package com.android.email.mail;
18
19import java.io.IOException;
20import java.io.InputStream;
21import java.io.OutputStream;
22import java.net.SocketException;
23import java.net.URI;
24
25/**
26 * This interface defines a "transport", which is defined here as being one layer below the
27 * specific wire protocols such as POP3, IMAP, or SMTP.
28 *
29 * Practically speaking, it provides a definition of the common functionality between them
30 * (dealing with sockets & streams, SSL, logging, and so forth), and provides a seam just below
31 * the individual protocols to enable better testing.
32 *
33 * The following features are supported and presumed to be common:
34 *
35 *  Interpretation of URI
36 *  Support for SSL and TLS wireline security
37 */
38public interface Transport {
39
40    /**
41     * Connection security options for transport that supports SSL and/or TLS
42     */
43    public static final int CONNECTION_SECURITY_NONE = 0;
44    public static final int CONNECTION_SECURITY_SSL = 1;
45    public static final int CONNECTION_SECURITY_TLS = 2;
46
47    /**
48     * Get a new transport, using an existing one as a model.  The new transport is configured as if
49     * setUri() and setSecurity() have been called, but not opened or connected in any way.
50     * @return a new Transport ready to open()
51     */
52    public Transport newInstanceWithConfiguration();
53
54    /**
55     * Set the Uri for the connection.
56     *
57     * @param uri The Uri for the connection
58     * @param defaultPort If the Uri does not include an explicit port, this value will be used.
59     */
60    public void setUri(URI uri, int defaultPort);
61
62    /**
63     * @return Returns the host part of the Uri
64     */
65    public String getHost();
66
67    /**
68     * @return Returns the port (either from the Uri or from the default)
69     */
70    public int getPort();
71
72    /**
73     * Returns the user info parts of the Uri, if any were supplied.  Typically, [0] is the user
74     * and [1] is the password.
75     * @return Returns the user info parts of the Uri.  Null if none were supplied.
76     */
77    public String[] getUserInfoParts();
78
79    /**
80     * Set the desired security mode for this connection.
81     * @param connectionSecurity A value indicating the desired security mode.
82     * @param trustAllCertificates true to allow unverifiable certificates to be used
83     */
84    public void setSecurity(int connectionSecurity, boolean trustAllCertificates);
85
86    /**
87     * @return Returns the desired security mode for this connection.
88     */
89    public int getSecurity();
90
91    /**
92     * @return true if the security mode indicates that SSL is possible
93     */
94    public boolean canTrySslSecurity();
95
96    /**
97     * @return true if the security mode indicates that TLS is possible
98     */
99    public boolean canTryTlsSecurity();
100
101    /**
102     * @return true if the security mode indicates that all certificates can be trusted
103     */
104    public boolean canTrustAllCertificates();
105
106    /**
107     * Set the socket timeout.
108     * @param timeoutMilliseconds the read timeout value if greater than {@code 0}, or
109     *            {@code 0} for an infinite timeout.
110     */
111    public void setSoTimeout(int timeoutMilliseconds) throws SocketException;
112
113        /**
114     * Attempts to open the connection using the supplied parameters, and using SSL if indicated.
115     */
116    public void open() throws MessagingException, CertificateValidationException;
117
118    /**
119     * Attempts to reopen the connection using TLS.
120     */
121    public void reopenTls() throws MessagingException;
122
123    /**
124     * @return true if the connection is open
125     */
126    public boolean isOpen();
127
128    /**
129     * Closes the connection.  Does not send any closure messages, simply closes the socket and the
130     * associated streams.  Best effort only.  Catches all exceptions and always returns.
131     *
132     * MUST NOT throw any exceptions.
133     */
134    public void close();
135
136    /**
137     * @return returns the active input stream
138     */
139    public InputStream getInputStream();
140
141    /**
142     * @return returns the active output stream
143     */
144    public OutputStream getOutputStream();
145
146    /**
147     * Write a single line to the server, and may generate a log entry (if enabled).
148     * @param s The text to send to the server.
149     * @param sensitiveReplacement If the command includes sensitive data (e.g. authentication)
150     * please pass a replacement string here (for logging).  Most callers simply pass null,
151     */
152    void writeLine(String s, String sensitiveReplacement) throws IOException;
153
154    /**
155     * Reads a single line from the server.  Any delimiter characters will not be included in the
156     * result.  May generate a log entry, if enabled.
157     * @return Returns the string from the server.
158     * @throws IOException
159     */
160    String readLine() throws IOException;
161
162}
163