Transport.java revision 96c5af40d639d629267794f4f0338a267ff94ce5
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_TLS_OPTIONAL = 1; 45 public static final int CONNECTION_SECURITY_TLS_REQUIRED = 2; 46 public static final int CONNECTION_SECURITY_SSL_REQUIRED = 3; 47 public static final int CONNECTION_SECURITY_SSL_OPTIONAL = 4; 48 49 /** 50 * Get a new transport, using an existing one as a model. The new transport is configured as if 51 * setUri() and setSecurity() have been called, but not opened or connected in any way. 52 * @return a new Transport ready to open() 53 */ 54 public Transport newInstanceWithConfiguration(); 55 56 /** 57 * Set the Uri for the connection. 58 * 59 * @param uri The Uri for the connection 60 * @param defaultPort If the Uri does not include an explicit port, this value will be used. 61 */ 62 public void setUri(URI uri, int defaultPort); 63 64 /** 65 * @return Returns the host part of the Uri 66 */ 67 public String getHost(); 68 69 /** 70 * @return Returns the port (either from the Uri or from the default) 71 */ 72 public int getPort(); 73 74 /** 75 * Returns the user info parts of the Uri, if any were supplied. Typically, [0] is the user 76 * and [1] is the password. 77 * @return Returns the user info parts of the Uri. Null if none were supplied. 78 */ 79 public String[] getUserInfoParts(); 80 81 /** 82 * Set the desired security mode for this connection. 83 * @param connectionSecurity A value indicating the desired security mode. 84 */ 85 public void setSecurity(int connectionSecurity); 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 (optional or required) 94 */ 95 public boolean canTrySslSecurity(); 96 97 /** 98 * @return true if the security mode indicates that TLS is possible (optional or required) 99 */ 100 public boolean canTryTlsSecurity(); 101 102 /** 103 * Set the socket timeout. 104 * @param timeoutMilliseconds the read timeout value if greater than {@code 0}, or 105 * {@code 0} for an infinite timeout. 106 */ 107 public void setSoTimeout(int timeoutMilliseconds) throws SocketException; 108 109 /** 110 * Attempts to open the connection using the supplied parameters, and using SSL if indicated. 111 */ 112 public void open() throws MessagingException, CertificateValidationException; 113 114 /** 115 * Attempts to reopen the connection using TLS. 116 */ 117 public void reopenTls() throws MessagingException; 118 119 /** 120 * @return true if the connection is open 121 */ 122 public boolean isOpen(); 123 124 /** 125 * Closes the connection. Does not send any closure messages, simply closes the socket and the 126 * associated streams. Best effort only. Catches all exceptions and always returns. 127 * 128 * MUST NOT throw any exceptions. 129 */ 130 public void close(); 131 132 /** 133 * @return returns the active input stream 134 */ 135 public InputStream getInputStream(); 136 137 /** 138 * @return returns the active output stream 139 */ 140 public OutputStream getOutputStream(); 141 142 /** 143 * Write a single line to the server, and may generate a log entry (if enabled). 144 * @param s The text to send to the server. 145 * @param sensitiveReplacement If the command includes sensitive data (e.g. authentication) 146 * please pass a replacement string here (for logging). Most callers simply pass null, 147 */ 148 void writeLine(String s, String sensitiveReplacement) throws IOException; 149 150 /** 151 * Reads a single line from the server. Any delimiter characters will not be included in the 152 * result. May generate a log entry, if enabled. 153 * @return Returns the string from the server. 154 * @throws IOException 155 */ 156 String readLine() throws IOException; 157 158} 159