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 boolean isOutputShutdown();
31
32 /**
33 * Shutdown any backing input stream associated with the endpoint
34 */
35 void shutdownInput() throws IOException;
36
37 boolean isInputShutdown();
38
39 /**
40 * Close any backing stream associated with the endpoint
41 */
42 void close() throws IOException;
43
44 /**
45 * Fill the buffer from the current putIndex to it's capacity from whatever
46 * byte source is backing the buffer. The putIndex is increased if bytes filled.
47 * The buffer may chose to do a compact before filling.
48 * @return an <code>int</code> value indicating the number of bytes
49 * filled or -1 if EOF is reached.
50 */
51 int fill(Buffer buffer) throws IOException;
52
53
54 /**
55 * Flush the buffer from the current getIndex to it's putIndex using whatever byte
56 * sink is backing the buffer. The getIndex is updated with the number of bytes flushed.
57 * Any mark set is cleared.
58 * If the entire contents of the buffer are flushed, then an implicit empty() is done.
59 *
60 * @param buffer The buffer to flush. This buffers getIndex is updated.
61 * @return the number of bytes written
62 */
63 int flush(Buffer buffer) throws IOException;
64
65 /**
66 * Flush the buffer from the current getIndex to it's putIndex using whatever byte
67 * sink is backing the buffer. The getIndex is updated with the number of bytes flushed.
68 * Any mark set is cleared.
69 * If the entire contents of the buffer are flushed, then an implicit empty() is done.
70 * The passed header/trailer buffers are written before/after the contents of this buffer. This may be done
71 * either as gather writes, as a poke into this buffer or as several writes. The implementation is free to
72 * select the optimal mechanism.
73 * @param header A buffer to write before flushing this buffer. This buffers getIndex is updated.
74 * @param buffer The buffer to flush. This buffers getIndex is updated.
75 * @param trailer A buffer to write after flushing this buffer. This buffers getIndex is updated.
76 * @return the total number of bytes written.
77 */
78 int flush(Buffer header, Buffer buffer, Buffer trailer) throws IOException;
79
80
81 /* ------------------------------------------------------------ */
82 /**
83 * @return The local IP address to which this <code>EndPoint</code> is bound, or <code>null</code>
84 * if this <code>EndPoint</code> does not represent a network connection.
85 */
86 public String getLocalAddr();
87
88 /* ------------------------------------------------------------ */
89 /**
90 * @return The local host name to which this <code>EndPoint</code> is bound, or <code>null</code>
91 * if this <code>EndPoint</code> does not represent a network connection.
92 */
93 public String getLocalHost();
94
95 /* ------------------------------------------------------------ */
96 /**
97 * @return The local port number on which this <code>EndPoint</code> is listening, or <code>0</code>
98 * if this <code>EndPoint</code> does not represent a network connection.
99 */
100 public int getLocalPort();
101
102 /* ------------------------------------------------------------ */
103 /**
104 * @return The remote IP address to which this <code>EndPoint</code> is connected, or <code>null</code>
105 * if this <code>EndPoint</code> does not represent a network connection.
106 */
107 public String getRemoteAddr();
108
109 /* ------------------------------------------------------------ */
110 /**
111 * @return The host name of the remote machine to which this <code>EndPoint</code> is connected, or <code>null</code>
112 * if this <code>EndPoint</code> does not represent a network connection.
113 */
114 public String getRemoteHost();
115
116 /* ------------------------------------------------------------ */
117 /**
118 * @return The remote port number to which this <code>EndPoint</code> is connected, or <code>0</code>
119 * if this <code>EndPoint</code> does not represent a network connection.
120 */
121 public int getRemotePort();
122
123
124 /* ------------------------------------------------------------ */
125 public boolean isBlocking();
126
127 /* ------------------------------------------------------------ */
128 public boolean isBufferred();
129
130 /* ------------------------------------------------------------ */
131 public boolean blockReadable(long millisecs) throws IOException;
132
133 /* ------------------------------------------------------------ */
134 public boolean blockWritable(long millisecs) throws IOException;
135
136 /* ------------------------------------------------------------ */
137 public boolean isOpen();
138
139 /* ------------------------------------------------------------ */
140 /**
141 * @return The underlying transport object (socket, channel, etc.)
142 */
143 public Object getTransport();
144
145 /* ------------------------------------------------------------ */
146 /**
147 * @return True if the endpoint has some buffered input data
148 */
149 public boolean isBufferingInput();
150
151 /* ------------------------------------------------------------ */
152 /**
153 * @return True if the endpoint has some buffered output data
154 */
155 public boolean isBufferingOutput();
156
157 /* ------------------------------------------------------------ */
158 /** Flush any buffered output.
159 * May fail to write all data if endpoint is non-blocking
160 * @throws IOException
161 */
162 public void flush() throws IOException;
163
164
165 /* ------------------------------------------------------------ */
166 /** Get the max idle time in ms.
167 * <p>The max idle time is the time the endpoint can be idle before
168 * extraordinary handling takes place. This loosely corresponds to
169 * the {@link java.net.Socket#getSoTimeout()} for blocking connections,
170 * but {@link AsyncEndPoint} implementations must use other mechanisms
171 * to implement the max idle time.
172 * @return the max idle time in ms or if ms <= 0 implies an infinite timeout
173 */
174 public int getMaxIdleTime();
175
176 /* ------------------------------------------------------------ */
177 /** Set the max idle time.
178 * @param timeMs the max idle time in MS. Timeout <= 0 implies an infinite timeout
179 * @throws IOException if the timeout cannot be set.
180 */
181 public void setMaxIdleTime(int timeMs) throws IOException;
182
183
184
185 }