org.erights.e.elib.base
Class ClassDesc

java.lang.Object
  |
  +--org.erights.e.elib.slot.BaseGuard
        |
        +--org.erights.e.elib.slot.BaseAuditor
              |
              +--org.erights.e.elib.base.TypeDesc
                    |
                    +--org.erights.e.elib.base.ClassDesc
All Implemented Interfaces:
Auditor, Guard, Marker, Persistent, Serializable, SlotGuard, ValueGuard
Direct Known Subclasses:
ArrayGuardSugar, BigIntegerGuardSugar, ByteGuardSugar, ClassGuardSugar, DoubleGuardSugar, EListGuardSugar, FloatGuardSugar, IntegerGuardSugar, InterfaceGuardSugar, LongGuardSugar, RefGuardSugar, ShortGuardSugar, StringGuardSugar, ThrowableGuardSugar, TypeDescGuardSugar, VoidGuardSugar

public class ClassDesc
extends TypeDesc

Untamed: Describes the E-type of instances of a Java class (and its subclasses). This is the Java type as modified by the E sugar mechanism, and as seen through E.

Author:
Mark S. Miller
See Also:
Serialized Form

Field Summary
private static Class[] ArgTypes
           
private static FlexMap DescCache
          A Mapping from classes, primitive or not, to ClassDescs (instances of ClassDesc or a GuardSugar subclass of ClassDesc).
private static Class[] FloatingTypeList
           
private static ConstMap FloatingTypes
           
private static FlexMap GuardCache
           
private static String[][] GuardSugarings
          Maps from the fully qualified class name of a non-primitive to the fqname of the GuardSugar class providing its coerce method.
private static Class[] IntegralTypeList
           
private static ConstMap IntegralTypes
           
private  Class myClass
           
(package private) static long serialVersionUID
           
private static ConstMap TheGuardSugars
          The above list of pairs turned into a ConstMap.
 
Fields inherited from class org.erights.e.elib.base.TypeDesc
 
Fields inherited from class org.erights.e.elib.slot.BaseGuard
myOptValueGuard
 
Fields inherited from interface org.erights.e.elib.serial.Persistent
HONORARY, HONORED_NAMES
 
Constructor Summary
ClassDesc(Class clazz)
          Enabled:
 
Method Summary
 Class asClass()
          Enabled: Not meaningful from E, since a Class promotes to its ClassDesc anyway.
static Guard byJavaRules(Class clazz)
          Enabled: Returns a guard that corresponds more closely than make/1, in two ways, to Java's type conformance rules.
 Object coerce(Object specimen, OneArgFunc optEjector)
          Enabled: Shortens, handles null, handles a trivial match (Class.isInstance(Object)), and otherwise delegates to subCoerce(Object, OneArgFunc).
static String flatName(String fqName)
          Enabled: Drops any package or containing class prefixes.
static String flatSig(Class type)
          Enabled: Only the class name itself without the package qualifier.
 Guard get()
          Enabled: Cause "myClass[]" to return the type "list of myClass".
 Object get(int index)
          Enabled: Cause "myClass[5]" to return a 5 element array of myClass.
private static Class GetGuard(Class clazz)
           
static boolean isFloating(Class clazz)
          Enabled:
static boolean isIntegral(Class clazz)
          Enabled:
static ClassDesc make(Class clazz)
          Enabled: Returns the E-object that a Java Class object promotes to.
private static ConstList mTypes(Class clazz)
           
private static ClassDesc privateMake(Class clazz)
          Returns a description of the messages that may be sent to members of this type.
static String sig(Class type)
          Enabled: If an array type, then the sig of the base type followed by "[]".
static String sig(Class type, String suffix)
          Enabled: If an array type, then the sig-with-suffix of the base type followed by "[]".
static String simpleName(String fqName)
          Enabled: Drops any package or containing class prefixes and any "__C" or "__T" suffixes prior to the last "significant" name.
static String simpleSig(Class type)
          Enabled: Only the class name itself without the package qualifier.
 Object subCoerce(Object specimen, OneArgFunc optEjector)
          Enabled: 'specimen' is assumed to already be shortened, not be null, and already known not to be an instance of myClass.
 
Methods inherited from class org.erights.e.elib.base.TypeDesc
getAuditors, getDocComment, getFQName, getMessageTypes, getName, prettyPrintOn, show, toString
 
Methods inherited from class org.erights.e.elib.slot.BaseAuditor
audit
 
Methods inherited from class org.erights.e.elib.slot.BaseGuard
__printOn, accepts, and, butNot, coerce, makeSlot, makeSlot, not, or, xor
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

serialVersionUID

static final long serialVersionUID

GuardSugarings

private static final String[][] GuardSugarings
Maps from the fully qualified class name of a non-primitive to the fqname of the GuardSugar class providing its coerce method.

When a Class is used as a type (coerced to a ClassDesc), it might have per-Class coercion behavior. Such behavior would be in a GuardSugar class that implements ValueGuard. This table maps from the fqnames of Classes to the fqnames of their corresponding GuardSugar class. The ClassDesc that a Class is an instance of this GuardSugar.

For a given Class, if a direct match isn't found, we check that class's supertypes (both extends & implements). If a unique best match is found we take that. Otherwise we throw an Exception. (XXX double check that we actually do so.)

Arrays make use of ArrayGuardSugar, interfaces make use of InterfaceGuardSugar by default, and fully unmatched types make use of ClassDesc itself.


TheGuardSugars

private static final ConstMap TheGuardSugars
The above list of pairs turned into a ConstMap.


GuardCache

private static final FlexMap GuardCache

DescCache

private static final FlexMap DescCache
A Mapping from classes, primitive or not, to ClassDescs (instances of ClassDesc or a GuardSugar subclass of ClassDesc).


ArgTypes

private static final Class[] ArgTypes

IntegralTypeList

private static final Class[] IntegralTypeList

IntegralTypes

private static final ConstMap IntegralTypes

FloatingTypeList

private static final Class[] FloatingTypeList

FloatingTypes

private static final ConstMap FloatingTypes

myClass

private final Class myClass
Constructor Detail

ClassDesc

public ClassDesc(Class clazz)
Enabled:

Method Detail

GetGuard

private static Class GetGuard(Class clazz)
                       throws ClassNotFoundException
Parameters:
clazz - A non-primitive class
Returns:
A kind of ClassDesc.
ClassNotFoundException

byJavaRules

public static Guard byJavaRules(Class clazz)
Enabled: Returns a guard that corresponds more closely than make/1, in two ways, to Java's type conformance rules.

1) In Java, what a class is used to declare a variable, parameter, or return type, unless the class is primitive, it accepts null in addition to instances of its type. If the class is primitive (ie, a scalar, like char, then it accepts only instances of its type.

By contrast, when a Java class is used as an E guard, it accepts only instances of its type. In order to form a guard that accepts either null or any instance of class T, one uses the nullOk function:

     def x :nullOk(T)
 
The byJavaRules/1 method will turn a class into a guard in the same way as make/1, except that if the Class parameter isn't primitive, it'll then wrap the result in a call to nullOk/1.

2) The class Object.class is turned into the equivalent of :any rather than using a ClassDesc on the class object. This reflects that Java parameters of type Object will also accept non-near pointers. Likewise, it converts Void.class and Void.TYPE into the equivalent of :void.


make

public static ClassDesc make(Class clazz)
Enabled: Returns the E-object that a Java Class object promotes to.

This provides several services


privateMake

private static ClassDesc privateMake(Class clazz)
                              throws ClassNotFoundException,
                                     IllegalAccessException,
                                     InstantiationException,
                                     java.lang.reflect.InvocationTargetException,
                                     NoSuchMethodException
Returns a description of the messages that may be sent to members of this type.

ClassNotFoundException
IllegalAccessException
InstantiationException
java.lang.reflect.InvocationTargetException
NoSuchMethodException

mTypes

private static ConstList mTypes(Class clazz)

isIntegral

public static boolean isIntegral(Class clazz)
Enabled:


isFloating

public static boolean isFloating(Class clazz)
Enabled:


coerce

public Object coerce(Object specimen,
                     OneArgFunc optEjector)
Enabled: Shortens, handles null, handles a trivial match (Class.isInstance(Object)), and otherwise delegates to subCoerce(Object, OneArgFunc).

But does check the output, so it can give a meaningful error if it doesn't match. This allows subCoerce implementations to avoid checking for those errors that may as well be caught here.

Specified by:
coerce in interface ValueGuard
Overrides:
coerce in class BaseAuditor

subCoerce

public Object subCoerce(Object specimen,
                        OneArgFunc optEjector)
Enabled: 'specimen' is assumed to already be shortened, not be null, and already known not to be an instance of myClass.

Used by coerce(Object, OneArgFunc) and overridden by subclasses to provide the type-specific part of the coercion behavior. The default implementation here firsts sees if specimen promotes to a subtype of the target type, and if so, returns that promotion. Failing that, the default implementation ejects according to optEjector.

Subclasses should override to provide other coercions, and delegate to this one (super.subCoerce...) if they can't coerce.

Although this is public, it's not intended to be invokable from E.


asClass

public final Class asClass()
Enabled: Not meaningful from E, since a Class promotes to its ClassDesc anyway.


get

public Object get(int index)
Enabled: Cause "myClass[5]" to return a 5 element array of myClass.

Rather weird kludge. Result is that, in E, "myClass[5]" doesn't get the fifth (or sixth) of anything, but rather produces a 5 element array of type myClass.


get

public Guard get()
Enabled: Cause "myClass[]" to return the type "list of myClass".

At the Java level, it's actually the type "Array of myClass".

Specified by:
get in interface Guard
Overrides:
get in class BaseGuard
Returns:

flatName

public static String flatName(String fqName)
Enabled: Drops any package or containing class prefixes.


simpleName

public static String simpleName(String fqName)
Enabled: Drops any package or containing class prefixes and any "__C" or "__T" suffixes prior to the last "significant" name.

A "significant" name is any name that doesn't begin with a digit (ruling out anonymous objects and classes) and that isn't "self".


sig

public static String sig(Class type,
                         String suffix)
Enabled: If an array type, then the sig-with-suffix of the base type followed by "[]".


sig

public static String sig(Class type)
Enabled: If an array type, then the sig of the base type followed by "[]".

For example, an array or arrays of Strings would be "java.lang.String[][]". Primitive types are represented by their simple name.


flatSig

public static String flatSig(Class type)
Enabled: Only the class name itself without the package qualifier.

If an array type, then the flatSig of the base type followed by "[]".


simpleSig

public static String simpleSig(Class type)
Enabled: Only the class name itself without the package qualifier.

If an array type, then the simpleSig of the base type followed by "[]".



comments?