# HG changeset patch
# User Doug Simon <doug.simon@oracle.com>
# Date 1354025450 -3600
# Node ID 947de43c68d6770a9a58cb8ebd93b0902b39275c
# Parent  4cef3dfcaedcfc7f2f0cc21a86645a8c6b78f9b0
improved documentation for ResolvedJavaType.findUniqueConcreteSubtype()
HotSpotResolvedJavaType.findUniqueConcreteSubtype() now matches spec for array types

diff -r 4cef3dfcaedc -r 947de43c68d6 graal/com.oracle.graal.api.meta.test/src/com/oracle/graal/api/meta/test/TestMetaAccessProvider.java
--- a/graal/com.oracle.graal.api.meta.test/src/com/oracle/graal/api/meta/test/TestMetaAccessProvider.java	Tue Nov 27 13:03:08 2012 +0100
+++ b/graal/com.oracle.graal.api.meta.test/src/com/oracle/graal/api/meta/test/TestMetaAccessProvider.java	Tue Nov 27 15:10:50 2012 +0100
@@ -34,7 +34,9 @@
 import com.oracle.graal.api.meta.*;
 import com.oracle.graal.api.runtime.*;
 
-
+/**
+ * Tests for {@link MetaAccessProvider}.
+ */
 public class TestMetaAccessProvider {
 
     public TestMetaAccessProvider() {
diff -r 4cef3dfcaedc -r 947de43c68d6 graal/com.oracle.graal.api.meta.test/src/com/oracle/graal/api/meta/test/TestResolvedJavaType.java
--- a/graal/com.oracle.graal.api.meta.test/src/com/oracle/graal/api/meta/test/TestResolvedJavaType.java	Tue Nov 27 13:03:08 2012 +0100
+++ b/graal/com.oracle.graal.api.meta.test/src/com/oracle/graal/api/meta/test/TestResolvedJavaType.java	Tue Nov 27 15:10:50 2012 +0100
@@ -36,6 +36,9 @@
 
 import com.oracle.graal.api.meta.*;
 
+/**
+ * Tests for {@link ResolvedJavaType}.
+ */
 public class TestResolvedJavaType {
 
     public TestResolvedJavaType() {
@@ -239,9 +242,8 @@
 
     static void checkConcreteSubtype(ResolvedJavaType type, Class expected) {
         ResolvedJavaType subtype = type.findUniqueConcreteSubtype();
-        if (type.isInterface() && subtype == null) {
-            // A runtime may not record the subtype tree for interfaces in which case
-            // findUniqueConcreteSubtype() will return null for interfaces.
+        if (subtype == null) {
+            // The findUniqueConcreteSubtype() method is conservative
             return;
         }
 
@@ -252,10 +254,9 @@
         }
         if (!type.isArrayClass()) {
             ResolvedJavaType arrayType = type.getArrayClass();
-            if (subtype == type) {
-                assertEquals(arrayType.findUniqueConcreteSubtype(), arrayType);
-            } else {
-                assertNull(arrayType.findUniqueConcreteSubtype());
+            ResolvedJavaType arraySubtype = arrayType.findUniqueConcreteSubtype();
+            if (arraySubtype != null) {
+                assertEquals(arraySubtype, arrayType);
             }
         }
     }
diff -r 4cef3dfcaedc -r 947de43c68d6 graal/com.oracle.graal.api.meta/src/com/oracle/graal/api/meta/ResolvedJavaType.java
--- a/graal/com.oracle.graal.api.meta/src/com/oracle/graal/api/meta/ResolvedJavaType.java	Tue Nov 27 13:03:08 2012 +0100
+++ b/graal/com.oracle.graal.api.meta/src/com/oracle/graal/api/meta/ResolvedJavaType.java	Tue Nov 27 15:10:50 2012 +0100
@@ -171,13 +171,21 @@
     ResolvedJavaType findLeastCommonAncestor(ResolvedJavaType otherType);
 
     /**
-     * Gets the unique concrete subclass of this type.
-     *
+     * Attempts to get a unique concrete subclass of this type.
+     * <p>
+     * For an {@linkplain #isArrayClass() array} type A, the unique concrete subclass is A if
+     * the element type of A is primitive or has no subtype. Otherwise there is no unique concrete subclass.
+     * <p>
+     * For a non-array type T, the result is the unique concrete type in the complete hierarchy of T.
+     * <p>
+     * A runtime may decide not to manage or walk a large hierarchy and so the result is conservative.
+     * That is, a non-null result is guaranteed to be the unique concrete class in T's hierarchy
+     * but a null result does not necessarily imply that there is no unique concrete class in T's hierarchy.
      * <p>
      * If the compiler uses the result of this method for its compilation, it must register an assumption because
      * dynamic class loading can invalidate the result of this method.
      *
-     * @return the exact type of this type, if it exists; {@code null} otherwise
+     * @return the unique concrete subclass for this type as described above
      */
     ResolvedJavaType findUniqueConcreteSubtype();