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    }
52
53    /**
54     * Creates a new socket which is not connected to any remote host. This
55     * method has to be overridden by a subclass otherwise a {@code
56     * SocketException} is thrown.
57     *
58     * @return the created unconnected socket.
59     * @throws IOException
60     *             if an error occurs while creating a new socket.
61     */
62    public Socket createSocket() throws IOException {
63        // follow RI's behavior
64        throw new SocketException("Unconnected sockets not implemented");
65    }
66
67    /**
68     * Creates a new socket which is connected to the remote host specified by
69     * the parameters {@code host} and {@code port}. The socket is bound to any
70     * available local address and port.
71     *
72     * @param host
73     *            the remote host address the socket has to be connected to.
74     * @param port
75     *            the port number of the remote host at which the socket is
76     *            connected.
77     * @return the created connected socket.
78     * @throws IOException
79     *             if an error occurs while creating a new socket.
80     * @throws UnknownHostException
81     *             if the specified host is unknown or the IP address could not
82     *             be resolved.
83     */
84    public abstract Socket createSocket(String host, int port) throws IOException,
85            UnknownHostException;
86
87    /**
88     * Creates a new socket which is connected to the remote host specified by
89     * the parameters {@code host} and {@code port}. The socket is bound to the
90     * local network interface specified by the InetAddress {@code localHost} on
91     * port {@code localPort}.
92     *
93     * @param host
94     *            the remote host address the socket has to be connected to.
95     * @param port
96     *            the port number of the remote host at which the socket is
97     *            connected.
98     * @param localHost
99     *            the local host address the socket is bound to.
100     * @param localPort
101     *            the port number of the local host at which the socket is
102     *            bound.
103     * @return the created connected socket.
104     * @throws IOException
105     *             if an error occurs while creating a new socket.
106     * @throws UnknownHostException
107     *             if the specified host is unknown or the IP address could not
108     *             be resolved.
109     */
110    public abstract Socket createSocket(String host, int port, InetAddress localHost, int localPort)
111            throws IOException, UnknownHostException;
112
113    /**
114     * Creates a new socket which is connected to the remote host specified by
115     * the InetAddress {@code host}. The socket is bound to any available local
116     * address and port.
117     *
118     * @param host
119     *            the host address the socket has to be connected to.
120     * @param port
121     *            the port number of the remote host at which the socket is
122     *            connected.
123     * @return the created connected socket.
124     * @throws IOException
125     *             if an error occurs while creating a new socket.
126     */
127    public abstract Socket createSocket(InetAddress host, int port) throws IOException;
128
129
130    /**
131     * Creates a new socket which is connected to the remote host specified by
132     * the InetAddress {@code address}. The socket is bound to the local network
133     * interface specified by the InetAddress {@code localHost} on port {@code
134     * localPort}.
135     *
136     * @param address
137     *            the remote host address the socket has to be connected to.
138     * @param port
139     *            the port number of the remote host at which the socket is
140     *            connected.
141     * @param localAddress
142     *            the local host address the socket is bound to.
143     * @param localPort
144     *            the port number of the local host at which the socket is
145     *            bound.
146     * @return the created connected socket.
147     * @throws IOException
148     *             if an error occurs while creating a new socket.
149     */
150    public abstract Socket createSocket(InetAddress address, int port, InetAddress localAddress,
151            int localPort) throws IOException;
152}
153