View Javadoc

1   //========================================================================
2   //$Id: EndPoint.java,v 1.1 2005/10/05 14:09:25 janb Exp $
3   //Copyright 2004-2005 Mort Bay Consulting Pty. Ltd.
4   //------------------------------------------------------------------------
5   //Licensed under the Apache License, Version 2.0 (the "License");
6   //you may not use this file except in compliance with the License.
7   //You may obtain a copy of the License at 
8   //http://www.apache.org/licenses/LICENSE-2.0
9   //Unless required by applicable law or agreed to in writing, software
10  //distributed under the License is distributed on an "AS IS" BASIS,
11  //WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12  //See the License for the specific language governing permissions and
13  //limitations under the License.
14  //========================================================================
15  
16  package org.mortbay.io;
17  
18  import java.io.IOException;
19  
20  
21  
22  /**
23   * @author gregw
24   * A transport EndPoint
25   */
26  public interface EndPoint
27  {
28      
29      /**
30       * Close any backing stream associated with the buffer
31       */
32      void close() throws IOException;
33  
34      /**
35       * Fill the buffer from the current putIndex to it's capacity from whatever 
36       * byte source is backing the buffer. The putIndex is increased if bytes filled.
37       * The buffer may chose to do a compact before filling.
38       * @return an <code>int</code> value indicating the number of bytes 
39       * filled or -1 if EOF is reached.
40       */
41      int fill(Buffer buffer) throws IOException;
42      
43  
44      /**
45       * Flush the buffer from the current getIndex to it's putIndex using whatever byte
46       * sink is backing the buffer. The getIndex is updated with the number of bytes flushed.
47       * Any mark set is cleared.
48       * If the entire contents of the buffer are flushed, then an implicit empty() is done.
49       * 
50       * @param buffer The buffer to flush. This buffers getIndex is updated.
51       * @return  the number of bytes written
52       */
53      int flush(Buffer buffer) throws IOException;
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       * The passed header/trailer buffers are written before/after the contents of this buffer. This may be done 
61       * either as gather writes, as a poke into this buffer or as several writes. The implementation is free to
62       * select the optimal mechanism.
63       * @param header A buffer to write before flushing this buffer. This buffers getIndex is updated.
64       * @param buffer The buffer to flush. This buffers getIndex is updated.
65       * @param trailer A buffer to write after flushing this buffer. This buffers getIndex is updated.
66       * @return the total number of bytes written.
67       */
68      int flush(Buffer header, Buffer buffer, Buffer trailer) throws IOException;
69  
70      
71      /* ------------------------------------------------------------ */
72      /**
73       * @return The local IP address to which this <code>EndPoint</code> is bound, or <code>null</code>
74       * if this <code>EndPoint</code> does not represent a network connection.
75       */
76      public String getLocalAddr();
77      
78      /* ------------------------------------------------------------ */
79      /**
80       * @return The local host name to which this <code>EndPoint</code> is bound, or <code>null</code>
81       * if this <code>EndPoint</code> does not represent a network connection.
82       */
83      public String getLocalHost();
84  
85      /* ------------------------------------------------------------ */
86      /**
87       * @return The local port number on which this <code>EndPoint</code> is listening, or <code>0</code>
88       * if this <code>EndPoint</code> does not represent a network connection.
89       */
90      public int getLocalPort();
91  
92      /* ------------------------------------------------------------ */
93      /**
94       * @return The remote IP address to which this <code>EndPoint</code> is connected, or <code>null</code>
95       * if this <code>EndPoint</code> does not represent a network connection.
96       */
97      public String getRemoteAddr();
98  
99      /* ------------------------------------------------------------ */
100     /**
101      * @return The host name of the remote machine to which this <code>EndPoint</code> is connected, or <code>null</code>
102      * if this <code>EndPoint</code> does not represent a network connection.
103      */
104     public String getRemoteHost();
105 
106     /* ------------------------------------------------------------ */
107     /**
108      * @return The remote port number to which this <code>EndPoint</code> is connected, or <code>0</code>
109      * if this <code>EndPoint</code> does not represent a network connection.
110      */
111     public int getRemotePort();
112 
113 
114     /* ------------------------------------------------------------ */
115     public boolean isBlocking();
116     
117     /* ------------------------------------------------------------ */
118     public boolean isBufferred();
119     
120     /* ------------------------------------------------------------ */
121     public boolean blockReadable(long millisecs) throws IOException;
122 
123     /* ------------------------------------------------------------ */
124     public boolean blockWritable(long millisecs) throws IOException;
125 
126     /* ------------------------------------------------------------ */
127     public boolean isOpen();
128 
129     /* ------------------------------------------------------------ */
130     /**
131      * @return The underlying transport object (socket, channel, etc.)
132      */
133     public Object getTransport();
134     
135     /* ------------------------------------------------------------ */
136     /**
137      * @return True if the endpoint has some buffered input data
138      */
139     public boolean isBufferingInput();
140     
141     /* ------------------------------------------------------------ */
142     /**
143      * @return True if the endpoint has some buffered output data
144      */
145     public boolean isBufferingOutput();
146     
147     /* ------------------------------------------------------------ */
148     /** Flush any buffered output.
149      * May fail to write all data if endpoint is non-blocking
150      * @throws IOException 
151      */
152     public void flush() throws IOException;
153     
154 }