SocketFactory.java revision 6b811c5daec1b28e6f63b57f98a032236f2c3cf7 
1/*
2 *  Licensed to the Apache Software Foundation (ASF) under one or more
3 *  contributor license agreements.  See the NOTICE file distributed with
4 *  this work for additional information regarding copyright ownership.
5 *  The ASF licenses this file to You under the Apache License, Version 2.0
6 *  (the "License"); you may not use this file except in compliance with
7 *  the License.  You may obtain a copy of the License at
8 *
9 *     http://www.apache.org/licenses/LICENSE-2.0
10 *
11 *  Unless required by applicable law or agreed to in writing, software
12 *  distributed under the License is distributed on an "AS IS" BASIS,
13 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 *  See the License for the specific language governing permissions and
15 *  limitations under the License.
16 */
17
18package javax.net;
19
20import java.io.IOException;
21import java.net.InetAddress;
22import java.net.Socket;
23import java.net.SocketException;
24import java.net.UnknownHostException;
25
26/**
27 * This abstract class defines methods to create sockets. It can be subclassed
28 * to create specific socket types with additional socket-level functionality.
29 */
30public abstract class SocketFactory {
31
32    private static SocketFactory defaultFactory;
33
34    /**
35     * Gets the default socket factory of the system which can be used to create
36     * new sockets without creating a subclass of this factory.
37     *
38     * @return the system default socket factory.
39     */
40    public static synchronized SocketFactory getDefault() {
41        if (defaultFactory == null) {
42            defaultFactory = new DefaultSocketFactory();
43        }
44        return defaultFactory;
45    }
46
47    /**
48     * Creates a new {@code SocketFactory} instance.
49     */
50    protected SocketFactory() {
51        super();
52    }
53
54    /**
55     * Creates a new socket which is not connected to any remote host. This
56     * method has to be overridden by a subclass otherwise a {@code
57     * SocketException} is thrown.
58     *
59     * @return the created unconnected socket.
60     * @throws IOException
61     *             if an error occurs while creating a new socket.
62     */
63    public Socket createSocket() throws IOException {
64        // follow RI's behavior
65        throw new SocketException("Unconnected sockets not implemented");
66    }
67
68    /**
69     * Creates a new socket which is connected to the remote host specified by
70     * the parameters {@code host} and {@code port}. The socket is bound to any
71     * available local address and port.
72     *
73     * @param host
74     *            the remote host address the socket has to be connected to.
75     * @param port
76     *            the port number of the remote host at which the socket is
77     *            connected.
78     * @return the created connected socket.
79     * @throws IOException
80     *             if an error occurs while creating a new socket.
81     * @throws UnknownHostException
82     *             if the specified host is unknown or the IP address could not
83     *             be resolved.
84     */
85    public abstract Socket createSocket(String host, int port) throws IOException,
86            UnknownHostException;
87
88    /**
89     * Creates a new socket which is connected to the remote host specified by
90     * the parameters {@code host} and {@code port}. The socket is bound to the
91     * local network interface specified by the InetAddress {@code localHost} on
92     * port {@code localPort}.
93     *
94     * @param host
95     *            the remote host address the socket has to be connected to.
96     * @param port
97     *            the port number of the remote host at which the socket is
98     *            connected.
99     * @param localHost
100     *            the local host address the socket is bound to.
101     * @param localPort
102     *            the port number of the local host at which the socket is
103     *            bound.
104     * @return the created connected socket.
105     * @throws IOException
106     *             if an error occurs while creating a new socket.
107     * @throws UnknownHostException
108     *             if the specified host is unknown or the IP address could not
109     *             be resolved.
110     */
111    public abstract Socket createSocket(String host, int port, InetAddress localHost, int localPort)
112            throws IOException, UnknownHostException;
113
114    /**
115     * Creates a new socket which is connected to the remote host specified by
116     * the InetAddress {@code host}. The socket is bound to any available local
117     * address and port.
118     *
119     * @param host
120     *            the host address the socket has to be connected to.
121     * @param port
122     *            the port number of the remote host at which the socket is
123     *            connected.
124     * @return the created connected socket.
125     * @throws IOException
126     *             if an error occurs while creating a new socket.
127     */
128    public abstract Socket createSocket(InetAddress host, int port) throws IOException;
129
130
131    /**
132     * Creates a new socket which is connected to the remote host specified by
133     * the InetAddress {@code address}. The socket is bound to the local network
134     * interface specified by the InetAddress {@code localHost} on port {@code
135     * localPort}.
136     *
137     * @param address
138     *            the remote host address the socket has to be connected to.
139     * @param port
140     *            the port number of the remote host at which the socket is
141     *            connected.
142     * @param localAddress
143     *            the local host address the socket is bound to.
144     * @param localPort
145     *            the port number of the local host at which the socket is
146     *            bound.
147     * @return the created connected socket.
148     * @throws IOException
149     *             if an error occurs while creating a new socket.
150     */
151    public abstract Socket createSocket(InetAddress address, int port, InetAddress localAddress,
152            int localPort) throws IOException;
153}
154