org.aspectj/docs/release/README-1.9.20.adoc

= AspectJ 1.9.20

:doctype: book
:leveloffset: +1

= AspectJ 1.9.20.1

_© Copyright 2023 Contributors. All rights reserved._

_Release info: 1.9.20.1 available 04-Sep-2023_

This is a bugfix release for 1.9.20, fixing two problems:

* https://github.com/eclipse-aspectj/aspectj/issues/257[Regression bug 257] introduced in 1.9.20 would match negated
  type patterns like `!void` or `!String[]` incorrectly.
* https://github.com/spring-projects/spring-framework/issues/27761[Spring issue 27761] describes a problem where
  AspectJ, when used by Spring AOP, in rare cases falsely considered bridge methods for overridden generic methods for
  matching, leading to falsely negative matching results. See also
  https://github.com/eclipse-aspectj/aspectj/issues/256[AspectJ tracker issue 256]).

The list of issues addressed for 1.9.20.1 can be found
https://github.com/eclipse-aspectj/aspectj/issues?q=is%3Aissue+is%3Aclosed++milestone%3A1.9.20.1[here].

= AspectJ 1.9.20

_© Copyright 2023 Contributors. All rights reserved._

_Release info: 1.9.20 available 16-Aug-2023_

Please note that Bugzilla for issue management is deprecated and new issues should be filed as
https://github.com/eclipse-aspectj/aspectj/issues/new[GitHub issues]. The list of issues addressed for 1.9.20 can be found
here:

* https://github.com/eclipse-aspectj/aspectj/issues?q=is%3Aissue+is%3Aclosed++milestone%3A1.9.20[GitHub 1.9.20]
* https://github.com/eclipse-aspectj/aspectj/issues?q=is%3Aissue+is%3Aclosed++milestone%3A1.9.20.1[GitHub 1.9.20.1]
* https://bugs.eclipse.org/bugs/buglist.cgi?bug_status=RESOLVED&bug_status=VERIFIED&bug_status=CLOSED&f0=OP&f1=OP&f3=CP&f4=CP&j1=OR&list_id=16866879&product=AspectJ&query_format=advanced&target_milestone=1.9.20[Bugzilla 1.9.20]

== New features

AspectJ 1.9.20 supports https://openjdk.java.net/projects/jdk/20/[Java 20] and its final, preview and incubator
features, such as:

* Record patterns (preview)
* Virtual threads (preview)
* Pattern matching for `switch` (preview 3)
* Structured concurrency (incubator)

Please note, that the upstream Eclipse Java Compiler (ECJ), which the AspectJ Compiler (AJC) is a fork of, still has
some open issues concerning Java 20 preview feature support, see the list in
https://github.com/eclipse-aspectj/aspectj/issues/184#issuecomment-1272254940[this comment]. AJC therefore inherits the same
problems for the specific cases described in the linked issues.

== Improvements

* Since Java 9 and the introduction of the Java Module System, the upstream Eclipse Java Compiler (ECJ) and Eclipse Java
  Development Tools (JDT) had gone through some internal changes, enabling both the compiler and the IDE to handle new
  Java language features. In AspectJ, some of those internal changes have not been properly upgraded for quite a while,
  but this is now fixed. However, it might *require you to recompile your aspects and projects/classes using them.*
  Otherwise, you might get problems in Eclipse IDE or under certain circumstances even when running newly compiled
  aspects in older AspectJ versions and vice versa. You are on the safe side if you simply rebuild your projects. We are
  sorry for the inconvenience, but we have to follow upstream ECJ and JDT changes.
* Along with fixing https://github.com/eclipse-aspectj/aspectj/issues/24[GitHub bug 24], the syntax for array type
  matching has been improved considerably. You can find some examples
  https://github.com/eclipse-aspectj/aspectj/tree/master/tests/bugs1920/github_24[here].

== Code examples

You can find some sample code in the AspectJ test suite under the respective AspectJ version in which the features were
first supported (possibly as JVM preview features):

* https://github.com/eclipse-aspectj/aspectj/tree/master/tests/features198/java17[Pattern matching for switch (preview 1)]
* https://github.com/eclipse-aspectj/aspectj/tree/master/tests/features199/java18[Pattern matching for switch (preview 2)]
* https://github.com/eclipse-aspectj/aspectj/tree/master/tests/features1919/java19[Pattern matching for switch (preview 3),
  record patterns (preview 1)]
* https://github.com/eclipse-aspectj/aspectj/tree/master/tests/features1920/java20[Pattern matching for switch (preview 4),
  record patterns (preview 2)]
* Please note that presently there is no specific sample code for virtual threads and structured concurrency in the
  AspectJ code base, because these are just new APIs, no Java language features. You can find sample code for these
  concurrency features elsewhere, e.g. in the corresponding JEPs. In AspectJ, they should just work transparently like
  any other Java API.

== Other changes and bug fixes

* About a dozen bugs have been fixed, some of them quite old. See "list of issues addressed" further above and follow
  the link to GitHub to find out if your issue is among them.

== AspectJ usage hints

=== AspectJ compiler build system requirements

Since 1.9.8, the AspectJ compiler `ajc` (contained in the `aspectjtools` library) no longer works on JDKs 8 to 10. The
minimum compile-time requirement is now JDK 11 due to upstream changes in the Eclipse Java Compiler (subset of JDT
Core), which AspectJ is a fork of. You can still compile to legacy target versions as low as Java 1.3 when compiling
plain Java code or using plain Java ITD constructs which do not require the AspectJ runtime `aspectjrt`, but the
compiler itself needs JDK 11+. Just like in previous AspectJ versions, both the runtime `aspectjrt` and the load-time
weaver `aspectjweaver` still only require JRE 8+.

=== Use LTW on Java 16+

Please note that if you want to use load-time weaving on Java 16+, the weaving agent collides with
https://openjdk.java.net/jeps/396[JEP 396 (Strongly Encapsulate JDK Internals by Default)]. Therefore, you need to set
the JVM parameter `--add-opens java.base/java.lang=ALL-UNNAMED` in order to enable aspect weaving. This is due to the
fact that the weaver uses internal APIs for which we have not found an adequate replacement yet when defining classes
in different classloaders.

=== Compile with Java preview features

For features marked as preview on a given JDK, you need to compile with `ajc --enable-preview` and run with
`java --enable-preview` on that JDK.

Please note, that you cannot run code compiled with preview features on any other JDK than the one used for compilation.
For example, records compiled with preview on JDK 15 cannot be used on JDK 16 without recompilation. This is a JVM
limitation unrelated to AspectJ. Also, e.g. sealed classes are preview-1 on JDK 15 and preview-2 on JDK 16. You still
need to recompile, no matter what.