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 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.14.0</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:

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:


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:

io.github.toolfactory.jvm.Driver driver = io.github.toolfactory.jvm.Driver.Factory.getNewDefault();
io.github.toolfactory.jvm.Driver driver = io.github.toolfactory.jvm.Driver.Factory.getNewDynamic();
io.github.toolfactory.jvm.Driver driver = io.github.toolfactory.jvm.Driver.Factory.getNewHybrid();
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: