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