Skip to content

A driver to allow deep interaction with the JVM without any restrictions

License

Notifications You must be signed in to change notification settings

burningwave/jvm-driver

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Burningwave JVM Driver Tweet

Burningwave-logo.png

Maven Central with version prefix filter GitHub

Platforms

Supported JVM

GitHub open issues GitHub closed issues

Artifact downloads Repository dependents HitCount

A driver derived from ToolFactory JVM Driver with a fully extensible architecture and with a custom and extremely optimized JNI engine to allow deep interaction with the JVM without any restrictions.


To include Burningwave JVM Driver in your projects simply use with Apache Maven:

<dependency>
    <groupId>org.burningwave</groupId>
    <artifactId>jvm-driver</artifactId>
    <version>8.16.1</version>
</dependency>	

Requiring the Burningwave JVM Driver module

To use Burningwave JMV Driver as a Java module, add the following to your module-info.java:

//Mandatory if you use the default, dynamic or hybrid driver
requires jdk.unsupported;

requires org.burningwave.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

All JNI methods used by the dynamic, hybrid and native driver are supplied by a custom and highly optimized JNI engine written in C++ that works on the following system configurations:

  • Windows x86/x64
  • Linux x86/x64
  • MacOs x64
  • aarch64 (needs testing)

Usage

To create a driver instance you should use this code:

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:
io.github.toolfactory.jvm.Driver driver = io.github.toolfactory.jvm.Driver.Factory.getNewDefault();
  • this code to create a dynamic driver instance:
io.github.toolfactory.jvm.Driver driver = io.github.toolfactory.jvm.Driver.Factory.getNewDynamic();
  • this code to create an hybrid driver instance:
io.github.toolfactory.jvm.Driver driver = io.github.toolfactory.jvm.Driver.Factory.getNewHybrid();
  • this code to create a native driver instance:
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:

public <D extends Driver> D init();

public <T> 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 <T> Constructor<T>[] getDeclaredConstructors(Class<T> cls);

public Field[] getDeclaredFields(Class<?> cls);

public Method[] getDeclaredMethods(Class<?> cls);

public <T> T getFieldValue(Object target, Field field);

public Package getPackage(ClassLoader classLoader, String packageName);

public Collection<URL> getResources(String resourceRelativePath, boolean findFirst, ClassLoader... classLoaders);

public Collection<URL> getResources(String resourceRelativePath, boolean findFirst, Collection<ClassLoader> classLoaders);

public <T> T invoke(Object target, Method method, Object[] params);

public boolean isBuiltinClassLoader(ClassLoader classLoader);

public boolean isClassLoaderDelegate(ClassLoader classLoader);

public <T> T newInstance(Constructor<T> ctor, Object[] params);

public CleanableSupplier<Collection<Class<?>>> getLoadedClassesRetriever(ClassLoader classLoader);

public Map<String, ?> 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> T throwException(String message, Object... placeHolderReplacements);

public <T> T throwException(Throwable exception);

Compilation requirements

A JDK version 9 or higher and a GCC compiler are required to compile the project. On Windows you can find compiler and GDB debugger from MinGW-W64 project.


Contributing

The native module is currently compiled for Linux x86/x64, Windows x86/x64, and Mac OS X x64: feel free to contribute native code builds for other platforms or architectures. Once the native code is compiled you need to add a few lines of code in the native library loader.


Ask for assistance

For assistance you can: