1 // ======================================================================== 2 // Copyright (c) 2004-2009 Mort Bay Consulting Pty. Ltd. 3 // ------------------------------------------------------------------------ 4 // All rights reserved. This program and the accompanying materials 5 // are made available under the terms of the Eclipse Public License v1.0 6 // and Apache License v2.0 which accompanies this distribution. 7 // The Eclipse Public License is available at 8 // http://www.eclipse.org/legal/epl-v10.html 9 // The Apache License v2.0 is available at 10 // http://www.opensource.org/licenses/apache2.0.php 11 // You may elect to redistribute this code under either of these licenses. 12 // ======================================================================== 13 14 package org.eclipse.jetty.io; 15 16 import java.io.IOException; 17 18 19 /** 20 * 21 * A transport EndPoint 22 */ 23 public interface EndPoint 24 { 25 /** 26 * Shutdown any backing output stream associated with the endpoint 27 */ 28 void shutdownOutput() throws IOException; 29 30 /** 31 * Close any backing stream associated with the endpoint 32 */ 33 void close() throws IOException; 34 35 /** 36 * Fill the buffer from the current putIndex to it's capacity from whatever 37 * byte source is backing the buffer. The putIndex is increased if bytes filled. 38 * The buffer may chose to do a compact before filling. 39 * @return an <code>int</code> value indicating the number of bytes 40 * filled or -1 if EOF is reached. 41 */ 42 int fill(Buffer buffer) throws IOException; 43 44 45 /** 46 * Flush the buffer from the current getIndex to it's putIndex using whatever byte 47 * sink is backing the buffer. The getIndex is updated with the number of bytes flushed. 48 * Any mark set is cleared. 49 * If the entire contents of the buffer are flushed, then an implicit empty() is done. 50 * 51 * @param buffer The buffer to flush. This buffers getIndex is updated. 52 * @return the number of bytes written 53 */ 54 int flush(Buffer buffer) throws IOException; 55 56 /** 57 * Flush the buffer from the current getIndex to it's putIndex using whatever byte 58 * sink is backing the buffer. The getIndex is updated with the number of bytes flushed. 59 * Any mark set is cleared. 60 * If the entire contents of the buffer are flushed, then an implicit empty() is done. 61 * The passed header/trailer buffers are written before/after the contents of this buffer. This may be done 62 * either as gather writes, as a poke into this buffer or as several writes. The implementation is free to 63 * select the optimal mechanism. 64 * @param header A buffer to write before flushing this buffer. This buffers getIndex is updated. 65 * @param buffer The buffer to flush. This buffers getIndex is updated. 66 * @param trailer A buffer to write after flushing this buffer. This buffers getIndex is updated. 67 * @return the total number of bytes written. 68 */ 69 int flush(Buffer header, Buffer buffer, Buffer trailer) throws IOException; 70 71 72 /* ------------------------------------------------------------ */ 73 /** 74 * @return The local IP address to which this <code>EndPoint</code> is bound, or <code>null</code> 75 * if this <code>EndPoint</code> does not represent a network connection. 76 */ 77 public String getLocalAddr(); 78 79 /* ------------------------------------------------------------ */ 80 /** 81 * @return The local host name to which this <code>EndPoint</code> is bound, or <code>null</code> 82 * if this <code>EndPoint</code> does not represent a network connection. 83 */ 84 public String getLocalHost(); 85 86 /* ------------------------------------------------------------ */ 87 /** 88 * @return The local port number on which this <code>EndPoint</code> is listening, or <code>0</code> 89 * if this <code>EndPoint</code> does not represent a network connection. 90 */ 91 public int getLocalPort(); 92 93 /* ------------------------------------------------------------ */ 94 /** 95 * @return The remote IP address to which this <code>EndPoint</code> is connected, or <code>null</code> 96 * if this <code>EndPoint</code> does not represent a network connection. 97 */ 98 public String getRemoteAddr(); 99 100 /* ------------------------------------------------------------ */ 101 /** 102 * @return The host name of the remote machine to which this <code>EndPoint</code> is connected, or <code>null</code> 103 * if this <code>EndPoint</code> does not represent a network connection. 104 */ 105 public String getRemoteHost(); 106 107 /* ------------------------------------------------------------ */ 108 /** 109 * @return The remote port number to which this <code>EndPoint</code> is connected, or <code>0</code> 110 * if this <code>EndPoint</code> does not represent a network connection. 111 */ 112 public int getRemotePort(); 113 114 115 /* ------------------------------------------------------------ */ 116 public boolean isBlocking(); 117 118 /* ------------------------------------------------------------ */ 119 public boolean isBufferred(); 120 121 /* ------------------------------------------------------------ */ 122 public boolean blockReadable(long millisecs) throws IOException; 123 124 /* ------------------------------------------------------------ */ 125 public boolean blockWritable(long millisecs) throws IOException; 126 127 /* ------------------------------------------------------------ */ 128 public boolean isOpen(); 129 130 /* ------------------------------------------------------------ */ 131 /** 132 * @return The underlying transport object (socket, channel, etc.) 133 */ 134 public Object getTransport(); 135 136 /* ------------------------------------------------------------ */ 137 /** 138 * @return True if the endpoint has some buffered input data 139 */ 140 public boolean isBufferingInput(); 141 142 /* ------------------------------------------------------------ */ 143 /** 144 * @return True if the endpoint has some buffered output data 145 */ 146 public boolean isBufferingOutput(); 147 148 /* ------------------------------------------------------------ */ 149 /** Flush any buffered output. 150 * May fail to write all data if endpoint is non-blocking 151 * @throws IOException 152 */ 153 public void flush() throws IOException; 154 155 156 /* ------------------------------------------------------------ */ 157 /** Get the max idle time in ms. 158 * <p>The max idle time is the time the endpoint can be idle before 159 * extraordinary handling takes place. This loosely corresponds to 160 * the {@link java.net.Socket#getSoTimeout()} for blocking connections, 161 * but {@link AsyncEndPoint} implementations must use other mechanisms 162 * to implement the max idle time. 163 * @return the max idle time in ms. 164 */ 165 public int getMaxIdleTime(); 166 167 /* ------------------------------------------------------------ */ 168 /** Set the max idle time. 169 * @param timeMs the max idle time in MS. 170 * @throws IOException if the timeout cannot be set. 171 */ 172 public void setMaxIdleTime(int timeMs) throws IOException; 173 174 175 176 }