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