com.sun.jini.jeri.internal.runtime
Class Util

java.lang.Object
  extended by com.sun.jini.jeri.internal.runtime.Util

public class Util
extends Object

Utility methods for implementing custom remote reference types.

Author:
Sun Microsystems, Inc.

Nested Class Summary
private static class Util.ClientHostImpl
           
private static class Util.ClientSubjectImpl
           
private static class Util.IntegrityEnforcementImpl
           
private static class Util.LazyMethodToHash_Map
           
private static class Util.TableCache
           
 
Field Summary
private static Util.TableCache methodToHash_TableCache
          cache of tables mapping methods to hashes
private static Class[] paramTypes
          parameter types for activatable constructor or activate method
private static Collection prohibitedProxyInterfaces
          names of interfaces that proxies are prohibited from implementing
private static String prohibitedProxyInterfacesResource
          name of the resource containing prohibited proxy interfaces
private static Map proxyRemoteMethodCache
          cache of valid proxy remote methods
 
Constructor Summary
Util()
           
 
Method Summary
private static void __________EXCEPTION_RECEIVED_FROM_SERVER__________(Throwable t)
           
private static void checkExceptions(Class c, String name, Class[] types)
          Throws IllegalArgumentException if any superinterface of c declares a method with the given name and parameter types that does not declare RemoteException or a superclass in its throws clause.
private static void checkMethod(Method m)
          Verifies that the supplied method has at least one declared exception type that is RemoteException or one of its superclasses.
static void checkPackageAccess(Class type)
          Check for permission to access the package of the specified class.
private static void checkProhibitedProxyInterfaces(Class c)
          Throws IllegalArgumentException if any superinterface of c has its name in prohibitedProxyInterfaces.
static void checkProxyRemoteMethod(Class c, Method m)
          Throws IllegalArgumentException if any superinterface of c declares a method with the same name and parameter types as m that does not declare RemoteException or a superclass in its throws clause, or if any superinterface of c has its name in prohibitedProxyInterfaces.
static boolean checkTrustEquivalence(Object subject, Object object)
          Returns true either if both arguments are null of if "subject" is an instance of TrustEquivalence and an invocation of TrustEquivalence.checkTrustEquivalence on "subject" with "object" as the argument returns true; returns false otherwise.
static void clearStackTraces(Throwable t)
          Clear the stack trace of the given exception by replacing it with an empty StackTraceElement array, and do the same for all of its chained causative exceptions.
private static long computeMethodHash(Method m)
          Computes the "method hash" of a remote method, m.
static boolean equalInterfaces(Object obj1, Object obj2)
          Returns true if the interfaces implemented by obj1's class are the same (and in the same order) as obj2's class.
static boolean equals(Object subject, Object object)
          Returns true either if both arguments are null or if an invocation of Object.equals on "subject" with "object" as the argument returns true; returns false otherwise;
static void exceptionReceivedFromServer(Throwable t)
          Appends the current thread's stack trace to the stack trace of the given exception.
static InetAddress getClientHost()
           
static String getClientHostString()
           
static Subject getClientSubject()
           
static long getMethodHash(Method m)
          Returns the method hash for the method m.
static String getMethodNameAndDescriptor(Method m)
          Returns a string consisting of the given method's name followed by its "method descriptor", as appropriate for use in the computation of the "method hash".
private static Collection getProhibitedProxyInterfaces()
          Returns collection of prohibited proxy interfaces read from resources.
private static void getRemoteInterfaces(ArrayList list, Class cl)
          Fills the given array list with the remote interfaces implemented by the given class.
static Class[] getRemoteInterfaces(Class remoteClass)
          Returns an array containing the remote interfaces implemented by the given class.
private static String getTypeDescriptor(Class type)
          Returns the descriptor of a particular type, as appropriate for either a parameter type or return type in a method descriptor.
static String getUnqualifiedName(Class c)
          Returns the binary name of the given type without package qualification.
static void marshalValue(Class type, Object value, ObjectOutput out)
          Marshals value to an ObjectOutput stream, out, using RMI's serialization format for arguments or return values.
static void populateContext(Collection context, boolean integrity)
           
static void populateContext(Collection context, InetAddress addr)
           
static void populateContext(Collection context, Subject s)
           
static boolean sameClassAndEquals(Object subject, Object object)
          Returns true either if both arguments are null or if both arguments refer to objects of the same class and an invocation of Object.equals on "subject" with "object" as the argument returns true; returns false otherwise.
static boolean sameProxyClass(Object proxy1, Object proxy2)
          Returns true if proxy2 is a generated Proxy (proxy1 is assumed to be one) and the classes of both proxies implement the same ordered list of interfaces, and returns false otherwise.
static Object unmarshalValue(Class type, ObjectInput in)
          Unmarshals a value of the specified type from the ObjectInput stream, in, using RMI's serialization format for arguments or return values and returns the result.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

methodToHash_TableCache

private static Util.TableCache methodToHash_TableCache
cache of tables mapping methods to hashes


proxyRemoteMethodCache

private static Map proxyRemoteMethodCache
cache of valid proxy remote methods


paramTypes

private static Class[] paramTypes
parameter types for activatable constructor or activate method


prohibitedProxyInterfacesResource

private static final String prohibitedProxyInterfacesResource
name of the resource containing prohibited proxy interfaces

See Also:
Constant Field Values

prohibitedProxyInterfaces

private static final Collection prohibitedProxyInterfaces
names of interfaces that proxies are prohibited from implementing

Constructor Detail

Util

public Util()
Method Detail

exceptionReceivedFromServer

public static void exceptionReceivedFromServer(Throwable t)
Appends the current thread's stack trace to the stack trace of the given exception. This method is used for exceptions that have been unmarshalled as the exceptional result of a remote method invocation, so that the client-side stack trace gets recorded in the exception (while preserving the server-side stack trace in the exception as well). Note that the (somewhat odd) names of this method and the method that this one internally delegates to are significant because these methods visually highlight the remote call boundary between the server-side and the client-side portions to readers of the combined stack trace.


__________EXCEPTION_RECEIVED_FROM_SERVER__________

private static void __________EXCEPTION_RECEIVED_FROM_SERVER__________(Throwable t)

clearStackTraces

public static void clearStackTraces(Throwable t)
Clear the stack trace of the given exception by replacing it with an empty StackTraceElement array, and do the same for all of its chained causative exceptions. This method is used when it is desired for the stack trace data of an exception to be suppressed before the exception gets marshalled to a remote virtual machine, perhaps for reasons of confidentiality or performance.


marshalValue

public static void marshalValue(Class type,
                                Object value,
                                ObjectOutput out)
                         throws IOException
Marshals value to an ObjectOutput stream, out, using RMI's serialization format for arguments or return values. For primitive types, the primitive type's class should be specified (i.e., for the type int, specify int.class), and the primitive value should be wrapped in instances of the appropriate wrapper class, such as java.lang.Integer or java.lang.Boolean.

Parameters:
type - Class object for the value to be marshalled
value - value to marshal
out - stream to which the value is marshalled
Throws:
IOException - if an I/O error occurs marshalling the value to the output stream

unmarshalValue

public static Object unmarshalValue(Class type,
                                    ObjectInput in)
                             throws IOException,
                                    ClassNotFoundException
Unmarshals a value of the specified type from the ObjectInput stream, in, using RMI's serialization format for arguments or return values and returns the result. For primitive types, the primitive type's class should be specified (i.e., for the primitive type int, specify int.class).

Parameters:
type - Class object for the value to be unmarshalled
in - stream from which the value is unmarshalled
Returns:
value unmarshalled from the input stream
Throws:
IOException - if an I/O error occurs marshalling the value to the output stream
ClassNotFoundException - if the type's class could not be found

computeMethodHash

private static long computeMethodHash(Method m)
Computes the "method hash" of a remote method, m. The method hash is a long containing the first 64 bits of the SHA digest from the UTF encoded string of the method name followed by its "method descriptor". See section 4.3.3 of The Java(TM) Virtual Machine Specification for the definition of a "method descriptor".

Parameters:
m - remote method
Returns:
the method hash

getMethodHash

public static long getMethodHash(Method m)
Returns the method hash for the method m. Subsequent calls to getMethodHash passing the same method argument should be faster since this method caches internally the result of the method to method hash mapping. The method hash is calculated using the computeMethodHash method.

Parameters:
m - the remote method
Returns:
the method hash for the method m

checkMethod

private static void checkMethod(Method m)
Verifies that the supplied method has at least one declared exception type that is RemoteException or one of its superclasses. If not, then this method throws IllegalArgumentException.

Throws:
IllegalArgumentException - if m is an illegal remote method

getMethodNameAndDescriptor

public static String getMethodNameAndDescriptor(Method m)
Returns a string consisting of the given method's name followed by its "method descriptor", as appropriate for use in the computation of the "method hash". See section 4.3.3 of The Java(TM) Virtual Machine Specification for the definition of a "method descriptor".


getTypeDescriptor

private static String getTypeDescriptor(Class type)
Returns the descriptor of a particular type, as appropriate for either a parameter type or return type in a method descriptor.


getRemoteInterfaces

public static Class[] getRemoteInterfaces(Class remoteClass)
Returns an array containing the remote interfaces implemented by the given class.

Throws:
IllegalArgumentException - if remoteClass implements any illegal remote interfaces
NullPointerException - if remoteClass is null

getRemoteInterfaces

private static void getRemoteInterfaces(ArrayList list,
                                        Class cl)
Fills the given array list with the remote interfaces implemented by the given class.

Throws:
IllegalArgumentException - if the specified class implements any illegal remote interfaces
NullPointerException - if the specified class or list is null

checkProxyRemoteMethod

public static void checkProxyRemoteMethod(Class c,
                                          Method m)
Throws IllegalArgumentException if any superinterface of c declares a method with the same name and parameter types as m that does not declare RemoteException or a superclass in its throws clause, or if any superinterface of c has its name in prohibitedProxyInterfaces.


checkExceptions

private static void checkExceptions(Class c,
                                    String name,
                                    Class[] types)
Throws IllegalArgumentException if any superinterface of c declares a method with the given name and parameter types that does not declare RemoteException or a superclass in its throws clause.


getProhibitedProxyInterfaces

private static Collection getProhibitedProxyInterfaces()
Returns collection of prohibited proxy interfaces read from resources.


checkProhibitedProxyInterfaces

private static void checkProhibitedProxyInterfaces(Class c)
Throws IllegalArgumentException if any superinterface of c has its name in prohibitedProxyInterfaces.


getUnqualifiedName

public static String getUnqualifiedName(Class c)
Returns the binary name of the given type without package qualification. Nested types are treated no differently from top-level types, so for a nested type, the returned name will still be qualified with the simple name of its enclosing top-level type (and perhaps other enclosing types), the separator will be '$', etc.


equals

public static boolean equals(Object subject,
                             Object object)
Returns true either if both arguments are null or if an invocation of Object.equals on "subject" with "object" as the argument returns true; returns false otherwise;


sameClassAndEquals

public static boolean sameClassAndEquals(Object subject,
                                         Object object)
Returns true either if both arguments are null or if both arguments refer to objects of the same class and an invocation of Object.equals on "subject" with "object" as the argument returns true; returns false otherwise. This method is used to compare to possibly-null references for object equality when neither object's class is trusted, with the restriction that only objects of the same class can be considered equal.


checkTrustEquivalence

public static boolean checkTrustEquivalence(Object subject,
                                            Object object)
Returns true either if both arguments are null of if "subject" is an instance of TrustEquivalence and an invocation of TrustEquivalence.checkTrustEquivalence on "subject" with "object" as the argument returns true; returns false otherwise.


sameProxyClass

public static boolean sameProxyClass(Object proxy1,
                                     Object proxy2)
Returns true if proxy2 is a generated Proxy (proxy1 is assumed to be one) and the classes of both proxies implement the same ordered list of interfaces, and returns false otherwise.


equalInterfaces

public static boolean equalInterfaces(Object obj1,
                                      Object obj2)
Returns true if the interfaces implemented by obj1's class are the same (and in the same order) as obj2's class.


populateContext

public static void populateContext(Collection context,
                                   InetAddress addr)

populateContext

public static void populateContext(Collection context,
                                   Subject s)

populateContext

public static void populateContext(Collection context,
                                   boolean integrity)

getClientHost

public static InetAddress getClientHost()
                                 throws ServerNotActiveException
Throws:
ServerNotActiveException

getClientHostString

public static String getClientHostString()
                                  throws ServerNotActiveException
Throws:
ServerNotActiveException

getClientSubject

public static Subject getClientSubject()
                                throws ServerNotActiveException
Throws:
ServerNotActiveException

checkPackageAccess

public static void checkPackageAccess(Class type)
Check for permission to access the package of the specified class.

Throws:
SecurityException - if a security manager exists and invoking its checkPackageAccess method with the package name of the specified class throws a SecurityException


Copyright 2007-2010, multiple authors.
Licensed under the Apache License, Version 2.0, see the NOTICE file for attributions.