/*
* Copyright (c) 1996, 2013, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package java.rmi.server;
import java.io.*;
import java.net.*;
/**
* An <code>RMISocketFactory</code> instance is used by the RMI runtime
* in order to obtain client and server sockets for RMI calls. An
* application may use the <code>setSocketFactory</code> method to
* request that the RMI runtime use its socket factory instance
* instead of the default implementation.
*
* <p>The default socket factory implementation performs a
* three-tiered approach to creating client sockets. First, a direct
* socket connection to the remote VM is attempted. If that fails
* (due to a firewall), the runtime uses HTTP with the explicit port
* number of the server. If the firewall does not allow this type of
* communication, then HTTP to a cgi-bin script on the server is used
* to POST the RMI call.
*
* <p>The default socket factory implementation creates server sockets that
* are bound to the wildcard address, which accepts requests from all network
* interfaces.
*
* @implNote
* <p>You can use the {@code RMISocketFactory} class to create a server socket that
* is bound to a specific address, restricting the origin of requests. For example,
* the following code implements a socket factory that binds server sockets to an IPv4
* loopback address. This restricts RMI to processing requests only from the local host.
*
* <pre>{@code
* class LoopbackSocketFactory extends RMISocketFactory {
* public ServerSocket createServerSocket(int port) throws IOException {
* return new ServerSocket(port, 5, InetAddress.getByName("127.0.0.1"));
* }
*
* public Socket createSocket(String host, int port) throws IOException {
* // just call the default client socket factory
* return RMISocketFactory.getDefaultSocketFactory()
* .createSocket(host, port);
* }
* }
*
* // ...
*
* RMISocketFactory.setSocketFactory(new LoopbackSocketFactory());
* }</pre>
*
* Set the {@code java.rmi.server.hostname} system property
* to {@code 127.0.0.1} to ensure that the generated stubs connect to the right
* network interface.
*
* @author Ann Wollrath
* @author Peter Jones
* @since JDK1.1
*/
public abstract class RMISocketFactory
implements RMIClientSocketFactory, RMIServerSocketFactory
{
/** Client/server socket factory to be used by RMI runtime */
private static RMISocketFactory factory = null;
/** default socket factory used by this RMI implementation */
private static RMISocketFactory defaultSocketFactory;
/** Handler for socket creation failure */
private static RMIFailureHandler handler = null;
/**
* Constructs an <code>RMISocketFactory</code>.
* @since JDK1.1
*/
public RMISocketFactory() {
super();
}
/**
* Creates a client socket connected to the specified host and port.
* @param host the host name
* @param port the port number
* @return a socket connected to the specified host and port.
* @exception IOException if an I/O error occurs during socket creation
* @since JDK1.1
*/
public abstract Socket createSocket(String host, int port)
throws IOException;
/**
* Create a server socket on the specified port (port 0 indicates
* an anonymous port).
* @param port the port number
* @return the server socket on the specified port
* @exception IOException if an I/O error occurs during server socket
* creation
* @since JDK1.1
*/
public abstract ServerSocket createServerSocket(int port)
throws IOException;
/**
* Set the global socket factory from which RMI gets sockets (if the
* remote object is not associated with a specific client and/or server
* socket factory). The RMI socket factory can only be set once. Note: The
* RMISocketFactory may only be set if the current security manager allows
* setting a socket factory; if disallowed, a SecurityException will be
* thrown.
* @param fac the socket factory
* @exception IOException if the RMI socket factory is already set
* @exception SecurityException if a security manager exists and its
* <code>checkSetFactory</code> method doesn't allow the operation.
* @see #getSocketFactory
* @see java.lang.SecurityManager#checkSetFactory()
* @since JDK1.1
*/
public synchronized static void setSocketFactory(RMISocketFactory fac)
throws IOException
{
if (factory != null) {
throw new SocketException("factory already defined");
}
SecurityManager security = System.getSecurityManager();
if (security != null) {
security.checkSetFactory();
}
factory = fac;
}
/**
* Returns the socket factory set by the <code>setSocketFactory</code>
* method. Returns <code>null</code> if no socket factory has been
* set.
* @return the socket factory
* @see #setSocketFactory(RMISocketFactory)
* @since JDK1.1
*/
public synchronized static RMISocketFactory getSocketFactory()
{
return factory;
}
/**
* Returns a reference to the default socket factory used
* by this RMI implementation. This will be the factory used
* by the RMI runtime when <code>getSocketFactory</code>
* returns <code>null</code>.
* @return the default RMI socket factory
* @since JDK1.1
*/
public synchronized static RMISocketFactory getDefaultSocketFactory() {
if (defaultSocketFactory == null) {
defaultSocketFactory =
new sun.rmi.transport.proxy.RMIMasterSocketFactory();
}
return defaultSocketFactory;
}
/**
* Sets the failure handler to be called by the RMI runtime if server
* socket creation fails. By default, if no failure handler is installed
* and server socket creation fails, the RMI runtime does attempt to
* recreate the server socket.
*
* <p>If there is a security manager, this method first calls
* the security manager's <code>checkSetFactory</code> method
* to ensure the operation is allowed.
* This could result in a <code>SecurityException</code>.
*
* @param fh the failure handler
* @throws SecurityException if a security manager exists and its
* <code>checkSetFactory</code> method doesn't allow the
* operation.
* @see #getFailureHandler
* @see java.rmi.server.RMIFailureHandler#failure(Exception)
* @since JDK1.1
*/
public synchronized static void setFailureHandler(RMIFailureHandler fh)
{
SecurityManager security = System.getSecurityManager();
if (security != null) {
security.checkSetFactory();
}
handler = fh;
}
/**
* Returns the handler for socket creation failure set by the
* <code>setFailureHandler</code> method.
* @return the failure handler
* @see #setFailureHandler(RMIFailureHandler)
* @since JDK1.1
*/
public synchronized static RMIFailureHandler getFailureHandler()
{
return handler;
}
}