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