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 }