public interface JavaProvider
JavaProvider
interface defines the requirements of the compiler for retrieving class information. Clients may provide implementations of the JavaProvider if they would like to provide customize class information.
This is essentially a class loader with an API customized for the compiler implementation.
The comments describing the interface methods describe the requirements that an implementation must satisfy in order to work properly with the compiler.
Modifier and Type | Method and Description |
---|---|
JavaType |
getArrayType(JavaType componentType, int dimensions)
Fetch the
JavaType representing the given array type of the specified component type and dimensions. |
JavaClass |
getClass(java.lang.String fqName)
Fetch the
JavaClass for the given fully-qualified type name in dotted notation. |
JavaClass |
getClass(java.lang.String fqPrefix, java.lang.String name)
Fetch the
JavaClass for the given qualified class. |
JavaClass |
getClassByVMName(java.lang.String fqVmName)
Fetch the
JavaClass for the specified fully-qualified type name in VM notation. |
JavaPackage |
getPackage(java.lang.String fqPrefix)
Fetch the
JavaPackage for the given fully-qualified package prefix. |
SourceClass |
getSourceClass(java.lang.String fqName)
Fetch the
SourceClass for the fully-qualified class name. |
TextBuffer |
getTextBuffer(java.net.URL url)
Fetch a
TextBuffer instance for the specified URL. |
JavaClass getClass(java.lang.String fqName)
JavaClass
for the given fully-qualified type name in dotted notation. The type may denote a primitive type, or a class type.
If the qualified name specified represents a primitive type, then the implementer is required to return the canonical PrimitiveType
instance. PrimitiveType
is in the "common" subpackage and implementers can get the correct one by calling CommonUtilities.getPrimitiveType( String )
.
If the qualified name specified represents a class type, the implementation has the choice of fetching the class information from either a Java class (*.class) or source (*.java) file. The choice is given to implementations for performance reasons, though implementations are required to provide up-to-date information.
For class types, implementations are required to perform left-to-right class resolution.
Although implementations are not required to return the same JavaClass
instance each time, they are encouraged to do so as it will dramatically improve performance.
If the fully-qualified type name is a generic type use, a proper parameterized type is returned as long as all types can be resolved by this provider. For instance, "java.util.List<String>" results in a JavaType with the qualified name "java.util.List<java.lang.String>". However, for any type that can't be resolved, a '?' is used, e.g. given a name "java.util.List<U>", a JavaType is returned with the qualified name "java.util.List<?>", and for "java.util.Map<? extends K, ? extends V>", a Javatype is returned with the qualified name "java.util.Map<?, ?>"
fqName
- the fully-qualified type name in dotted notation, such as "java.lang.Object" or "java.util.Map.Entry"JavaClass getClass(java.lang.String fqPrefix, java.lang.String name)
JavaClass
for the given qualified class. This is similar to getClass( String fqName )
except that it splits out the fully-qualified prefix and class name for convenience.
Implementations can concatenate the fqPrefix and name together and just rely on the getClass( String fqName )
method.
fqPrefix
- the fully-qualified prefixname
- the name of the classgetClass(String)
JavaClass getClassByVMName(java.lang.String fqVmName)
JavaClass
for the specified fully-qualified type name in VM notation. The type may denote an array type, a primitive type, or a class type.
If the qualified name specified represents an array type, the implementer should fetch the JavaClass
for the underlying class first, then generate an array type for the class using getArrayType( class, dimensions )
.
If the qualified name specifies a primitive type, the implementer is required to return the canonical PrimitiveType
instance.
If the qualified name represents a class type, the implementation has the choice of fetching the class information from either a Java class (*.class) or source (*.java) file. The choice is given to implementations for performance reasons, though implementations are required to provide up-to-date information.
The '/' is a package delimiter, while the '$' can be treated literally as part of the class name, or as a class delimiter. Implementations must perform left-to-right resolution on the class name portion to determine whether '$' should be interpreted literally, or as a delimiter.
Although implementations are not required to return the same JavaClass
instance each time, they are encouraged to do so as it will dramatically improve performance.
fqVmName
- the fully-qualified type name (different from the qualified source name and different from the descriptor) in VM notation, such as "java/lang/Object" or "java/util/Map$Entry"JavaType getArrayType(JavaType componentType, int dimensions)
JavaType
representing the given array type of the specified component type and dimensions.componentType
- the component type to generate an array type fordimensions
- the array dimensions for the array typejava.lang.IllegalArgumentException
- if the dimensions are invalid, i.e., negativeSourceClass getSourceClass(java.lang.String fqName)
SourceClass
for the fully-qualified class name. The name must represent a class type. Implementations must base the class information on Java source (*.java) content.
Similar to getClass( String fqName )
, implementations must perform left-to-right package/class resolution.
fqName
- the fully-qualified type name in dotted notation, such as "java.lang.Object" or "java.util.Map.Entry"JavaPackage getPackage(java.lang.String fqPrefix)
JavaPackage
for the given fully-qualified package prefix. An empty String ("") represents the root package.fqPrefix
- the fully-qualified package prefix, such as "java.io" or "javax.swing.text"TextBuffer getTextBuffer(java.net.URL url)
TextBuffer
instance for the specified URL. This is used currently for parsing and resolving a SourceFile. This method may be removed in the future.url
- the URL to fetch the TextBuffer for