Java: Clarify that RefType qualified name can include type parameters

[Marcono1234]

Description of the issue
The JLS defines "fully qualified name" as:

The fully qualified name of a top level class or top level interface that is declared in a named package consists of the fully qualified name of the package, followed by ".", followed by the simple name of the class or interface.
[...]
The fully qualified name of the interface Enumeration, which is defined in the package java.util, is "java.util.Enumeration".
[...]
A local class or anonymous class does not have a fully qualified name.

Source: JLS §6.7

So the qualified name does not include type parameters.

However, QL's

• RefType.getQualifiedName
• RefType.hasQualifiedName

can contain type parameters and even type arguments and return results for local and anonymous classes.
This is not obvious from the documentation of these methods (except when looking at AnonymousClass::getQualifiedName, though a caller of RefType::getQualifiedName likely does not do that) so it would be good to add that.

Example query:

import java

from MethodAccess call
where
  call.getReceiverType().hasQualifiedName("java.util", "List<String>")
select call

[aschackmull]

In the QL representation we don't distinguish "classes" and "class types", and even the JLS tends to be somewhat hand-wavy around this distinction (see e.g. https://docs.oracle.com/javase/specs/jls/se14/html/jls-4.html#jls-4.12.6 where it's stated that "We often use the term type to refer to either a class or an interface" even though previous sections have had clear distinctions between "class" and "class type"), and as long as generics aren't involved the distinction isn't really important. Cleaning this and related issues up in a nice way is probably a can-of-worms if it means adding this distinction.

Now in QL, our RefType includes parameterized types arising from generic class definitions and at the same time attempts to include classes as a subset of RefType (because we don't distinguish classes and class types). This means that for the subset of RefType that represents the mixed concept of class/interface and class/interface type you'll get qualified names matching the JLS, and for the remaining types we include the type parameters.

A related can-of-worms is Method, since that includes both source definitions, i.e. class members, and members of parameterized types. And for this distinction I don't even know if we have good names to distinguish the two concepts. (There's a QL class SrcMethod, but really I'd like Method to be that class, and the current collection of entities called Method to be named something else, but I don't know what would be a good name here.)

[Marcono1234]

Thanks for this insight!

Maybe leaving the documentation as is would be fine then. I used something like getAnAncestor().hasQualifiedName("java.util", "Map") and was confused why it did not return any results, though I should have included a call to getErasure().

Additionally I thought Eclipse's "Copy Qualified Name" action does not copy type parameters either which would by another reason why a user might expect different behavior from the QL predicates, though I checked it now and I was wrong. The action result does include type paramters if you use the action on the type definition (though not on usages of that type?).

So feel free to close this issue.

[aschackmull]

Note that for identifying maps and collections we have some library classes to help out with that. In particular MapType in Maps.qll and CollectionType in Collections.qll.