Transport.java revision a50fc99b0c433f0cde31ba1c7ab87fb9ea86345d 
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 com.android.emailcommon.mail.CertificateValidationException;
20import com.android.emailcommon.mail.MessagingException;
21
22import java.io.IOException;
23import java.io.InputStream;
24import java.io.OutputStream;
25import java.net.InetAddress;
26import java.net.SocketException;
27import java.net.URI;
28
29/**
30 * This interface defines a "transport", which is defined here as being one layer below the
31 * specific wire protocols such as POP3, IMAP, or SMTP.
32 *
33 * Practically speaking, it provides a definition of the common functionality between them
34 * (dealing with sockets & streams, SSL, logging, and so forth), and provides a seam just below
35 * the individual protocols to enable better testing.
36 *
37 * The following features are supported and presumed to be common:
38 *
39 *  Interpretation of URI
40 *  Support for SSL and TLS wireline security
41 */
42public interface Transport {
43
44    /**
45     * Connection security options for transport that supports SSL and/or TLS
46     */
47    public static final int CONNECTION_SECURITY_NONE = 0;
48    public static final int CONNECTION_SECURITY_SSL = 1;
49    public static final int CONNECTION_SECURITY_TLS = 2;
50
51    /**
52     * Get a new transport, using an existing one as a model.  The new transport is configured as if
53     * setUri() and setSecurity() have been called, but not opened or connected in any way.
54     * @return a new Transport ready to open()
55     */
56    public Transport newInstanceWithConfiguration();
57
58    /**
59     * Set the Uri for the connection.
60     *
61     * @param uri The Uri for the connection
62     * @param defaultPort If the Uri does not include an explicit port, this value will be used.
63     * @deprecated use the individual methods {@link #setHost(String)} and {@link #setPort(int)}
64     */
65    @Deprecated
66    public void setUri(URI uri, int defaultPort);
67
68    /**
69     * Sets the host
70     */
71    public void setHost(String host);
72
73    /**
74     * Sets the port
75     */
76    public void setPort(int port);
77
78    /**
79     * Returns the host or {@code null} if none was specified.
80     */
81    public String getHost();
82
83    /**
84     * Returns the port or {@code 0} if none was specified.
85     */
86    public int getPort();
87
88    /**
89     * Returns the user info parts of the Uri, if any were supplied.  Typically, [0] is the user
90     * and [1] is the password.
91     * @return Returns the user info parts of the Uri.  Null if none were supplied.
92     * @deprecated do not use this method. user info parts should not be stored in the transport.
93     */
94    @Deprecated
95    public String[] getUserInfoParts();
96
97    /**
98     * Set the desired security mode for this connection.
99     * @param connectionSecurity A value indicating the desired security mode.
100     * @param trustAllCertificates true to allow unverifiable certificates to be used
101     */
102    public void setSecurity(int connectionSecurity, boolean trustAllCertificates);
103
104    /**
105     * @return Returns the desired security mode for this connection.
106     */
107    public int getSecurity();
108
109    /**
110     * @return true if the security mode indicates that SSL is possible
111     */
112    public boolean canTrySslSecurity();
113
114    /**
115     * @return true if the security mode indicates that TLS is possible
116     */
117    public boolean canTryTlsSecurity();
118
119    /**
120     * @return true if the security mode indicates that all certificates can be trusted
121     */
122    public boolean canTrustAllCertificates();
123
124    /**
125     * Set the socket timeout.
126     * @param timeoutMilliseconds the read timeout value if greater than {@code 0}, or
127     *            {@code 0} for an infinite timeout.
128     */
129    public void setSoTimeout(int timeoutMilliseconds) throws SocketException;
130
131        /**
132     * Attempts to open the connection using the supplied parameters, and using SSL if indicated.
133     */
134    public void open() throws MessagingException, CertificateValidationException;
135
136    /**
137     * Attempts to reopen the connection using TLS.
138     */
139    public void reopenTls() throws MessagingException;
140
141    /**
142     * @return true if the connection is open
143     */
144    public boolean isOpen();
145
146    /**
147     * Closes the connection.  Does not send any closure messages, simply closes the socket and the
148     * associated streams.  Best effort only.  Catches all exceptions and always returns.
149     *
150     * MUST NOT throw any exceptions.
151     */
152    public void close();
153
154    /**
155     * @return returns the active input stream
156     */
157    public InputStream getInputStream();
158
159    /**
160     * @return returns the active output stream
161     */
162    public OutputStream getOutputStream();
163
164    /**
165     * Write a single line to the server, and may generate a log entry (if enabled).
166     * @param s The text to send to the server.
167     * @param sensitiveReplacement If the command includes sensitive data (e.g. authentication)
168     * please pass a replacement string here (for logging).  Most callers simply pass null,
169     */
170    void writeLine(String s, String sensitiveReplacement) throws IOException;
171
172    /**
173     * Reads a single line from the server.  Any delimiter characters will not be included in the
174     * result.  May generate a log entry, if enabled.
175     * @return Returns the string from the server.
176     * @throws IOException
177     */
178    String readLine() throws IOException;
179
180    /**
181     * @return The local address.  If we have an open socket, get the local address from this.
182     *     Otherwise simply use {@link InetAddress#getLocalHost}.
183     */
184    InetAddress getLocalAddress() throws IOException;
185}
186