1 /*
2 * Copyright 1996-2002 Sun Microsystems, Inc. All Rights Reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any questions.
24 */
25
26 package java.rmi.server;
27
28 import java.io;
29 import java.net;
30
31 /**
32 * An <code>RMISocketFactory</code> instance is used by the RMI runtime
33 * in order to obtain client and server sockets for RMI calls. An
34 * application may use the <code>setSocketFactory</code> method to
35 * request that the RMI runtime use its socket factory instance
36 * instead of the default implementation.<p>
37 *
38 * The default socket factory implementation used goes through a
39 * three-tiered approach to creating client sockets. First, a direct
40 * socket connection to the remote VM is attempted. If that fails
41 * (due to a firewall), the runtime uses HTTP with the explicit port
42 * number of the server. If the firewall does not allow this type of
43 * communication, then HTTP to a cgi-bin script on the server is used
44 * to POST the RMI call.<p>
45 *
46 * @author Ann Wollrath
47 * @author Peter Jones
48 * @since JDK1.1
49 */
50 public abstract class RMISocketFactory
51 implements RMIClientSocketFactory, RMIServerSocketFactory
52 {
53
54 /** Client/server socket factory to be used by RMI runtime */
55 private static RMISocketFactory factory = null;
56 /** default socket factory used by this RMI implementation */
57 private static RMISocketFactory defaultSocketFactory;
58 /** Handler for socket creation failure */
59 private static RMIFailureHandler handler = null;
60
61 /**
62 * Constructs an <code>RMISocketFactory</code>.
63 * @since JDK1.1
64 */
65 public RMISocketFactory() {
66 super();
67 }
68
69 /**
70 * Creates a client socket connected to the specified host and port.
71 * @param host the host name
72 * @param port the port number
73 * @return a socket connected to the specified host and port.
74 * @exception IOException if an I/O error occurs during socket creation
75 * @since JDK1.1
76 */
77 public abstract Socket createSocket(String host, int port)
78 throws IOException;
79
80 /**
81 * Create a server socket on the specified port (port 0 indicates
82 * an anonymous port).
83 * @param port the port number
84 * @return the server socket on the specified port
85 * @exception IOException if an I/O error occurs during server socket
86 * creation
87 * @since JDK1.1
88 */
89 public abstract ServerSocket createServerSocket(int port)
90 throws IOException;
91
92 /**
93 * Set the global socket factory from which RMI gets sockets (if the
94 * remote object is not associated with a specific client and/or server
95 * socket factory). The RMI socket factory can only be set once. Note: The
96 * RMISocketFactory may only be set if the current security manager allows
97 * setting a socket factory; if disallowed, a SecurityException will be
98 * thrown.
99 * @param fac the socket factory
100 * @exception IOException if the RMI socket factory is already set
101 * @exception SecurityException if a security manager exists and its
102 * <code>checkSetFactory</code> method doesn't allow the operation.
103 * @see #getSocketFactory
104 * @see java.lang.SecurityManager#checkSetFactory()
105 * @since JDK1.1
106 */
107 public synchronized static void setSocketFactory(RMISocketFactory fac)
108 throws IOException
109 {
110 if (factory != null) {
111 throw new SocketException("factory already defined");
112 }
113 SecurityManager security = System.getSecurityManager();
114 if (security != null) {
115 security.checkSetFactory();
116 }
117 factory = fac;
118 }
119
120 /**
121 * Returns the socket factory set by the <code>setSocketFactory</code>
122 * method. Returns <code>null</code> if no socket factory has been
123 * set.
124 * @return the socket factory
125 * @see #setSocketFactory(RMISocketFactory)
126 * @since JDK1.1
127 */
128 public synchronized static RMISocketFactory getSocketFactory()
129 {
130 return factory;
131 }
132
133 /**
134 * Returns a reference to the default socket factory used
135 * by this RMI implementation. This will be the factory used
136 * by the RMI runtime when <code>getSocketFactory</code>
137 * returns <code>null</code>.
138 * @return the default RMI socket factory
139 * @since JDK1.1
140 */
141 public synchronized static RMISocketFactory getDefaultSocketFactory() {
142 if (defaultSocketFactory == null) {
143 defaultSocketFactory =
144 new sun.rmi.transport.proxy.RMIMasterSocketFactory();
145 }
146 return defaultSocketFactory;
147 }
148
149 /**
150 * Sets the failure handler to be called by the RMI runtime if server
151 * socket creation fails. By default, if no failure handler is installed
152 * and server socket creation fails, the RMI runtime does attempt to
153 * recreate the server socket.
154 *
155 * <p>If there is a security manager, this method first calls
156 * the security manager's <code>checkSetFactory</code> method
157 * to ensure the operation is allowed.
158 * This could result in a <code>SecurityException</code>.
159 *
160 * @param fh the failure handler
161 * @throws SecurityException if a security manager exists and its
162 * <code>checkSetFactory</code> method doesn't allow the
163 * operation.
164 * @see #getFailureHandler
165 * @see java.rmi.server.RMIFailureHandler#failure(Exception)
166 * @since JDK1.1
167 */
168 public synchronized static void setFailureHandler(RMIFailureHandler fh)
169 {
170 SecurityManager security = System.getSecurityManager();
171 if (security != null) {
172 security.checkSetFactory();
173 }
174 handler = fh;
175 }
176
177 /**
178 * Returns the handler for socket creation failure set by the
179 * <code>setFailureHandler</code> method.
180 * @return the failure handler
181 * @see #setFailureHandler(RMIFailureHandler)
182 * @since JDK1.1
183 */
184 public synchronized static RMIFailureHandler getFailureHandler()
185 {
186 return handler;
187 }
188 }
Save This Page