clarification on docs of Class#getInterfaces() and Class#getGenericInterfaces() needed? (original) (raw)

Jochen Theodorou blackdrag at gmx.org
Mon Mar 10 15:10:02 UTC 2014

Hi,

hoping I will not annoy anyway asking this here I was wondering about how to interpret the javadoc of these methods correctly.

You basically find this sentence for Class#getInterfaces() and Class#getGenericInterfaces() "If this object represents a class, the return value is an array containing objects representing all interfaces implemented by the class."

The problem is that wording of "all". When I look at for example AbstractList, then all means to me more than just List (which is what is returned for AbstractList.class.getInterfaces()).

Furthermore, since the wording is so equal you would assume that getInterfaces() and getGenericInterfaces() will always return the same interfaces, in the same order, same length, only one generified, the other not. But this is only true for classes produced by the java compiler. getInterfaces seems to read what is produced from "implements part" in bytecode, while getGenericinterfaces uses the signature. There seems to be nothing forbidding a different order or even a different number.

The example, that did bring me to this is scala.runtime.AbstractPartialFunction from Scala 2.10.2 (other versions I did not check). While the implements part says only PartialFunction, the generics signature contains Function1 as well. Since PartialFunction implements Function1 there should be no real problem with that, unless you wrote code like me, that did depend on the two methods returning more or less the same.

While much shorter the javadoc used in Android is for me much more clear: http://developer.android.com/reference/java/lang/Class.html#getInterfaces%28%29 """ Returns an array of Class objects that match the interfaces in the implements declaration of the class represented by this Class. The order of the elements in the array is identical to the order in the original class declaration. If the class does not implement any interfaces, an empty array is returned. """

I won't say this will prevent the mistake I made, but at least it will prevent the assumption all interfaces are to be shown here.

All in all I find it quite difficult to phrase this to not awake assumptions like that, without especially mentioning it. But anyway... should the javadoc be changed?

bye Jochen

More information about the core-libs-dev mailing list