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

• A descriptions of the messages that may be sent to members of this type.
• ValueGuard (coerce/2) behavior, enabling a Class to be used as a ValueGuard.
• SlotGuard (makeSlot/2) behavior, enabling...
• Auditor (audit/1) behavior, enabling...

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 "[]".