View Javadoc

1   /*
2    * Copyright  2004-2005 Stefan Reuter
3    *
4    *  Licensed under the Apache License, Version 2.0 (the "License");
5    *  you may not use this file except in compliance with the License.
6    *  You may obtain a copy of the License at
7    *
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    *
10   *  Unless required by applicable law or agreed to in writing, software
11   *  distributed under the License is distributed on an "AS IS" BASIS,
12   *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   *  See the License for the specific language governing permissions and
14   *  limitations under the License.
15   *
16   */
17  package net.sf.asterisk.io;
18  
19  import java.io.IOException;
20  import java.net.InetAddress;
21  
22  /***
23   * The SocketConnectionFacade provides read and write operation for
24   * communication over TCP/IP sockets.<br>
25   * It hides the details of the underlying I/O system used for socket
26   * communication.
27   * 
28   * @author srt
29   * @version $Id: SocketConnectionFacade.java,v 1.3 2005/09/27 21:07:26 srt Exp $
30   */
31  public interface SocketConnectionFacade
32  {
33      /***
34       * Reads a line of text from the socket connection. The current thread is
35       * blocked until either the next line is received or an IOException
36       * encounters.
37       * 
38       * @return the line of text received excluding any newline character
39       * @throws IOException if the connection has been closed.
40       */
41      String readLine() throws IOException;
42  
43      /***
44       * Sends a given String to the socket connection.
45       * 
46       * @param s the String to send.
47       * @throws IOException if the String cannot be sent, maybe because the
48       *             connection has already been closed.
49       */
50      void write(String s) throws IOException;
51  
52      /***
53       * Flushes the socket connection, that is sends any buffered but yet unsent
54       * data.
55       * 
56       * @throws IOException if the connection cannot be flushed.
57       */
58      void flush() throws IOException;
59  
60      /***
61       * Closes the socket connection including its input and output stream and
62       * frees all associated ressources.<br>
63       * When calling close() any Thread currently blocked by a call to readLine()
64       * will be unblocked and receive an IOException.
65       * 
66       * @throws IOException if the socket connection cannot be closed.
67       */
68      void close() throws IOException;
69  
70      /***
71       * Returns the connection state of the socket.
72       * 
73       * @return <code>true</code> if the socket successfuly connected to a
74       *         server
75       */
76      boolean isConnected();
77  
78      /***
79       * Returns the local address this socket connection.
80       * 
81       * @return the local address this socket connection.
82       * @since 0.2
83       */
84      InetAddress getLocalAddress();
85  
86      /***
87       * Returns the local port of this socket connection.
88       * 
89       * @return the local port of this socket connection.
90       * @since 0.2
91       */
92      int getLocalPort();
93  
94      /***
95       * Returns the remote address of this socket connection.
96       * 
97       * @return the remote address of this socket connection.
98       * @since 0.2
99       */
100     InetAddress getRemoteAddress();
101 
102     /***
103      * Returns the remote port of this socket connection.
104      * 
105      * @return the remote port of this socket connection.
106      * @since 0.2
107      */
108     int getRemotePort();
109 }