= Supported Utilities in Extensions

The `junit-platform-commons` artifact provides _maintained_ utilities for working with
annotations, classes, reflection, classpath scanning, and conversion tasks. These
utilities can be found in the `{junit-platform-support-package}` and its subpackages.
`TestEngine` and `Extension` authors are encouraged to use these supported utilities in
order to align with the behavior of the JUnit Platform and JUnit Jupiter.

[[annotations]]
== Annotation Support

`AnnotationSupport` provides static utility methods that operate on annotated elements
(e.g., packages, annotations, classes, interfaces, constructors, methods, and fields).
These include methods to check whether an element is annotated or meta-annotated with a
particular annotation, to search for specific annotations, and to find annotated methods
and fields in a class or interface. Some of these methods search on implemented
interfaces and within class hierarchies to find annotations. Consult the Javadoc for
`{AnnotationSupport}` for further details.

NOTE: The `isAnnotated()` methods do not find repeatable annotations. To check for repeatable annotations,
use one of the `findRepeatableAnnotations()` methods and verify that the returned list is not empty.

NOTE: See also: <<search-semantics>>

[[classes]]
== Class Support

`ClassSupport` provides static utility methods for working with classes (i.e., instances
of `java.lang.Class`). Consult the Javadoc for `{ClassSupport}` for further details.

[[reflection]]
== Reflection Support

`ReflectionSupport` provides static utility methods that augment the standard JDK
reflection and class-loading mechanisms. These include methods to scan the classpath in
search of classes matching specified predicates, to load and create new instances of a
class, and to find and invoke methods. Some of these methods traverse class hierarchies
to locate matching methods. Consult the Javadoc for `{ReflectionSupport}` for further
details.

NOTE: See also: <<search-semantics>>

[[modifier]]
== Modifier Support

`ModifierSupport` provides static utility methods for working with member and class
modifiers -- for example, to determine if a member is declared as `public`, `private`,
`abstract`, `static`, etc. Consult the Javadoc for `{ModifierSupport}` for further
details.

[[conversion]]
== Conversion Support

`ConversionSupport` (in the `org.junit.platform.commons.support.conversion` package)
provides support for converting from strings to primitive types and their corresponding
wrapper types, date and time types from the `java.time package`, and some additional
common Java types such as `File`, `BigDecimal`, `BigInteger`, `Currency`, `Locale`, `URI`,
`URL`, `UUID`, etc. Consult the Javadoc for `{ConversionSupport}` for further details.

[[search-semantics]]
== Field and Method Search Semantics

Various methods in `AnnotationSupport` and `ReflectionSupport` use search algorithms that
traverse type hierarchies to locate matching fields and methods – for example,
`AnnotationSupport.findAnnotatedFields(...)`, `ReflectionSupport.findMethods(...)`, etc.

As of JUnit 5.11 (JUnit Platform 1.11), field and method search algorithms adhere to
standard Java semantics regarding whether a given field or method is visible or overridden
according to the rules of the Java language.

Prior to JUnit 5.11, the field and method search algorithms applied what we now refer to
as "legacy semantics". Legacy semantics consider fields and methods to be _hidden_,
_shadowed_, or _superseded_ by fields and methods in super types (superclasses or
interfaces) based solely on the field's name or the method's signature, disregarding the
actual Java language semantics for visibility and the rules that determine if one method
overrides another method.

Although the JUnit team recommends the use of the standard search semantics, developers
may optionally revert to the legacy semantics via the
`junit.platform.reflection.search.useLegacySemantics` JVM system property.

For example, to enable legacy search semantics for fields and methods, you can start your
JVM with the following system property.

`-Djunit.platform.reflection.search.useLegacySemantics=true`

NOTE: Due to the low-level nature of the feature, the
`junit.platform.reflection.search.useLegacySemantics` flag can only be set via a JVM
system property. It cannot be set via a xref:running-tests/configuration-parameters.adoc[configuration
parameter].
