/*

 * Copyright (c) 1996, 2017, 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.ObjectInputFilter;

import java.rmi.*;

import sun.rmi.server.UnicastServerRef;

import sun.rmi.server.UnicastServerRef2;

import sun.rmi.transport.LiveRef;

/**

 * Used for exporting a remote object with JRMP and obtaining a stub

 * that communicates to the remote object. Stubs are either generated

 * at runtime using dynamic proxy objects, or they are generated statically

 * at build time, typically using the {@code rmic} tool.

 *

 * <p><strong>Deprecated: Static Stubs.</strong> <em>Support for statically

 * generated stubs is deprecated. This includes the API in this class that

 * requires the use of static stubs, as well as the runtime support for

 * loading static stubs.  Generating stubs dynamically is preferred, using one

 * of the non-deprecated ways of exporting objects as listed below. Do

 * not run {@code rmic} to generate static stub classes. It is unnecessary, and

 * it is also deprecated.</em>

 *

 * <p>There are eight ways to export remote objects:

 *

 * <ol>

 *

 * <li>Subclassing {@code UnicastRemoteObject} and calling the

 * {@link #UnicastRemoteObject()} constructor.

 *

 * <li>Subclassing {@code UnicastRemoteObject} and calling the

 * {@link #UnicastRemoteObject(int) UnicastRemoteObject(port)} constructor.

 *

 * <li>Subclassing {@code UnicastRemoteObject} and calling the

 * {@link #UnicastRemoteObject(int, RMIClientSocketFactory, RMIServerSocketFactory)

 * UnicastRemoteObject(port, csf, ssf)} constructor.

 *

 * <li>Calling the

 * {@link #exportObject(Remote) exportObject(Remote)} method.

 * <strong>Deprecated.</strong>

 *

 * <li>Calling the

 * {@link #exportObject(Remote, int) exportObject(Remote, port)} method.

 *

 * <li>Calling the

 * {@link #exportObject(Remote, int, RMIClientSocketFactory, RMIServerSocketFactory)

 * exportObject(Remote, port, csf, ssf)} method.

 *

 * <li>Calling the

 * {@link #exportObject(Remote, int, ObjectInputFilter) exportObject(Remote, port, filter)} method.

 *

 * <li>Calling the

 * {@link #exportObject(Remote, int, RMIClientSocketFactory, RMIServerSocketFactory, ObjectInputFilter)

 * exportObject(Remote, port, csf, ssf, filter)} method.

 *

 * </ol>

 *

 * <p>The fourth technique, {@link #exportObject(Remote)},

 * always uses statically generated stubs and is deprecated.

 *

 * <p>The other techniques all use the following approach: if the

 * {@code java.rmi.server.ignoreStubClasses} property is {@code true}

 * (case insensitive) or if a static stub cannot be found, stubs are generated

 * dynamically using {@link java.lang.reflect.Proxy Proxy} objects. Otherwise,

 * static stubs are used.

 *

 * <p>The default value of the

 * {@code java.rmi.server.ignoreStubClasses} property is {@code false}.

 *

 * <p>Statically generated stubs are typically pregenerated from the

 * remote object's class using the {@code rmic} tool. A static stub is

 * loaded and an instance of that stub class is constructed as described

 * below.

 *

 * <ul>

 *

 * <li>A "root class" is determined as follows: if the remote object's

 * class directly implements an interface that extends {@link Remote}, then

 * the remote object's class is the root class; otherwise, the root class is

 * the most derived superclass of the remote object's class that directly

 * implements an interface that extends {@code Remote}.

 *

 * <li>The name of the stub class to load is determined by concatenating

 * the binary name of the root class with the suffix {@code _Stub}.

 *

 * <li>The stub class is loaded by name using the class loader of the root

 * class. The stub class must be public, it must extend {@link RemoteStub}, it must

 * reside in a package that is exported to at least the {@code java.rmi} module, and it

 * must have a public constructor that has one parameter of type {@link RemoteRef}.

 *

 * <li>Finally, an instance of the stub class is constructed with a

 * {@link RemoteRef}.

 *

 * <li>If the appropriate stub class could not be found, or if the stub class

 * could not be loaded, or if a problem occurs creating the stub instance, a

 * {@link StubNotFoundException} is thrown.

 *

 * </ul>

 *

 * <p>Stubs are dynamically generated by constructing an instance of

 * a {@link java.lang.reflect.Proxy Proxy} with the following characteristics:

 *

 * <ul>

 *

 * <li>The proxy's class is defined according to the specifications for the

 * <a href="{@docRoot}/java.base/java/lang/reflect/Proxy.html#membership">

 * {@code Proxy}

 * </a>

 * class, using the class loader of the remote object's class.

 *

 * <li>The proxy implements all the remote interfaces implemented by the

 * remote object's class.

 *

 * <li>Each remote interface must either be public and reside in a package that is

 * {@linkplain Module#isExported(String,Module) exported}

 * to at least the {@code java.rmi} module, or it must reside in a package that is

 * {@linkplain Module#isOpen(String,Module) open}

 * to at least the {@code java.rmi} module.

 *

 * <li>The proxy's invocation handler is a {@link

 * RemoteObjectInvocationHandler} instance constructed with a

 * {@link RemoteRef}.

 *

 * <li>If the proxy could not be created, a {@link StubNotFoundException}

 * will be thrown.

 *

 * </ul>

 *

 * <p>

 * Exported remote objects receive method invocations from the stubs

 * as described in the RMI specification. Each invocation's operation and

 * parameters are unmarshaled using a custom {@link java.io.ObjectInputStream}.

 * If an {@link ObjectInputFilter} is provided and is not {@code null} when the object

 * is exported, it is used to filter the parameters as they are unmarshaled from the stream.

 * The filter is used for all invocations and all parameters regardless of

 * the method being invoked or the parameter values.

 * If no filter is provided or is {@code null} for the exported object then the

 * {@code ObjectInputStream} default filter, if any, is used. The default filter is

 * configured with {@link ObjectInputFilter.Config#setSerialFilter(ObjectInputFilter)

 * ObjectInputFilter.Config.setSerialFilter}.

 * If the filter rejects any of the parameters, the {@code InvalidClassException}

 * thrown by {@code ObjectInputStream} is reported as the cause of an

 * {@link UnmarshalException}.

 *

 * @implNote

 * Depending upon which constructor or static method is used for exporting an

 * object, {@link RMISocketFactory} may be used for creating sockets.

 * By default, server sockets created by {@link RMISocketFactory}

 * listen on all network interfaces. See the

 * {@link RMISocketFactory} class and the section

 * <a href="{@docRoot}/../specs/rmi/server.html#rmi-socket-factories">RMI Socket Factories</a>

 * in the

 * <a href="{@docRoot}/../specs/rmi/index.html">Java RMI Specification</a>.

 *

 * @author  Ann Wollrath

 * @author  Peter Jones

 * @since   1.1

 **/

public class UnicastRemoteObject extends RemoteServer {

    /**

     * @serial port number on which to export object

     */

    private int port = 0;

    /**

     * @serial client-side socket factory (if any)

     */

    private RMIClientSocketFactory csf = null;

    /**

     * @serial server-side socket factory (if any) to use when

     * exporting object

     */

    private RMIServerSocketFactory ssf = null;

    /* indicate compatibility with JDK 1.1.x version of class */

    private static final long serialVersionUID = 4974527148936298033L;

    /**

     * Creates and exports a new UnicastRemoteObject object using an

     * anonymous port.

     *

     * <p>The object is exported with a server socket

     * created using the {@link RMISocketFactory} class.

     *

     * @throws RemoteException if failed to export object

     * @since 1.1

     */

    protected UnicastRemoteObject() throws RemoteException

    {

        this(0);

    }

    /**

     * Creates and exports a new UnicastRemoteObject object using the

     * particular supplied port.

     *

     * <p>The object is exported with a server socket

     * created using the {@link RMISocketFactory} class.

     *

     * @param port the port number on which the remote object receives calls

     * (if <code>port</code> is zero, an anonymous port is chosen)

     * @throws RemoteException if failed to export object

     * @since 1.2

     */

    protected UnicastRemoteObject(int port) throws RemoteException

    {

        this.port = port;

        exportObject((Remote) this, port);

    }

    /**

     * Creates and exports a new UnicastRemoteObject object using the

     * particular supplied port and socket factories.

     *

     * <p>Either socket factory may be {@code null}, in which case

     * the corresponding client or server socket creation method of

     * {@link RMISocketFactory} is used instead.

     *

     * @param port the port number on which the remote object receives calls

     * (if <code>port</code> is zero, an anonymous port is chosen)

     * @param csf the client-side socket factory for making calls to the

     * remote object

     * @param ssf the server-side socket factory for receiving remote calls

     * @throws RemoteException if failed to export object

     * @since 1.2

     */

    protected UnicastRemoteObject(int port,

                                  RMIClientSocketFactory csf,

                                  RMIServerSocketFactory ssf)

        throws RemoteException

    {

        this.port = port;

        this.csf = csf;

        this.ssf = ssf;

        exportObject((Remote) this, port, csf, ssf);

    }

    /**

     * Re-export the remote object when it is deserialized.

     */

    private void readObject(java.io.ObjectInputStream in)

        throws java.io.IOException, java.lang.ClassNotFoundException

    {

        in.defaultReadObject();

        reexport();

    }

    /**

     * Returns a clone of the remote object that is distinct from

     * the original.

     *

     * @exception CloneNotSupportedException if clone failed due to

     * a RemoteException.

     * @return the new remote object

     * @since 1.1

     */

    public Object clone() throws CloneNotSupportedException

    {

        try {

            UnicastRemoteObject cloned = (UnicastRemoteObject) super.clone();

            cloned.reexport();

            return cloned;

        } catch (RemoteException e) {

            throw new ServerCloneException("Clone failed", e);

        }

    }

    /*

     * Exports this UnicastRemoteObject using its initialized fields because

     * its creation bypassed running its constructors (via deserialization

     * or cloning, for example).

     */

    private void reexport() throws RemoteException

    {

        if (csf == null && ssf == null) {

            exportObject((Remote) this, port);

        } else {

            exportObject((Remote) this, port, csf, ssf);

        }

    }

    /**

     * Exports the remote object to make it available to receive incoming

     * calls using an anonymous port. This method will always return a

     * statically generated stub.

     *

     * <p>The object is exported with a server socket

     * created using the {@link RMISocketFactory} class.

     *

     * @param obj the remote object to be exported

     * @return remote object stub

     * @exception RemoteException if export fails

     * @since 1.1

     * @deprecated This method is deprecated because it supports only static stubs.

     * Use {@link #exportObject(Remote, int) exportObject(Remote, port)} or

     * {@link #exportObject(Remote, int, RMIClientSocketFactory, RMIServerSocketFactory)

     * exportObject(Remote, port, csf, ssf)}

     * instead.

     */

    @Deprecated

    public static RemoteStub exportObject(Remote obj)

        throws RemoteException

    {

        /*

         * Use UnicastServerRef constructor passing the boolean value true

         * to indicate that only a generated stub class should be used.  A

         * generated stub class must be used instead of a dynamic proxy

         * because the return value of this method is RemoteStub which a

         * dynamic proxy class cannot extend.

         */

        return (RemoteStub) exportObject(obj, new UnicastServerRef(true));

    }

    /**

     * Exports the remote object to make it available to receive incoming

     * calls, using the particular supplied port.

     *

     * <p>The object is exported with a server socket

     * created using the {@link RMISocketFactory} class.

     *

     * @param obj the remote object to be exported

     * @param port the port to export the object on

     * @return remote object stub

     * @exception RemoteException if export fails

     * @since 1.2

     */

    public static Remote exportObject(Remote obj, int port)

        throws RemoteException

    {

        return exportObject(obj, new UnicastServerRef(port));

    }

    /**

     * Exports the remote object to make it available to receive incoming

     * calls, using a transport specified by the given socket factory.

     *

     * <p>Either socket factory may be {@code null}, in which case

     * the corresponding client or server socket creation method of

     * {@link RMISocketFactory} is used instead.

     *

     * @param obj the remote object to be exported

     * @param port the port to export the object on

     * @param csf the client-side socket factory for making calls to the

     * remote object

     * @param ssf the server-side socket factory for receiving remote calls

     * @return remote object stub

     * @exception RemoteException if export fails

     * @since 1.2

     */

    public static Remote exportObject(Remote obj, int port,

                                      RMIClientSocketFactory csf,

                                      RMIServerSocketFactory ssf)

        throws RemoteException

    {

        return exportObject(obj, new UnicastServerRef2(port, csf, ssf));

    }

    /**

     * Exports the remote object to make it available to receive incoming

     * calls, using the particular supplied port

     * and {@linkplain ObjectInputFilter filter}.

     *

     * <p>The object is exported with a server socket

     * created using the {@link RMISocketFactory} class.

     *

     * @param obj the remote object to be exported

     * @param port the port to export the object on

     * @param filter an ObjectInputFilter applied when deserializing invocation arguments;

     *               may be {@code null}

     * @return remote object stub

     * @exception RemoteException if export fails

     * @since 9

     */

    public static Remote exportObject(Remote obj, int port,

                                      ObjectInputFilter filter)

            throws RemoteException

    {

        return exportObject(obj, new UnicastServerRef(new LiveRef(port), filter));

    }

    /**

     * Exports the remote object to make it available to receive incoming

     * calls, using a transport specified by the given socket factory

     * and {@linkplain ObjectInputFilter filter}.

     *

     * <p>Either socket factory may be {@code null}, in which case

     * the corresponding client or server socket creation method of

     * {@link RMISocketFactory} is used instead.

     *

     * @param obj the remote object to be exported

     * @param port the port to export the object on

     * @param csf the client-side socket factory for making calls to the

     * remote object

     * @param ssf the server-side socket factory for receiving remote calls

     * @param filter an ObjectInputFilter applied when deserializing invocation arguments;

     *               may be {@code null}

     * @return remote object stub

     * @exception RemoteException if export fails

     * @since 9

     */

    public static Remote exportObject(Remote obj, int port,

                                      RMIClientSocketFactory csf,

                                      RMIServerSocketFactory ssf,

                                      ObjectInputFilter filter)

        throws RemoteException

    {

        return exportObject(obj, new UnicastServerRef2(port, csf, ssf, filter));

    }

    /**

     * Removes the remote object, obj, from the RMI runtime. If

     * successful, the object can no longer accept incoming RMI calls.

     * If the force parameter is true, the object is forcibly unexported

     * even if there are pending calls to the remote object or the

     * remote object still has calls in progress.  If the force

     * parameter is false, the object is only unexported if there are

     * no pending or in progress calls to the object.

     *

     * @param obj the remote object to be unexported

     * @param force if true, unexports the object even if there are

     * pending or in-progress calls; if false, only unexports the object

     * if there are no pending or in-progress calls

     * @return true if operation is successful, false otherwise

     * @exception NoSuchObjectException if the remote object is not

     * currently exported

     * @since 1.2

     */

    public static boolean unexportObject(Remote obj, boolean force)

        throws java.rmi.NoSuchObjectException

    {

        return sun.rmi.transport.ObjectTable.unexportObject(obj, force);

    }

    /**

     * Exports the specified object using the specified server ref.

     */

    private static Remote exportObject(Remote obj, UnicastServerRef sref)

        throws RemoteException

    {

        // if obj extends UnicastRemoteObject, set its ref.

        if (obj instanceof UnicastRemoteObject) {

            ((UnicastRemoteObject) obj).ref = sref;

        }

        return sref.exportObject(obj, null, false);

    }

}