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

= AspectJ 1.9.8

_© Copyright 2022 Contributors. All rights reserved._

_Release info: 1.9.8 available 11-Feb-2022_

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.8 can be found
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.8[here for Bugzilla] and
https://github.com/eclipse-aspectj/aspectj/issues?q=is%3Aissue+is%3Aclosed++milestone%3A1.9.8[here for GitHub issues].

== New features

AspectJ 1.9.8 supports https://openjdk.java.net/projects/jdk/17/[Java 17] and its final and review features, such as:

* Sealed classes (final in Java 17, previews in Java 15, 16 and AspectJ 1.9.7)
* Pattern matching for `switch`

== Improvements

The `--release N` compiler option for correct cross-compilation to previous JDK bytecode + API versions is now supported
by AJC. Previously, the option existed (inherited by ECJ) but did not work correctly.

The following new properties can improve performance, e.g. Spring start-up time:

* `org.aspectj.apache.bcel.useSingleRepositoryInstance`
* `org.aspectj.apache.bcel.useUnavailableClassesCache`
* `org.aspectj.apache.bcel.ignoreCacheClearRequests`

For now, they all default to `false` for backward compatibility. This might change in a future Aspect release, if user
feedback is positive and no negative side effects are found. Please try using them as much as you can and report back
questions (to the AspectJ users mailing list) or problems (as a GitHub issue), if any. Thanks to Stefan Starke for his
contribution. See also https://github.com/eclipse-aspectj/aspectj/pull/37[PR #37].

== 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/compiler_release[Cross-compilation to legacy JDK]:
  An example class which only works correctly on JDK 8 when compiled with `--release 8` due to API changes in
  the JDK. Simply `-source 8 -target 8` would not be enough in this case.
* https://github.com/eclipse-aspectj/aspectj/tree/master/tests/features198/java17[Pattern matching for `switch`]

== Other changes and bug fixes

* 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+.
* Document build profiles and properties in _docs/developer/BUILD.md_
* Add a guide for setting up an AspectJ development environment in _docs/developer/IDE.md_
* Fix https://github.com/eclipse-aspectj/aspectj/issues/105[issue #105]: Compilation fails when using an aspect library via
  `-aspectpath` in combination with introducing an annotation via ITD. This was broken since version 1.9.5 and fixed in
  1.9.8.RC3.
* Fix https://github.com/eclipse-aspectj/aspectj/issues/68[issue #68]: Correctly process class files containing
  https://openjdk.java.net/jeps/309[dynamic class-file constants (JEP 309)], which were introduced in Java 11 and broken
  in AspectJ ever since their introduction in 1.9.2. Java itself currently does not use "condy" and neither do other
  widespread JVM languages. Byte code engineering libraries like ASM or Byte Buddy and some instrumentation tools like
  JaCoCo can however produce condy code. Therefore, in order to create a regression test, we actually had to
  https://github.com/eclipse-aspectj/aspectj/blob/de63b63d/tests/bugs198/github_68/Generator.java#L50-L61[craft a condy
  class with ASM].
* Thanks to Andrey Turbanov for several clean code contributions and to Dmitry Mikhaylov for fixing a potential
  concurrency problem.

== AspectJ usage hints

=== 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.

**Update:** As of AspectJ 1.9.21.1, `--add-opens` is no longer necessary. Please upgrade, if it bothers you too much.

=== 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.