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