View Javadoc

1   /*
2    * Copyright 2001-2005 The Apache Software Foundation
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  package org.apache.commons.net;
17  
18  import java.io.IOException;
19  import java.net.InetAddress;
20  import java.net.ServerSocket;
21  import java.net.Socket;
22  import java.net.UnknownHostException;
23  
24  /***
25   * The SocketFactory interface provides a means for the programmer to
26   * control the creation of sockets and provide his own Socket
27   * implementations for use by all classes derived from
28   * {@link org.apache.commons.net.SocketClient}.
29   * This allows you to provide your own Socket implementations and
30   * to perform security checks or browser capability requests before
31   * creating a Socket.
32   * <p>
33   * <p>
34   * @author Daniel F. Savarese
35   * @see DefaultSocketFactory
36   ***/
37  
38  public interface SocketFactory
39  {
40  
41      /***
42       * Creates a Socket connected to the given host and port.
43       * <p>
44       * @param host The hostname to connect to.
45       * @param port The port to connect to.
46       * @return A Socket connected to the given host and port.
47       * @exception UnknownHostException  If the hostname cannot be resolved.
48       * @exception IOException If an I/O error occurs while creating the Socket.
49       ***/
50      public Socket createSocket(String host, int port)
51      throws UnknownHostException, IOException;
52  
53  
54      /***
55       * Creates a Socket connected to the given host and port.
56       * <p>
57       * @param address The address of the host to connect to.
58       * @param port The port to connect to.
59       * @return A Socket connected to the given host and port.
60       * @exception IOException If an I/O error occurs while creating the Socket.
61       ***/
62      public Socket createSocket(InetAddress address, int port)
63      throws IOException;
64  
65  
66      /***
67       * Creates a Socket connected to the given host and port and
68       * originating from the specified local address and port.
69       * <p>
70       * @param host The hostname to connect to.
71       * @param port The port to connect to.
72       * @param localAddr  The local address to use.
73       * @param localPort  The local port to use.
74       * @return A Socket connected to the given host and port.
75       * @exception UnknownHostException  If the hostname cannot be resolved.
76       * @exception IOException If an I/O error occurs while creating the Socket.
77       ***/
78      public Socket createSocket(String host, int port, InetAddress localAddr,
79                                 int localPort)
80      throws UnknownHostException, IOException;
81  
82      /***
83       * Creates a Socket connected to the given host and port and
84       * originating from the specified local address and port.
85       * <p>
86       * @param address The address of the host to connect to.
87       * @param port The port to connect to.
88       * @param localAddr  The local address to use.
89       * @param localPort  The local port to use.
90       * @return A Socket connected to the given host and port.
91       * @exception IOException If an I/O error occurs while creating the Socket.
92       ***/
93      public Socket createSocket(InetAddress address, int port,
94                                 InetAddress localAddr, int localPort)
95      throws IOException;
96  
97      /***
98       * Creates a ServerSocket bound to a specified port.  A port
99       * of 0 will create the ServerSocket on a system-determined free port.
100      * <p>
101      * @param port  The port on which to listen, or 0 to use any free port.
102      * @return A ServerSocket that will listen on a specified port.
103      * @exception IOException If an I/O error occurs while creating
104      *                        the ServerSocket.
105      ***/
106     public ServerSocket createServerSocket(int port) throws IOException;
107 
108     /***
109      * Creates a ServerSocket bound to a specified port with a given
110      * maximum queue length for incoming connections.  A port of 0 will
111      * create the ServerSocket on a system-determined free port.
112      * <p>
113      * @param port  The port on which to listen, or 0 to use any free port.
114      * @param backlog  The maximum length of the queue for incoming connections.
115      * @return A ServerSocket that will listen on a specified port.
116      * @exception IOException If an I/O error occurs while creating
117      *                        the ServerSocket.
118      ***/
119     public ServerSocket createServerSocket(int port, int backlog)
120     throws IOException;
121 
122     /***
123      * Creates a ServerSocket bound to a specified port on a given local
124      * address with a given maximum queue length for incoming connections.
125      * A port of 0 will
126      * create the ServerSocket on a system-determined free port.
127      * <p>
128      * @param port  The port on which to listen, or 0 to use any free port.
129      * @param backlog  The maximum length of the queue for incoming connections.
130      * @param bindAddr  The local address to which the ServerSocket should bind.
131      * @return A ServerSocket that will listen on a specified port.
132      * @exception IOException If an I/O error occurs while creating
133      *                        the ServerSocket.
134      ***/
135     public ServerSocket createServerSocket(int port, int backlog,
136                                            InetAddress bindAddr)
137     throws IOException;
138 }