001 /*
002 * Copyright 1996-2002 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package java.rmi.server;
027
028 import java.io.*;
029 import java.net.*;
030
031 /**
032 * An <code>RMISocketFactory</code> instance is used by the RMI runtime
033 * in order to obtain client and server sockets for RMI calls. An
034 * application may use the <code>setSocketFactory</code> method to
035 * request that the RMI runtime use its socket factory instance
036 * instead of the default implementation.<p>
037 *
038 * The default socket factory implementation used goes through a
039 * three-tiered approach to creating client sockets. First, a direct
040 * socket connection to the remote VM is attempted. If that fails
041 * (due to a firewall), the runtime uses HTTP with the explicit port
042 * number of the server. If the firewall does not allow this type of
043 * communication, then HTTP to a cgi-bin script on the server is used
044 * to POST the RMI call.<p>
045 *
046 * @version 1.28, 05/05/07
047 * @author Ann Wollrath
048 * @author Peter Jones
049 * @since JDK1.1
050 */
051 public abstract class RMISocketFactory implements
052 RMIClientSocketFactory, RMIServerSocketFactory {
053
054 /** Client/server socket factory to be used by RMI runtime */
055 private static RMISocketFactory factory = null;
056 /** default socket factory used by this RMI implementation */
057 private static RMISocketFactory defaultSocketFactory;
058 /** Handler for socket creation failure */
059 private static RMIFailureHandler handler = null;
060
061 /**
062 * Constructs an <code>RMISocketFactory</code>.
063 * @since JDK1.1
064 */
065 public RMISocketFactory() {
066 super ();
067 }
068
069 /**
070 * Creates a client socket connected to the specified host and port.
071 * @param host the host name
072 * @param port the port number
073 * @return a socket connected to the specified host and port.
074 * @exception IOException if an I/O error occurs during socket creation
075 * @since JDK1.1
076 */
077 public abstract Socket createSocket(String host, int port)
078 throws IOException;
079
080 /**
081 * Create a server socket on the specified port (port 0 indicates
082 * an anonymous port).
083 * @param port the port number
084 * @return the server socket on the specified port
085 * @exception IOException if an I/O error occurs during server socket
086 * creation
087 * @since JDK1.1
088 */
089 public abstract ServerSocket createServerSocket(int port)
090 throws IOException;
091
092 /**
093 * Set the global socket factory from which RMI gets sockets (if the
094 * remote object is not associated with a specific client and/or server
095 * socket factory). The RMI socket factory can only be set once. Note: The
096 * RMISocketFactory may only be set if the current security manager allows
097 * setting a socket factory; if disallowed, a SecurityException will be
098 * thrown.
099 * @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(
108 RMISocketFactory fac) throws IOException {
109 if (factory != null) {
110 throw new SocketException("factory already defined");
111 }
112 SecurityManager security = System.getSecurityManager();
113 if (security != null) {
114 security.checkSetFactory();
115 }
116 factory = fac;
117 }
118
119 /**
120 * Returns the socket factory set by the <code>setSocketFactory</code>
121 * method. Returns <code>null</code> if no socket factory has been
122 * set.
123 * @return the socket factory
124 * @see #setSocketFactory(RMISocketFactory)
125 * @since JDK1.1
126 */
127 public synchronized static RMISocketFactory getSocketFactory() {
128 return factory;
129 }
130
131 /**
132 * Returns a reference to the default socket factory used
133 * by this RMI implementation. This will be the factory used
134 * by the RMI runtime when <code>getSocketFactory</code>
135 * returns <code>null</code>.
136 * @return the default RMI socket factory
137 * @since JDK1.1
138 */
139 public synchronized static RMISocketFactory getDefaultSocketFactory() {
140 if (defaultSocketFactory == null) {
141 defaultSocketFactory = new sun.rmi.transport.proxy.RMIMasterSocketFactory();
142 }
143 return defaultSocketFactory;
144 }
145
146 /**
147 * Sets the failure handler to be called by the RMI runtime if server
148 * socket creation fails. By default, if no failure handler is installed
149 * and server socket creation fails, the RMI runtime does attempt to
150 * recreate the server socket.
151 *
152 * <p>If there is a security manager, this method first calls
153 * the security manager's <code>checkSetFactory</code> method
154 * to ensure the operation is allowed.
155 * This could result in a <code>SecurityException</code>.
156 *
157 * @param fh the failure handler
158 * @throws SecurityException if a security manager exists and its
159 * <code>checkSetFactory</code> method doesn't allow the
160 * operation.
161 * @see #getFailureHandler
162 * @see java.rmi.server.RMIFailureHandler#failure(Exception)
163 * @since JDK1.1
164 */
165 public synchronized static void setFailureHandler(
166 RMIFailureHandler fh) {
167 SecurityManager security = System.getSecurityManager();
168 if (security != null) {
169 security.checkSetFactory();
170 }
171 handler = fh;
172 }
173
174 /**
175 * Returns the handler for socket creation failure set by the
176 * <code>setFailureHandler</code> method.
177 * @return the failure handler
178 * @see #setFailureHandler(RMIFailureHandler)
179 * @since JDK1.1
180 */
181 public synchronized static RMIFailureHandler getFailureHandler() {
182 return handler;
183 }
184 }
|