Java example source code file (RemoteClass.java)

This example Java source code file (RemoteClass.java) is included in the alvinalexander.com "Java Source Code Warehouse" project. The intent of this project is to help you "Learn Java by Example" ^TM.

Learn more about this Java project at its project page.

Java - Java tags/keywords

arraylist, assertionerror, bytearrayoutputstream, classdoc, classdoccomparator, dataoutputstream, javadoc, list, messagedigest, method, methoddoc, parameter, remoteclass, security, string, type, util

The RemoteClass.java Java example source code

/*
 * Copyright (c) 2003, 2008, 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 sun.rmi.rmic.newrmic.jrmp;

import com.sun.javadoc.ClassDoc;
import com.sun.javadoc.MethodDoc;
import com.sun.javadoc.Parameter;
import com.sun.javadoc.Type;
import java.io.IOException;
import java.io.ByteArrayOutputStream;
import java.io.DataOutputStream;
import java.security.MessageDigest;
import java.security.DigestOutputStream;
import java.security.NoSuchAlgorithmException;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Comparator;
import java.util.List;
import java.util.HashMap;
import java.util.Map;
import sun.rmi.rmic.newrmic.BatchEnvironment;

import static sun.rmi.rmic.newrmic.Constants.*;
import static sun.rmi.rmic.newrmic.jrmp.Constants.*;

/**
 * Encapsulates RMI-specific information about a remote implementation
 * class (a class that implements one or more remote interfaces).
 *
 * WARNING: The contents of this source file are not part of any
 * supported API.  Code that depends on them does so at its own risk:
 * they are subject to change or removal without notice.
 *
 * @author Peter Jones
 **/
final class RemoteClass {

    /** rmic environment for this object */
    private final BatchEnvironment env;

    /** the remote implementation class this object represents */
    private final ClassDoc implClass;

    /** remote interfaces implemented by this class */
    private ClassDoc[] remoteInterfaces;

    /** the remote methods of this class */
    private Method[] remoteMethods;

    /** stub/skeleton "interface hash" for this class */
    private long interfaceHash;

    /**
     * Creates a RemoteClass instance that represents the RMI-specific
     * information about the specified remote implementation class.
     *
     * If the class is not a valid remote implementation class or if
     * some other error occurs, the return value will be null, and
     * errors will have been reported to the supplied
     * BatchEnvironment.
     **/
    static RemoteClass forClass(BatchEnvironment env, ClassDoc implClass) {
        RemoteClass remoteClass = new RemoteClass(env, implClass);
        if (remoteClass.init()) {
            return remoteClass;
        } else {
            return null;
        }
    }

    /**
     * Creates a RemoteClass instance for the specified class.  The
     * resulting object is not yet initialized.
     **/
    private RemoteClass(BatchEnvironment env, ClassDoc implClass) {
        this.env = env;
        this.implClass = implClass;
    }

    /**
     * Returns the ClassDoc for this remote implementation class.
     **/
    ClassDoc classDoc() {
        return implClass;
    }

    /**
     * Returns the remote interfaces implemented by this remote
     * implementation class.
     *
     * A remote interface is an interface that is a subinterface of
     * java.rmi.Remote.  The remote interfaces of a class are the
     * direct superinterfaces of the class and all of its superclasses
     * that are remote interfaces.
     *
     * The order of the array returned is arbitrary, and some elements
     * may be superfluous (i.e., superinterfaces of other interfaces
     * in the array).
     **/
    ClassDoc[] remoteInterfaces() {
        return remoteInterfaces.clone();
    }

    /**
     * Returns an array of RemoteClass.Method objects representing all
     * of the remote methods of this remote implementation class (all
     * of the member methods of the class's remote interfaces).
     *
     * The methods in the array are ordered according to a comparison
     * of strings consisting of their name followed by their
     * descriptor, so each method's index in the array corresponds to
     * its "operation number" in the JDK 1.1 version of the JRMP
     * stub/skeleton protocol.
     **/
    Method[] remoteMethods() {
        return remoteMethods.clone();
    }

    /**
     * Returns the "interface hash" used to match a stub/skeleton pair
     * for this remote implementation class in the JDK 1.1 version of
     * the JRMP stub/skeleton protocol.
     **/
    long interfaceHash() {
        return interfaceHash;
    }

    /**
     * Validates this remote implementation class and computes the
     * RMI-specific information.  Returns true if successful, or false
     * if an error occurred.
     **/
    private boolean init() {
        /*
         * Verify that it is really a class, not an interface.
         */
        if (implClass.isInterface()) {
            env.error("rmic.cant.make.stubs.for.interface",
                      implClass.qualifiedName());
            return false;
        }

        /*
         * Find all of the remote interfaces of our remote
         * implementation class-- for each class up the superclass
         * chain, add each directly-implemented interface that somehow
         * extends Remote to a list.
         */
        List<ClassDoc> remotesImplemented = new ArrayList();
        for (ClassDoc cl = implClass; cl != null; cl = cl.superclass()) {
            for (ClassDoc intf : cl.interfaces()) {
                /*
                 * Add interface to the list if it extends Remote and
                 * it is not already there.
                 */
                if (!remotesImplemented.contains(intf) &&
                    intf.subclassOf(env.docRemote()))
                {
                    remotesImplemented.add(intf);
                    if (env.verbose()) {
                        env.output("[found remote interface: " +
                                   intf.qualifiedName() + "]");
                    }
                }
            }

            /*
             * Verify that the candidate remote implementation class
             * implements at least one remote interface directly.
             */
            if (cl == implClass && remotesImplemented.isEmpty()) {
                if (implClass.subclassOf(env.docRemote())) {
                    /*
                     * This error message is used if the class does
                     * implement a remote interface through one of its
                     * superclasses, but not directly.
                     */
                    env.error("rmic.must.implement.remote.directly",
                              implClass.qualifiedName());
                } else {
                    /*
                     * This error message is used if the class does
                     * not implement a remote interface at all.
                     */
                    env.error("rmic.must.implement.remote",
                              implClass.qualifiedName());
                }
                return false;
            }
        }

        /*
         * Convert list of remote interfaces to an array
         * (order is not important for this array).
         */
        remoteInterfaces =
            remotesImplemented.toArray(
                new ClassDoc[remotesImplemented.size()]);

        /*
         * Collect the methods from all of the remote interfaces into
         * a table, which maps from method name-and-descriptor string
         * to Method object.
         */
        Map<String,Method> methods = new HashMap();
        boolean errors = false;
        for (ClassDoc intf : remotesImplemented) {
            if (!collectRemoteMethods(intf, methods)) {
                /*
                 * Continue iterating despite errors in order to
                 * generate more complete error report.
                 */
                errors = true;
            }
        }
        if (errors) {
            return false;
        }

        /*
         * Sort table of remote methods into an array.  The elements
         * are sorted in ascending order of the string of the method's
         * name and descriptor, so that each elements index is equal
         * to its operation number in the JDK 1.1 version of the JRMP
         * stub/skeleton protocol.
         */
        String[] orderedKeys =
            methods.keySet().toArray(new String[methods.size()]);
        Arrays.sort(orderedKeys);
        remoteMethods = new Method[methods.size()];
        for (int i = 0; i < remoteMethods.length; i++) {
            remoteMethods[i] = methods.get(orderedKeys[i]);
            if (env.verbose()) {
                String msg = "[found remote method <" + i + ">: " +
                    remoteMethods[i].operationString();
                ClassDoc[] exceptions = remoteMethods[i].exceptionTypes();
                if (exceptions.length > 0) {
                    msg += " throws ";
                    for (int j = 0; j < exceptions.length; j++) {
                        if (j > 0) {
                            msg += ", ";
                        }
                        msg +=  exceptions[j].qualifiedName();
                    }
                }
                msg += "\n\tname and descriptor = \"" +
                    remoteMethods[i].nameAndDescriptor();
                msg += "\n\tmethod hash = " +
                    remoteMethods[i].methodHash() + "]";
                env.output(msg);
            }
        }

        /*
         * Finally, pre-compute the interface hash to be used by
         * stubs/skeletons for this remote class in the JDK 1.1
         * version of the JRMP stub/skeleton protocol.
         */
        interfaceHash = computeInterfaceHash();

        return true;
    }

    /**
     * Collects and validates all methods from the specified interface
     * and all of its superinterfaces as remote methods.  Remote
     * methods are added to the supplied table.  Returns true if
     * successful, or false if an error occurred.
     **/
    private boolean collectRemoteMethods(ClassDoc intf,
                                         Map<String,Method> table)
    {
        if (!intf.isInterface()) {
            throw new AssertionError(
                intf.qualifiedName() + " not an interface");
        }

        boolean errors = false;

        /*
         * Search interface's declared methods.
         */
    nextMethod:
        for (MethodDoc method : intf.methods()) {

            /*
             * Verify that each method throws RemoteException (or a
             * superclass of RemoteException).
             */
            boolean hasRemoteException = false;
            for (ClassDoc ex : method.thrownExceptions()) {
                if (env.docRemoteException().subclassOf(ex)) {
                    hasRemoteException = true;
                    break;
                }
            }

            /*
             * If this method did not throw RemoteException as required,
             * generate the error but continue, so that multiple such
             * errors can be reported.
             */
            if (!hasRemoteException) {
                env.error("rmic.must.throw.remoteexception",
                          intf.qualifiedName(),
                          method.name() + method.signature());
                errors = true;
                continue nextMethod;
            }

            /*
             * Verify that the implementation of this method throws only
             * java.lang.Exception or its subclasses (fix bugid 4092486).
             * JRMP does not support remote methods throwing
             * java.lang.Throwable or other subclasses.
             */
            MethodDoc implMethod = findImplMethod(method);
            if (implMethod != null) {           // should not be null
                for (ClassDoc ex : implMethod.thrownExceptions()) {
                    if (!ex.subclassOf(env.docException())) {
                        env.error("rmic.must.only.throw.exception",
                                  implMethod.name() + implMethod.signature(),
                                  ex.qualifiedName());
                        errors = true;
                        continue nextMethod;
                    }
                }
            }

            /*
             * Create RemoteClass.Method object to represent this method
             * found in a remote interface.
             */
            Method newMethod = new Method(method);

            /*
             * Store remote method's representation in the table of
             * remote methods found, keyed by its name and descriptor.
             *
             * If the table already contains an entry with the same
             * method name and descriptor, then we must replace the
             * old entry with a Method object that represents a legal
             * combination of the old and the new methods;
             * specifically, the combined method must have a throws
             * clause that contains (only) all of the checked
             * exceptions that can be thrown by both the old and the
             * new method (see bugid 4070653).
             */
            String key = newMethod.nameAndDescriptor();
            Method oldMethod = table.get(key);
            if (oldMethod != null) {
                newMethod = newMethod.mergeWith(oldMethod);
            }
            table.put(key, newMethod);
        }

        /*
         * Recursively collect methods for all superinterfaces.
         */
        for (ClassDoc superintf : intf.interfaces()) {
            if (!collectRemoteMethods(superintf, table)) {
                errors = true;
            }
        }

        return !errors;
    }

    /**
     * Returns the MethodDoc for the method of this remote
     * implementation class that implements the specified remote
     * method of a remote interface.  Returns null if no matching
     * method was found in this remote implementation class.
     **/
    private MethodDoc findImplMethod(MethodDoc interfaceMethod) {
        String name = interfaceMethod.name();
        String desc = Util.methodDescriptorOf(interfaceMethod);
        for (MethodDoc implMethod : implClass.methods()) {
            if (name.equals(implMethod.name()) &&
                desc.equals(Util.methodDescriptorOf(implMethod)))
            {
                return implMethod;
            }
        }
        return null;
    }

    /**
     * Computes the "interface hash" of the stub/skeleton pair for
     * this remote implementation class.  This is the 64-bit value
     * used to enforce compatibility between a stub class and a
     * skeleton class in the JDK 1.1 version of the JRMP stub/skeleton
     * protocol.
     *
     * It is calculated using the first 64 bits of an SHA digest.  The
     * digest is of a stream consisting of the following data:
     *     (int) stub version number, always 1
     *     for each remote method, in order of operation number:
     *         (UTF-8) method name
     *         (UTF-8) method descriptor
     *         for each declared exception, in alphabetical name order:
     *             (UTF-8) name of exception class
     * (where "UTF-8" includes a 16-bit length prefix as written by
     * java.io.DataOutput.writeUTF).
     **/
    private long computeInterfaceHash() {
        long hash = 0;
        ByteArrayOutputStream sink = new ByteArrayOutputStream(512);
        try {
            MessageDigest md = MessageDigest.getInstance("SHA");
            DataOutputStream out = new DataOutputStream(
                new DigestOutputStream(sink, md));

            out.writeInt(INTERFACE_HASH_STUB_VERSION);

            for (Method method : remoteMethods) {
                MethodDoc methodDoc = method.methodDoc();

                out.writeUTF(methodDoc.name());
                out.writeUTF(Util.methodDescriptorOf(methodDoc));
                                // descriptors already use binary names

                ClassDoc exceptions[] = methodDoc.thrownExceptions();
                Arrays.sort(exceptions, new ClassDocComparator());
                for (ClassDoc ex : exceptions) {
                    out.writeUTF(Util.binaryNameOf(ex));
                }
            }
            out.flush();

            // use only the first 64 bits of the digest for the hash
            byte hashArray[] = md.digest();
            for (int i = 0; i < Math.min(8, hashArray.length); i++) {
                hash += ((long) (hashArray[i] & 0xFF)) << (i * 8);
            }
        } catch (IOException e) {
            throw new AssertionError(e);
        } catch (NoSuchAlgorithmException e) {
            throw new AssertionError(e);
        }

        return hash;
    }

    /**
     * Compares ClassDoc instances according to the lexicographic
     * order of their binary names.
     **/
    private static class ClassDocComparator implements Comparator<ClassDoc> {
        public int compare(ClassDoc o1, ClassDoc o2) {
            return Util.binaryNameOf(o1).compareTo(Util.binaryNameOf(o2));
        }
    }

    /**
     * Encapsulates RMI-specific information about a particular remote
     * method in the remote implementation class represented by the
     * enclosing RemoteClass.
     **/
    final class Method implements Cloneable {

        /**
         * MethodDoc for this remove method, from one of the remote
         * interfaces that this method was found in.
         *
         * Note that this MethodDoc may be only one of multiple that
         * correspond to this remote method object, if multiple of
         * this class's remote interfaces contain methods with the
         * same name and descriptor.  Therefore, this MethodDoc may
         * declare more exceptions thrown that this remote method
         * does.
         **/
        private final MethodDoc methodDoc;

        /** java.rmi.server.Operation string for this remote method */
        private final String operationString;

        /** name and descriptor of this remote method */
        private final String nameAndDescriptor;

        /** JRMP "method hash" for this remote method */
        private final long methodHash;

        /**
         * Exceptions declared to be thrown by this remote method.
         *
         * This list may include superfluous entries, such as
         * unchecked exceptions and subclasses of other entries.
         **/
        private ClassDoc[] exceptionTypes;

        /**
         * Creates a new Method instance for the specified method.
         **/
        Method(MethodDoc methodDoc) {
            this.methodDoc = methodDoc;
            exceptionTypes = methodDoc.thrownExceptions();
            /*
             * Sort exception types to improve consistency with
             * previous implementations.
             */
            Arrays.sort(exceptionTypes, new ClassDocComparator());
            operationString = computeOperationString();
            nameAndDescriptor =
                methodDoc.name() + Util.methodDescriptorOf(methodDoc);
            methodHash = computeMethodHash();
        }

        /**
         * Returns the MethodDoc object corresponding to this method
         * of a remote interface.
         **/
        MethodDoc methodDoc() {
            return methodDoc;
        }

        /**
         * Returns the parameter types declared by this method.
         **/
        Type[] parameterTypes() {
            Parameter[] parameters = methodDoc.parameters();
            Type[] paramTypes = new Type[parameters.length];
            for (int i = 0; i < paramTypes.length; i++) {
                paramTypes[i] = parameters[i].type();
            }
            return paramTypes;
        }

        /**
         * Returns the exception types declared to be thrown by this
         * remote method.
         *
         * For methods with the same name and descriptor inherited
         * from multiple remote interfaces, the array will contain the
         * set of exceptions declared in all of the interfaces'
         * methods that can be legally thrown by all of them.
         **/
        ClassDoc[] exceptionTypes() {
            return exceptionTypes.clone();
        }

        /**
         * Returns the JRMP "method hash" used to identify this remote
         * method in the JDK 1.2 version of the stub protocol.
         **/
        long methodHash() {
            return methodHash;
        }

        /**
         * Returns the string representation of this method
         * appropriate for the construction of a
         * java.rmi.server.Operation object.
         **/
        String operationString() {
            return operationString;
        }

        /**
         * Returns a string consisting of this method's name followed
         * by its descriptor.
         **/
        String nameAndDescriptor() {
            return nameAndDescriptor;
        }

        /**
         * Returns a new Method object that is a legal combination of
         * this Method object and another one.
         *
         * Doing this requires determining the exceptions declared by
         * the combined method, which must be (only) all of the
         * exceptions declared in both old Methods that may thrown in
         * either of them.
         **/
        Method mergeWith(Method other) {
            if (!nameAndDescriptor().equals(other.nameAndDescriptor())) {
                throw new AssertionError(
                    "attempt to merge method \"" +
                    other.nameAndDescriptor() + "\" with \"" +
                    nameAndDescriptor());
            }

            List<ClassDoc> legalExceptions = new ArrayList();
            collectCompatibleExceptions(
                other.exceptionTypes, exceptionTypes, legalExceptions);
            collectCompatibleExceptions(
                exceptionTypes, other.exceptionTypes, legalExceptions);

            Method merged = clone();
            merged.exceptionTypes =
                legalExceptions.toArray(new ClassDoc[legalExceptions.size()]);

            return merged;
        }

        /**
         * Cloning is supported by returning a shallow copy of this
         * object.
         **/
        protected Method clone() {
            try {
                return (Method) super.clone();
            } catch (CloneNotSupportedException e) {
                throw new AssertionError(e);
            }
        }

        /**
         * Adds to the supplied list all exceptions in the "froms"
         * array that are subclasses of an exception in the "withs"
         * array.
         **/
        private void collectCompatibleExceptions(ClassDoc[] froms,
                                                 ClassDoc[] withs,
                                                 List<ClassDoc> list)
        {
            for (ClassDoc from : froms) {
                if (!list.contains(from)) {
                    for (ClassDoc with : withs) {
                        if (from.subclassOf(with)) {
                            list.add(from);
                            break;
                        }
                    }
                }
            }
        }

        /**
         * Computes the JRMP "method hash" of this remote method.  The
         * method hash is a long containing the first 64 bits of the
         * SHA digest from the UTF-8 encoded string of the method name
         * and descriptor.
         **/
        private long computeMethodHash() {
            long hash = 0;
            ByteArrayOutputStream sink = new ByteArrayOutputStream(512);
            try {
                MessageDigest md = MessageDigest.getInstance("SHA");
                DataOutputStream out = new DataOutputStream(
                    new DigestOutputStream(sink, md));

                String methodString = nameAndDescriptor();
                out.writeUTF(methodString);

                // use only the first 64 bits of the digest for the hash
                out.flush();
                byte hashArray[] = md.digest();
                for (int i = 0; i < Math.min(8, hashArray.length); i++) {
                    hash += ((long) (hashArray[i] & 0xFF)) << (i * 8);
                }
            } catch (IOException e) {
                throw new AssertionError(e);
            } catch (NoSuchAlgorithmException e) {
                throw new AssertionError(e);
            }

            return hash;
        }

        /**
         * Computes the string representation of this method
         * appropriate for the construction of a
         * java.rmi.server.Operation object.
         **/
        private String computeOperationString() {
            /*
             * To be consistent with previous implementations, we use
             * the deprecated style of placing the "[]" for the return
             * type (if any) after the parameter list.
             */
            Type returnType = methodDoc.returnType();
            String op = returnType.qualifiedTypeName() + " " +
                methodDoc.name() + "(";
            Parameter[] parameters = methodDoc.parameters();
            for (int i = 0; i < parameters.length; i++) {
                if (i > 0) {
                    op += ", ";
                }
                op += parameters[i].type().toString();
            }
            op += ")" + returnType.dimension();
            return op;
        }
    }
}