https://github.com/gunnarmorling/signature-check-jlink-plugin
A proof-of-concept for a jlink plug-in for detecting API signature mismatches between modules
https://github.com/gunnarmorling/signature-check-jlink-plugin
java jlink jlink-image jpms
Last synced: 29 days ago
JSON representation
A proof-of-concept for a jlink plug-in for detecting API signature mismatches between modules
- Host: GitHub
- URL: https://github.com/gunnarmorling/signature-check-jlink-plugin
- Owner: gunnarmorling
- License: apache-2.0
- Created: 2020-12-27T11:26:35.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2021-01-16T11:48:03.000Z (over 4 years ago)
- Last Synced: 2025-02-12T08:21:57.941Z (3 months ago)
- Topics: java, jlink, jlink-image, jpms
- Language: Java
- Homepage:
- Size: 18.6 KB
- Stars: 1
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# API Signature Check jlink Plug-in
A proof-of-concept for a plug-in for the jlink tool which detects differences between the API exposed by a module added to a custom Java runtime image and other modules calling this API.
This helps to prevent ``NoSuchMethodError``s at application runtime,
caused by using different versions of a module at compile time vs. runtime.
Note: The jlink plug-in API is currently not officially supported nor exposed by the _jdk.jlink_ module.
Hence [some trickery](https://in.relation.to/2017/12/12/exploring-jlink-plugin-api-in-java-9/#trick-2-the-java-agent) is required for compiling and using this plug-in.
## Usage
Build the project as described below. Then create a custom runtime image for the _example_ modules:
```shell
$JAVA_HOME/bin/jlink \
-J-javaagent:agent/target/signature-check-jlink-plugin-registration-agent-1.0-SNAPSHOT.jar \
-J--module-path=plugin/target/signature-check-jlink-plugin-1.0-SNAPSHOT.jar:/Users/gunnar/.m2/repository/org/codehaus/mojo/animal-sniffer/1.19/animal-sniffer-1.19.jar:/Users/gunnar/.m2/repository/org/ow2/asm/asm/9.0/asm-9.0.jar \
-J--add-modules=dev.morling.jlink.plugins.sigcheck \
--module-path=$JAVA_HOME/jmods/:example/customer-2/target/customer-2-1.0-SNAPSHOT.jar:example/order/target/order-1.0-SNAPSHOT.jar \
--add-modules=com.example.order \
--output=target/runtime-image \
--check-signatures
```
The `order` module is compiled against the `customer-1` module.
The runtime image is created using the `customer-2` module though, which contains a breaking API change.
When not using this plug-in, this would result in a `NoSuchMethodError` at runtime.
With this plug-in, the mismatching API signature will be detected at link time and raised as an error:
```shell
[ERROR] /com.example.order/com/example/order/OrderService.class:13: Undefined reference: void com.example.customer.CustomerService.doIt(String)
Error: Signature violations, check the logs
```
## Implementation
This is a very basic PoC, using Animal Sniffer internally for creating and comparing API signatures.
Only a subset of API changes will be spotted, e.g. an added abstract method to a superclass or interface would not be detected and still result in an error at runtime.
## Build
This project requires OpenJDK 11 or later for its build.
Apache Maven is used for the build.
Run the following to build the project:
```shell
mvn clean install
```
## License
This code base is available under the Apache License, version 2.