https://github.com/toolfactory/jvm-driver
A driver to allow deep interaction with the JVM without any restrictions
https://github.com/toolfactory/jvm-driver
classloader java jvm reflection
Last synced: 10 months ago
JSON representation
A driver to allow deep interaction with the JVM without any restrictions
- Host: GitHub
- URL: https://github.com/toolfactory/jvm-driver
- Owner: toolfactory
- License: mit
- Created: 2021-08-23T08:55:16.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2024-11-12T11:11:57.000Z (about 1 year ago)
- Last Synced: 2025-03-31T06:06:15.479Z (10 months ago)
- Topics: classloader, java, jvm, reflection
- Language: Java
- Homepage: https://github.com/toolfactory
- Size: 3.69 MB
- Stars: 53
- Watchers: 2
- Forks: 4
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# ToolFactory JVM Driver [](https://twitter.com/intent/tweet?text=%40ToolFactory_fw%20JVM%20driver%2C%20a%20%23driver%20to%20allow%20deep%20interaction%20with%20the%20JVM%20without%20any%20restrictions%20%28works%20on%20%23Java7%20%23Java8%20%23Java9%20%23Java10%20%23Java11%20%23Java12%20%23Java13%20%23Java14%20%23Java15%20%23Java16%20%23Java17%20%23Java18%20%23Java19%20%23Java20%20%23Java21%20%23Java22%29&url=https://toolfactory.github.io/jvm-driver/)
[](https://maven-badges.herokuapp.com/maven-central/io.github.toolfactory/jvm-driver/)
[](https://github.com/toolfactory/jvm-driver/blob/main/LICENSE)
[](https://github.com/toolfactory/jvm-driver/actions/runs/8919531180)
[-blueviolet)](https://github.com/toolfactory/jvm-driver/actions/runs/8919531180)
[](https://github.com/toolfactory/jvm-driver/issues)
[](https://github.com/toolfactory/jvm-driver/issues?q=is%3Aissue+is%3Aclosed)
[](https://github.com/toolfactory/jvm-driver/network/dependents)
Extracted from [**Burningwave Core 8**](https://github.com/burningwave/core/releases/tag/core-8.22.0), fully refactored and with an **extensible architecture** the JVM Driver allows a deep interaction with the JVM **without any restrictions**.
To include ToolFactory JVM Driver in your projects simply use with **Apache Maven**:
```xml
io.github.toolfactory
jvm-driver
9.7.1
```
### Requiring the ToolFactory JVM Driver module
To use ToolFactory JMV Driver as a Java module, add the following to your `module-info.java`:
```java
//Mandatory if you use the dynamic, hybrid or native driver
requires io.github.toolfactory.narcissus;
//Mandatory if you use the default, dynamic or hybrid driver
requires jdk.unsupported;
requires io.github.toolfactory.jvm;
```
## Overview
There are four kinds of driver:
* the **default driver** completely based on Java api
* the **dynamic driver** that extends the default driver and uses a JNI function only if a Java based function offered by the default driver cannot be initialized
* the **hybrid driver** that extends the default driver and uses some JNI functions only when run on JVM 17 and later
* the **native driver** that extends the hybrid driver and uses JNI functions more consistently regardless of the Java version it is running on
By default all JNI methods used by the dynamic, hybrid and native driver are supplied by [**Narcissus**](https://toolfactory.github.io/narcissus/) that works on the following system configurations:
* Windows (x86, x64)
* Linux (x86, x64)
* MacOs (x64)
It is also possible to replace the Narcissus JNI engine with [another fast JNI engine](https://github.com/toolfactory/narcissus/discussions/11): the one included in the [**Burningwave JVM Driver**](https://burningwave.github.io/jvm-driver/).
## Usage
To create a driver instance you should use this code:
```java
io.github.toolfactory.jvm.Driver driver = io.github.toolfactory.jvm.Driver.getNew();
```
The driver type returned by the method `io.github.toolfactory.jvm.Driver.Factory.getNew()` is **the first driver that can be initialized among the default, hybrid and native drivers respectively**.
If you need to create a specific driver type you should use:
* this code to create a default driver instance:
```java
io.github.toolfactory.jvm.Driver driver = io.github.toolfactory.jvm.Driver.Factory.getNewDefault();
```
* this code to create a dynamic driver instance:
```java
io.github.toolfactory.jvm.Driver driver = io.github.toolfactory.jvm.Driver.Factory.getNewDynamic();
```
* this code to create an hybrid driver instance:
```java
io.github.toolfactory.jvm.Driver driver = io.github.toolfactory.jvm.Driver.Factory.getNewHybrid();
```
* this code to create a native driver instance:
```java
io.github.toolfactory.jvm.Driver driver = io.github.toolfactory.jvm.Driver.Factory.getNewNative();
```
Each functionality offered by the driver is **initialized in deferred way** at the first call if the driver is not obtained through the method `io.github.toolfactory.jvm.Driver.getNew()`. However, it is possible to initialize all of the functionalities at once by calling the method `Driver.init()`.
The methods exposed by the Driver interface are the following:
```java
public D init();
public T allocateInstance(Class> cls);
// Return a ClassLoaderDelegate or the input itself if the input is a
// BuiltinClassLoader or null if the JVM version is less than 9
public ClassLoader convertToBuiltinClassLoader(ClassLoader classLoader);
public Class> defineHookClass(Class> clientClass, byte[] byteCode);
public Class> getBuiltinClassLoaderClass();
public Class> getClassLoaderDelegateClass();
public Class> getClassByName(String className, Boolean initialize, ClassLoader classLoader, Class> caller);
public MethodHandles.Lookup getConsulter(Class> cls);
public Constructor[] getDeclaredConstructors(Class cls);
public Field[] getDeclaredFields(Class> cls);
public Method[] getDeclaredMethods(Class> cls);
public T getFieldValue(Object target, Field field);
public Package getPackage(ClassLoader classLoader, String packageName);
public Collection getResources(String resourceRelativePath, boolean findFirst, ClassLoader... classLoaders);
public Collection getResources(String resourceRelativePath, boolean findFirst, Collection classLoaders);
public T invoke(Object target, Method method, Object[] params);
public boolean isBuiltinClassLoader(ClassLoader classLoader);
public boolean isClassLoaderDelegate(ClassLoader classLoader);
public T newInstance(Constructor ctor, Object[] params);
public CleanableSupplier>> getLoadedClassesRetriever(ClassLoader classLoader);
public Map retrieveLoadedPackages(ClassLoader classLoader);
public void setAccessible(AccessibleObject object, boolean flag);
public void setFieldValue(Object target, Field field, Object value);
public void stop(Thread thread);
public T throwException(String message, Object... placeHolderReplacements);
public T throwException(Throwable exception);
```
In the [test folder](https://github.com/toolfactory/jvm-driver/tree/main/java/src/test/java/io/github/toolfactory/util) is also present a little utility class named [`io.github.toolfactory.util.Reflection`](https://github.com/toolfactory/jvm-driver/blob/main/java/src/test/java/io/github/toolfactory/util/Reflection.java) that can be copied into your project and that can be instantiated through the factory methods exposed by the inner static class `io.github.toolfactory.util.Reflection.Factory`:
```java
public static Reflection getNew();
public static Reflection getNewWithDefaultDriver();
public static Reflection getNewWithDynamicDriver();
public static Reflection getNewWithHybridDriver();
public static Reflection getNewWithNativeDriver();
public static Reflection getNewWith(Driver driver);
```
The methods exposed by the `io.github.toolfactory.util.Reflection` component are the following:
```java
public Driver getDriver();
public Collection getDeclaredMethods(Class> cls);
public Collection getAllMethods(Class> cls);
public T getFieldValue(Object target, Field field);
public void setFieldValue(Object target, Field field, Object value);
public Field getDeclaredField(Class> cls, String name);
public Collection getDeclaredFields(Class> cls);
public Collection getAllFields(Class> cls);
public Collection> getDeclaredConstructors(Class> cls);
public Collection> getAllConstructors(Class> cls);
```
## Compilation requirements
**A JDK version 9 or higher is required to compile the project**.
# Ask for assistance
**For assistance you can**:
* [open a discussion](https://github.com/toolfactory/jvm-driver/discussions) here on GitHub
* [report a bug](https://github.com/toolfactory/jvm-driver/issues) here on GitHub
* ask on [Stack Overflow](https://stackoverflow.com/questions/ask)