Adds some documentation on TypeOracle and JType
Review at http://gwt-code-reviews.appspot.com/1268801
git-svn-id: https://google-web-toolkit.googlecode.com/svn/trunk@9524 8db76d5a-ed1c-0410-87a9-c151d255dfc7
diff --git a/dev/core/src/com/google/gwt/core/ext/typeinfo/JType.java b/dev/core/src/com/google/gwt/core/ext/typeinfo/JType.java
index a5730d4..3d777af 100644
--- a/dev/core/src/com/google/gwt/core/ext/typeinfo/JType.java
+++ b/dev/core/src/com/google/gwt/core/ext/typeinfo/JType.java
@@ -1,12 +1,12 @@
/*
* Copyright 2010 Google Inc.
- *
+ *
* Licensed under the Apache License, Version 2.0 (the "License"); you may not
* use this file except in compliance with the License. You may obtain a copy of
* the License at
- *
+ *
* http://www.apache.org/licenses/LICENSE-2.0
- *
+ *
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
@@ -20,31 +20,57 @@
*/
public interface JType {
+ /**
+ * Returns this type with no type parameters or type variables. See the JLS
+ * Third Edition section on <a href="http://java.sun.com/docs/books/jls/third_edition/html/typesValues.html#4.6">
+ * Type Erasure</a>.
+ */
JType getErasedType();
+ /**
+ * Returns the turns the
+ * <a href="http://java.sun.com/docs/books/jvms/second_edition/html/ClassFile.doc.html#14152">
+ * field descriptor"</a> for a type as specified by the Java Virtual Machine Specification.
+ *
+ * Examples:
+ *
+ * <ul>
+ * <li><b>boolean</b> = <code>Z</code></li>
+ * <li><b>byte[]</b> = <code>[B</code></li>
+ * <li><b>java.lang.String</b> = <code>Ljava/lang/String;</li>
+ * </ul>
+ */
String getJNISignature();
+ /**
+ * For array types, recursively looks for the element type that is not an
+ * array. Otherwise, returns this type.
+ */
JType getLeafType();
String getParameterizedQualifiedSourceName();
/**
- * A binary type name as specified by the
- * <a href="http://java.sun.com/docs/books/jls/second_edition/html/binaryComp.doc.html">
- * Java Language Spec, Edition 2</a>.
+ * A binary type name as specified by the
+ * <a href="http://java.sun.com/docs/books/jls/third_edition/html/binaryComp.html">
+ * Java Language Spec, ThirdEdition</a>.
*/
String getQualifiedBinaryName();
/**
- * A type name as it would be specified in Java source.
+ * Returns a type name as it would be specified in Java source, with the
+ * package name included.
*/
String getQualifiedSourceName();
+ /**
+ * Returns the name of this class without the package name or enclosing class name.
+ */
String getSimpleSourceName();
/**
- * Returns this instance if it is a annotation or <code>null</code> if it is
- * not.
+ * Returns this instance as a {@link JAnnotationType#} if it is a annotation
+ * or <code>null</code> if it is not.
*/
JAnnotationType isAnnotation();
@@ -68,6 +94,10 @@
JPrimitiveType isPrimitive();
+ /**
+ * Returns the raw type if this is a {@link JRawType#}, otherwise returns
+ * <code>null</code>.
+ */
JRawType isRawType();
JTypeParameter isTypeParameter();
diff --git a/dev/core/src/com/google/gwt/core/ext/typeinfo/TypeOracle.java b/dev/core/src/com/google/gwt/core/ext/typeinfo/TypeOracle.java
index c7a4358..f2d9c05 100644
--- a/dev/core/src/com/google/gwt/core/ext/typeinfo/TypeOracle.java
+++ b/dev/core/src/com/google/gwt/core/ext/typeinfo/TypeOracle.java
@@ -1,12 +1,12 @@
/*
* Copyright 2010 Google Inc.
- *
+ *
* Licensed under the Apache License, Version 2.0 (the "License"); you may not
* use this file except in compliance with the License. You may obtain a copy of
* the License at
- *
+ *
* http://www.apache.org/licenses/LICENSE-2.0
- *
+ *
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
@@ -20,15 +20,14 @@
import java.util.Set;
/**
- * Provides type-related information about a set of source files, including doc
- * comment metadata.
+ * Provides type-related information about a set of source files.
* <p>
* All type objects exposed, such as
* {@link com.google.gwt.core.ext.typeinfo.JClassType} and others, have a stable
* identity relative to this type oracle instance. Consequently, you can
* reliably compare object identity of any objects this type oracle produces.
* For example, the following code relies on this stable identity guarantee:
- *
+ *
* <pre>
* JClassType o = typeOracle.getJavaLangObject();
* JClassType s1 = typeOracle.getType("java.lang.String");
@@ -38,7 +37,7 @@
* JParameterizedType ls = typeOracle.parse("java.util.List<java.lang.String>");
* assert (ls.getTypeArgs()[0] == s1);
* </pre>
- *
+ *
* </p>
*/
public abstract class TypeOracle {
@@ -47,7 +46,7 @@
* A reserved metadata tag to indicates that a field type, method return type
* or method parameter type is intended to be parameterized. Note that
* constructor type parameters are not supported at present.
- *
+ *
* @deprecated gwt.typeArgs is not longer supported
*/
@Deprecated
@@ -115,18 +114,18 @@
/**
* Attempts to find a package by name. All requests for the same package
* return the same package object.
- *
+ *
* @return <code>null</code> if the package could not be found
*/
public abstract JPackage findPackage(String pkgName);
/**
* Finds a class or interface given its fully-qualified name.
- *
+ *
* @param name fully-qualified class/interface name - for nested classes, use
* its source name rather than its binary name (that is, use a "."
* rather than a "$")
- *
+ *
* @return <code>null</code> if the type is not found
*/
public abstract JClassType findType(String name);
@@ -135,7 +134,7 @@
* Finds a type given its package-relative name. For nested classes, use its
* source name rather than its binary name (that is, use a "." rather than a
* "$").
- *
+ *
* @return <code>null</code> if the type is not found
*/
public abstract JClassType findType(String pkgName, String typeName);
@@ -144,7 +143,7 @@
* Gets the type object that represents an array of the specified type. The
* returned type always has a stable identity so as to guarantee that all
* calls to this method with the same argument return the same object.
- *
+ *
* @param componentType the component type of the array, which can itself be
* an array type
* @return a type object representing an array of the component type
@@ -166,14 +165,14 @@
/**
* Gets a package by name. All requests for the same package return the same
* package object.
- *
+ *
* @return the package object associated with the specified name
*/
public abstract JPackage getPackage(String pkgName) throws NotFoundException;
/**
* Gets an array of all packages known to this type oracle.
- *
+ *
* @return an array of packages, possibly of zero-length
*/
public abstract JPackage[] getPackages();
@@ -183,7 +182,7 @@
* specified raw type and a set of type arguments. The returned type always
* has a stable identity so as to guarantee that all calls to this method with
* the same arguments return the same object.
- *
+ *
* @param genericType a generic base class
* @param enclosingType
* @param typeArgs the type arguments bound to the specified generic type
@@ -202,7 +201,7 @@
* specified raw type and a set of type arguments. The returned type always
* has a stable identity so as to guarantee that all calls to this method with
* the same arguments return the same object.
- *
+ *
* @param genericType a generic base class
* @param typeArgs the type arguments bound to the specified generic type
* @return a type object representing this particular binding of type
@@ -240,7 +239,7 @@
* Finds a type given its fully qualified name. For nested classes, use its
* source name rather than its binary name (that is, use a "." rather than a
* "$").
- *
+ *
* @return the specified type
*/
public abstract JClassType getType(String name) throws NotFoundException;
@@ -249,7 +248,7 @@
* Finds a type given its package-relative name. For nested classes, use its
* source name rather than its binary name (that is, use a "." rather than a
* "$").
- *
+ *
* @return the specified type
*/
public abstract JClassType getType(String pkgName,
@@ -257,7 +256,7 @@
/**
* Gets all types, both top-level and nested.
- *
+ *
* @return an array of types, possibly of zero length
*/
public abstract JClassType[] getTypes();
@@ -282,7 +281,7 @@
* <li><code>List<List<Shape>></code></li>
* </ul>
* </p>
- *
+ *
* @param type a type signature to be parsed
* @return the type object corresponding to the parse type
*/
diff --git a/dev/core/src/com/google/gwt/dev/javac/typemodel/TypeOracle.java b/dev/core/src/com/google/gwt/dev/javac/typemodel/TypeOracle.java
index 141f0ac..c85021a 100644
--- a/dev/core/src/com/google/gwt/dev/javac/typemodel/TypeOracle.java
+++ b/dev/core/src/com/google/gwt/dev/javac/typemodel/TypeOracle.java
@@ -1,12 +1,12 @@
/*
* Copyright 2008 Google Inc.
- *
+ *
* Licensed under the Apache License, Version 2.0 (the "License"); you may not
* use this file except in compliance with the License. You may obtain a copy of
* the License at
- *
+ *
* http://www.apache.org/licenses/LICENSE-2.0
- *
+ *
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
@@ -46,15 +46,14 @@
import java.util.Set;
/**
- * Provides type-related information about a set of source files, including doc
- * comment metadata.
+ * Provides type-related information about a set of types.
* <p>
* All type objects exposed, such as
* {@link com.google.gwt.core.ext.typeinfo.JClassType} and others, have a stable
* identity relative to this type oracle instance. Consequently, you can
* reliably compare object identity of any objects this type oracle produces.
* For example, the following code relies on this stable identity guarantee:
- *
+ *
* <pre>
* JClassType o = typeOracle.getJavaLangObject();
* JClassType s1 = typeOracle.getType("java.lang.String");
@@ -64,8 +63,9 @@
* JParameterizedType ls = typeOracle.parse("java.util.List<java.lang.String>");
* assert (ls.getTypeArgs()[0] == s1);
* </pre>
- *
+ *
* </p>
+ *
*/
public class TypeOracle extends com.google.gwt.core.ext.typeinfo.TypeOracle {
@@ -207,13 +207,6 @@
});
}
- static JClassType[] cast(
- com.google.gwt.core.ext.typeinfo.JClassType[] extTypeArgs) {
- JClassType[] result = new JClassType[extTypeArgs.length];
- System.arraycopy(extTypeArgs, 0, result, 0, extTypeArgs.length);
- return result;
- }
-
static String[] modifierBitsToNames(int bits) {
List<String> strings = new ArrayList<String>();
@@ -258,16 +251,29 @@
return strings.toArray(NO_STRINGS);
}
+ private static JClassType[] cast(
+ com.google.gwt.core.ext.typeinfo.JClassType[] extTypeArgs) {
+ JClassType[] result = new JClassType[extTypeArgs.length];
+ System.arraycopy(extTypeArgs, 0, result, 0, extTypeArgs.length);
+ return result;
+ }
+
/**
* A map of fully-qualify source names (ie, use "." rather than "$" for nested
* classes) to JRealClassTypes.
*/
private final Map<String, JRealClassType> allTypes = new HashMap<String, JRealClassType>();
+ /**
+ * Cached types that represent Arrays of other types. These types are created as needed.
+ */
@SuppressWarnings("unchecked")
private final Map<JType, JArrayType> arrayTypes = new ReferenceIdentityMap(
AbstractReferenceMap.WEAK, AbstractReferenceMap.WEAK, true);
+ /**
+ * Cached singleton type representing <code>java.lang.Object</code>.
+ */
private JClassType javaLangObject;
private final JavaSourceParser javaSourceParser = new JavaSourceParser();
@@ -277,8 +283,15 @@
*/
private final Map<JClassType, JClassType> jsoSingleImpls = new IdentityHashMap<JClassType, JClassType>();
+ /**
+ * Cached map of all packages thus far encountered.
+ */
private final Map<String, JPackage> packages = new HashMap<String, JPackage>();
+ /**
+ * Subclasses of generic types that have type parameters filled in. These types are created
+ * as needed.
+ */
@SuppressWarnings("unchecked")
private final Map<ParameterizedTypeKey, JParameterizedType> parameterizedTypes = new ReferenceMap(
AbstractReferenceMap.HARD, AbstractReferenceMap.WEAK, true);
@@ -304,7 +317,7 @@
/**
* Attempts to find a package by name. All requests for the same package
* return the same package object.
- *
+ *
* @return <code>null</code> if the package could not be found
*/
@Override
@@ -314,11 +327,11 @@
/**
* Finds a class or interface given its fully-qualified name.
- *
+ *
* @param name fully-qualified class/interface name - for nested classes, use
* its source name rather than its binary name (that is, use a "."
* rather than a "$")
- *
+ *
* @return <code>null</code> if the type is not found
*/
@Override
@@ -331,7 +344,7 @@
* Finds a type given its package-relative name. For nested classes, use its
* source name rather than its binary name (that is, use a "." rather than a
* "$").
- *
+ *
* @return <code>null</code> if the type is not found
*/
@Override
@@ -351,7 +364,7 @@
* Gets the type object that represents an array of the specified type. The
* returned type always has a stable identity so as to guarantee that all
* calls to this method with the same argument return the same object.
- *
+ *
* @param componentType the component type of the array, which can itself be
* an array type
* @return a type object representing an array of the component type
@@ -403,7 +416,7 @@
/**
* Gets a package by name. All requests for the same package return the same
* package object.
- *
+ *
* @return the package object associated with the specified name
*/
@Override
@@ -417,7 +430,7 @@
/**
* Gets an array of all packages known to this type oracle.
- *
+ *
* @return an array of packages, possibly of zero-length
*/
@Override
@@ -430,7 +443,7 @@
* specified raw type and a set of type arguments. The returned type always
* has a stable identity so as to guarantee that all calls to this method with
* the same arguments return the same object.
- *
+ *
* @param genericType a generic base class
* @param enclosingType
* @param typeArgs the type arguments bound to the specified generic type
@@ -498,7 +511,7 @@
* specified raw type and a set of type arguments. The returned type always
* has a stable identity so as to guarantee that all calls to this method with
* the same arguments return the same object.
- *
+ *
* @param genericType a generic base class
* @param typeArgs the type arguments bound to the specified generic type
* @return a type object representing this particular binding of type
@@ -551,7 +564,7 @@
* Finds a type given its fully qualified name. For nested classes, use its
* source name rather than its binary name (that is, use a "." rather than a
* "$").
- *
+ *
* @return the specified type
*/
@Override
@@ -568,7 +581,7 @@
* Finds a type given its package-relative name. For nested classes, use its
* source name rather than its binary name (that is, use a "." rather than a
* "$").
- *
+ *
* @return the specified type
*/
@Override
@@ -584,7 +597,7 @@
/**
* Gets all types, both top-level and nested.
- *
+ *
* @return an array of types, possibly of zero length
*/
@Override
@@ -643,7 +656,7 @@
* <li><code>List<List<Shape>></code></li>
* </ul>
* </p>
- *
+ *
* @param type a type signature to be parsed
* @return the type object corresponding to the parse type
*/
