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