src/share/classes/sun/rmi/rmic/newrmic/jrmp/RemoteClass.java - toolchain/jdk/jdk9_jdk - Git at Google

 /*
  * 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<ClassDoc>();
         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<String,Method>();
         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<ClassDoc>();
             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;
         }
     }
 }
	/*
	* 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<ClassDoc>();
	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<String,Method>();
	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<ClassDoc>();
	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;
	}
	}
	}