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 }