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

= AspectJ 1.9.21
:doctype: book
:leveloffset: +1

// AspectJ_JDK_Update: Each a.b.c release needs a new release notes document. For a.b.c.d minors, the existing a.b.c
// document can be updated. After copying this document, remove the comment from the previous one.

The releases 1.9.21 and 1.9.21.1 are described together in this document.

= AspectJ 1.9.21.1

_© Copyright 2024 Contributors. All rights reserved._

_Release info: 1.9.21.1 available 14-Feb-2024_

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.21.1 can be
found here:

* https://github.com/eclipse-aspectj/aspectj/issues?q=is%3Aissue+is%3Aclosed++milestone%3A1.9.21.1[GitHub 1.9.21.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.21.1[Bugzilla 1.9.21.1]

== New features

AspectJ 1.9.21.1 is a maintenance release with no new language features, but important improvements and some bugfixes,
see below.

== Improvements

* **For load-time weaving (LTW) on JDK 16+, xref:#ltw_java_16[using `--add-opens`] is no longer necessary!** This solves
link:https://github.com/eclipse-aspectj/aspectj/issues/117[issue #117]. The additional JVM command-line option was
necessary for LTW on JRE 16+ in all AspectJ versions up to 1.9.21. Since AspectJ 1.9.21.1, the LTW agent uses an
alternative approach for defining new classes during weaving, which works without `--add-opens` - at least for now, i.e.
JDKs 8 to 21. There still is no canonical solution, because link:https://bugs.openjdk.org/browse/JDK-8200559[JDK-8200559]
is still unresolved since 2018.

* The **AspectJ documentation** is now written in **asciidoc** format and processed by the Asciidoctor toolchain.
Before, it was a mixture of DocBook XML and plain HTML files. While the content has not changed much, it now looks
fresher, is easier to read (also online when browsing the GitHub repository), navigate and maintain and also easy to
publish in different formats (multi-page HTML, single-page HTML, PDF). Those formats are also distributed on the website
and with the AspectJ installer. A content overhaul is also overdue, but not part of this change. It is still basically
the same: Everything up to AspectJ 1.5 is in the regular documentation. The changes since then can be extracted
incrementally from various release notes.

== Other changes and bugfixes

* Running the AspectJ Compiler on JDK < 17 no longer creates an `ajcore.*.txt` crash dump file, but prints "The AspectJ
compiler needs at least Java runtime 17". Fixes link:https://github.com/eclipse-aspectj/aspectj/issues/269[issue #269].

* The AspectJ weaver now plays nicer with parallel class loaders, e.g. jboss-modules in WildFly. Before, it would
sometimes return original instead of woven byte code. Fixes link:https://github.com/eclipse-aspectj/aspectj/issues/279[issue #279].

* An upstream refresh from JDT Core (Eclipse Java Compiler) fixes a little
link:https://github.com/eclipse-jdt/eclipse.jdt.core/issues/1719[bug in JDK 21 string templates].

= AspectJ 1.9.21

_© Copyright 2023 Contributors. All rights reserved._

_Release info: 1.9.21 available 11-Dec-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.21 can be
found here:

* https://github.com/eclipse-aspectj/aspectj/issues?q=is%3Aissue+is%3Aclosed++milestone%3A1.9.21[GitHub 1.9.21]
* 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.21[Bugzilla 1.9.21]

== New features

AspectJ 1.9.21 supports https://openjdk.java.net/projects/jdk/21/[Java 21], its final features and a subset of preview
features, such as:

* Record patterns
* Pattern matching for switch
* Virtual threads
* Sequenced collections
* Structured concurrency (preview)
* String templates (preview)
* Instance main methods (preview)

Unfortunately, even after holding back the AspectJ release for 3 months after JDK 21 general availability, waiting for
Eclipse JDT Core and the Eclipse Java Compiler (ECJ) to catch up with Java 21 language features, even with Java 21
officially supported in Eclipse 2023-12, some preview features are still unimplemented in ECJ:

* Unnamed classes (preview)
* Unnamed patterns and variables (preview)

As soon as these preview features are part of the upstream ECJ we depend on, we hope to publish another AspectJ release
to support them in the AspectJ Compiler (AJC), too.

== Improvements

* In https://github.com/eclipse-aspectj/aspectj/issues/266[GitHub issue 266], exception cause reporting has been
  improved in `ExtensibleURLClassLoader`. Thanks to Andy Russell (@euclio) for his contribution.

== Other changes and bug fixes

* No major bug fixes

== AspectJ usage hints

=== AspectJ compiler build system requirements

Since 1.9.21, the AspectJ compiler `ajc` (contained in the `aspectjtools` library) no longer works on JDKs 11 to 16. The
minimum compile-time requirement is now JDK 17 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 17+. Just like in previous AspectJ versions, both the runtime `aspectjrt` and the load-time
weaver `aspectjweaver` still only require JRE 8+.

Please note: If you run `ajc` on JDKs 11-16, you will probably see an error like `java.lang.NoSuchFieldError:
RELEASE_17`, and an _ajcore.*.txt_ dump file will be created, while running it on even older JDKs will rather yield an
`UnsupportedClassVersionError`. See https://github.com/eclipse-aspectj/aspectj/issues/269[GitHub issue 269] for more
details.

History: Since 1.9.8, the AspectJ compiler ajc needed JDK 11+, before then JDK 8+.

[[ltw_java_16]]
=== 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)] and related subsequent
JEPs. 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.