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