oracle.javatools.parser.java.v2

Interface JavaProvider

All Known Subinterfaces:

CmtPackages, JavaFileProvider, JavaProvider2

All Known Implementing Classes:

BaseFileProvider, CachedFileProvider, CustomJavaManager, JavaManager, JavaModel, NullProvider, ProjectFileProvider, SimpleFileProvider

public interface JavaProvider

The 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.

Method Summary

Methods

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.

Method Detail

getClass

JavaClass getClass(java.lang.String fqName)

Fetch the 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<?, ?>"

Parameters:

fqName - the fully-qualified type name in dotted notation, such as "java.lang.Object" or "java.util.Map.Entry"

Returns:

the JavaClass instance for the given qualified type name, or null if it cannot be found

getClass

JavaClass getClass(java.lang.String fqPrefix,
                 java.lang.String name)

Fetch the 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.

Parameters:

fqPrefix - the fully-qualified prefix

name - the name of the class

Returns:

the JavaClass instance for the given qualified type name or null it cannot be found

See Also:

getClass(String)

getClassByVMName

JavaClass getClassByVMName(java.lang.String fqVmName)

Fetch the 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.

Parameters:

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"

Returns:

the JavaClass instance for the given qualified type name in VM notation, or null if it cannot be found

getArrayType

JavaType getArrayType(JavaType componentType,
                    int dimensions)

Fetch the JavaType representing the given array type of the specified component type and dimensions.

Parameters:

componentType - the component type to generate an array type for

dimensions - the array dimensions for the array type

Returns:

a JavaType representing the requested array type

Throws:

java.lang.IllegalArgumentException - if the dimensions are invalid, i.e., negative

getSourceClass

SourceClass getSourceClass(java.lang.String fqName)

Fetch the 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.

Parameters:

fqName - the fully-qualified type name in dotted notation, such as "java.lang.Object" or "java.util.Map.Entry"

Returns:

the SourceClass instance for the given qualified type name, or null if it cannot be found

getPackage

JavaPackage getPackage(java.lang.String fqPrefix)

Fetch the JavaPackage for the given fully-qualified package prefix. An empty String ("") represents the root package.

Parameters:

fqPrefix - the fully-qualified package prefix, such as "java.io" or "javax.swing.text"

Returns:

the requested JavaPackage, or null if the prefix was null

getTextBuffer

TextBuffer getTextBuffer(java.net.URL url)

Fetch a TextBuffer instance for the specified URL. This is used currently for parsing and resolving a SourceFile. This method may be removed in the future.

Parameters:

url - the URL to fetch the TextBuffer for

Returns:

the text buffer instance for the input URL