In a simple query, you specify what you want to be the result of the query by using the ^ in front of the name of the element. E.g. query

will return the java.lang.Object class.

In case you want to match more things (like for example a class and some method), you might want to use a different way of declaring what to match by the query.

Whoa, that’s a bit of a mouthful. But what can be seen there is that you can declare variables that match certain elements in the query (in the example above the %class and %method are variables "assigned" to the matching elements) and use them in the match statement (which needs to be the first statement in the query).

Btw. the above example will match the java.lang.Object class and any method with name beginning with and underscore that has any number of parameters and is present in any type (regardless of whether it is a class, interface, enum, etc).

This is the general principle. You can match different elements by visibility, annotation presence, contents, usage, etc.

For example:

will match all public classes (but not interfaces, enums or annotation types), while

will match the classes regardless of their visibility - all private, package private, protected and public classes will be matched.

If you want to constrain the matched types by their visibility, you can do so by using one of the public, protected, private or Classif’s own packageprivate qualifiers. The packageprivate modifier is required to distinguish between "any visibility", which in Classif is expressed by the lack of any visibility modifier, and "package private visibility" which is what Java assumes when there is on other visibility modifier.

There are also other modifiers supported on the types: static, final, abstract and strictfp, each as understood by your favorite Java compiler..

Some examples:

matches all final types in any package whose names end with "Impl".

matches all package private enums.

In addition to specifying single modifiers, you can also "or" multiple together like so:

will match all public or protected static final classes.

Finally, you can also negate the modifiers:

matches all classes that are static, not final and not public.

matches all types that are either not public or static.

You can match not only by annotation presence on an element, but also by basic checks on the attribute values.

Specifying an annotation again resembles the declarations in the Java source code.

Basic example:

will return all public classes annotated as JPA entities.

To find something that is not annotated by some annotation you can write:

which will find all types that are not annotated by the javax.persistence.Entity annotation but are annotated by the com.acme.MyAnno annotation.

To match by annotation attributes, you can write something like this:

which will match all JPA entities with an explicitly assigned name (this stems from the fact that the name attribute of the Entity annotation happens to have an empty string as its default value).

Notice that you can use more than just assignment when matching the attribute values. The allowed operators are: =, !=, >, >=, < or <=. Obviously the less/greater operators only make sense on the numeric attribute values.

When it comes to specifying the value of an attribute to match, there is again a couple of options. You can either specify the value as in the source code, e.g.

or you can try using regular expressions for matching strings:

which will match all JPA entity classes with an explicit name attribute which doesn’t end with "Private".

additionally, you can specify that you don’t actually care about the value using *.

Finally, you can check whether an annotation attribute has a value different from its default value like so:

This will match all JPA entity classes with an explicit name. Note that this is essentially the same as our first example above with the only difference being that you don’t have to know the default value.

The annotation attributes also support globbing. I.e. you can put a wildcard in place of a single or many attributes.

will match any type annotated with the @com.acme.Acme annotation with a single attribute specified.

will match any annotated with the @com.acme.Acme annotation with zero or more attributes of any name with any value.

Values can be replaced by a *, too, meaning, somewhat obviously, "any value". If you happen to match an array value, like for example:

you can use globbing of the values as well, as you probably have guessed from the provided example. The example will match any annotation type that is itself annotated with the @java.lang.annotation.Target annotation with the value attribute having the TYPE as the first element in its values, followed by zero or more other element types. Requiring the TYPE to be the first in the array is somewhat restrictive, so you could update it to read {, java.lang.annotation.ElementType.TYPE, } which would make the query match with TYPE on any position in the array.

In the above examples we were mostly using * in place of a type name. That is one of the special symbols supported by Classif. A single * stands for "any type in any package". Sometimes though we need to be more specific. That’s why Classif also supports full featured globbing of the fully qualified type names.

The single * is a special case put in place for convenience. In a normal case the fully qualified type names are globbed similarly to Ant path expressions.

• * stands for single part of the hierarchical name

• ** stands for any number of parts (0 to many) of the hierarchical name

• a sequence of characters stands for the single part of the hierarchical name with the same name

• the parts of the hierarchical name are separated by .

• instead of a sequence of characters, one can also use a regex enclosed in a pair of /.

Ok, that’s a little bit dense so let’s explore it on a couple of examples. Let’s suppose we want to match the type with the fully qualified name com.acme.util.StringUtils. Here is a couple of ways how to do it using the above described globbing features:

com.acme.util.StringUtils

The simplest thing to do is to simply write down all parts of the hierarchical fully qualified name in full.

com.*.util.*

In here we’re matching the acme and StringUtils parts of the name using a *. This expression would of course match any other class in any package with 3 hierarchical name parts first of which would be com and the third one util with the middle being anything. This expression would not match com.util.Clazz though because it has too few parts of the name as well as it would not match com.acme.util.internal.Misc because that has too many parts of the fully qualified name.

**.StringUtils

This expression will match a class called StringUtils located in any package no matter how deep the hierarchy of the package name. Contrast that to *.StringUtils which would only match the class StringUtils in packages with a single part (i.e. the package name without any dots in them). Also notice that the ** doesn’t match just the packages. It merely matches parts of the hierarchical name, so if the class StringUtils was an inner class of another class (of any name, in this concrete example) it would be matched also.

com.**.StringUtils

Similar to the above example but showing that you can put the ** wildcard in any place of the hierarchical name.

**./.*Utils/

In this example we’re using a regular expression .*Utils to match the class name and the ** wildcard to match a package of any depth.

Note	The regular expression always matches only a single part of the hierarchical name.

The whole name can further be negated:

would return all types that are not from the java.lang package or any of its sub-packages.

Types can of course be parameterized. To match types by their type parameters, Classif has you covered, of course.

Let’s go through some examples of why conflating the wildcards and type variables is kinda ok for a tool like Classif and also to explain how to use the matching by type parameters.

This simple example will match any type with any name that extends Collection<Serializable>. The type may or may not be parameterized itself (we don’t declare any requirements on the type variables so they’re not considered in the match).

The above declaration will match types like:

but will NOT match:

That’s because we’re matching for a concrete type parameter and we’re not checking any of its qualities. So for Classif, Collection<Serializable> is just different from Collection<String> (as is for Java compiler, too, actually).

Another example:

This will match any type with a single type parameter that extends Serializable (notice that we don’t specify any "name" of the type pamareter, we just use ?).

This will match types declared like this for example:

But it will NOT match a type declared like this (however such declaration is silly):

because the type variable bounds do not match (even though String implements Serializable). To match both Serializator and StringSerializator (and any other type like them), you’d need to write:

Now if you for example wanted to match all types with a single type parameter no matter their type or anything, you can use Classif globbing:

This will match any type that extends Collection and it doesn’t matter if the type parameter of the collection is a concrete type or a type variable.

You can also use globbing for saying "I don’t care about type parameters":

This says, "find me all types that for some silly reasons require their type parameters to be arrays (of any type)". The ** before and after are saying that any other type parameters (if any at all) may precede or succeed the array-requiring type parameter.

Often you will want to match a type by its "contents". I.e. what fields and methods are declared in it. Taking inspiration from the regular Java syntax, Classif can express such requirements like this:

This would match any class ending in "Util" in any package that happens to have a public constructor with any number of arguments (0 or more). This is usually considered a code smell because utility classes usually only contain static helper methods and therefore should not usually be instantiated.

If the type structure provider connected to Classif supports it (by default, Classif doesn’t provide any), the queries can also match types by their usage in other classes/methods/fields declarations (not in the code of the methods).

For example, to find all types used in declarations of another type, you could write:

If you haven’t specified the directly before usedby the search for usages would be recursive.

A more useful example of this could be:

If we had @Stable and @Unstable annotations that would mark types in the codebase as stable or unstable parts of the API, the above would match all the types, fields or methods from the stable API that use some unstable API. Note that because we haven’t declared directly uses but merely uses, the search is performed recursively.

You now may wonder what exactly is matched by type *;. Only top level types or also inner classes? The answer is that it depends :) By default this would match all types, top-level and inner. If on the other hand you want to really only match top-level types, you need to tell Classif about it like so:

The #strictHierarchy is a "pragma" that tells Classif to consider the hierarchy precisely. type * {} will only ever match top-level types, because it itself is a top-level declaration.

This takes into account the structure of the types, of course. If you for example wanted to find all types that have some inner type, you could write:

Without the #strictHierarchy pragma, this would match all types that have an inner class, regardless of whether they themselves are top-level or inner. With the pragma, it would only return top-level types with an inner class.

Similarly to types, methods, too, can be queried by the declared annotations.

If you wanted to convert all method-based JPA definitions to field-based definitions, because your project policy dictates so, you could find all the violators like this:

The above query could be rephrased as "In all types, look for any method with any number of parameters that is annotated by an annotation from the javax.persistence package.

As with types, Classif supports specifying the required annotation attributes.

This is very much the same as with types except the fact that method names are simple identifiers and don’t contain any hierarchy. It therefore doesn’t make sense to use the ** glob to match them.

The method names can either be spelled out in full, matched by the * glob or matched using a regular expression:

This would match any type that would have a method called namedMethod that would have no parameters, in addition the type would also have a method of any name with a single parameter of type int and finally the type would have a method with any number of parameters and a name starting with __.

You may have noticed that in all the examples above, the methods we were looking for lacked any information about their return type. In accordance with the Classif principles, we didn’t care about the return type and therefore we didn’t declare any.

If you wanted to match methods based on the return type though, you could certainly do so.

This could be rephrased as "find all setters that don’t return void". We see a couple of things here. First we don’t specify the visibility, so it is not considered. Then we specify the return type (as we would in Java code) but we negate it. Then we use a regular expression to match the name of the method. Finally we require that the method has a single parameter of any type.

We’ve already seen examples of matching by method parameters in the sections above. That’s because Classif can only distinguish a field declaration from a method declaration by the presence of the parameters on the method (this is the only violation of the "what’s not specified is not considered" principle).

Therefore you always need to specify what kind of parameters a method should have. The parameters are matched using a glob, so you can either spell out their type names, use for matching any type or * to match any number of parameters.

Of course, you can also match methods based on the presence of annotations on the method parameters.

This will find all the CDI event handlers. In any type, look for methods with any name that have a single parameter of any type that is annotated by the @Observes annotation.

As you can declare what exceptions can be thrown from a java method, you can also match the methods using the thrown exceptions with Classif.

This will return all the methods in all types that are declared to throw any exception that inherits from RuntimeException. Methods don’t need to declare that and so this may be flagged in some way.

Similarly to types, methods can also be matched by what types they use. This can either be a direct usage (e.g. the return type of a method, one of its parameters, …​) or indirect usage as well. The semantics of what determines an indirect usage of a type is left to the structure provider that is supplied to Classif.

This will return all the methods that somehow reference the sun.misc.Unsafe class. Again the semantics of what is a use of a type is left to the structure provider.

You can also match all methods that override some other method.

This will return all methods in all types that override some other method from any supertype.

This will return all types that declare some methods that override methods declared in any type annotated by the @com.acme.DoNotOverride annotation. Yes, this is a contrived example.. :)

If you want want to for example find all annotation types that declare some attributes without a default value, you could:

It is also possible to match by certain default value:

This will return all the annotation attributes of any annotation type that have a default value which is an array with 2 or more elements.

This is very much the same as in the case of types.