{"id":20054239,"url":"https://github.com/toolfactory/jvm-driver","last_synced_at":"2025-04-07T07:17:59.724Z","repository":{"id":38311879,"uuid":"399035799","full_name":"toolfactory/jvm-driver","owner":"toolfactory","description":"A driver to allow deep interaction with the JVM without any restrictions","archived":false,"fork":false,"pushed_at":"2024-11-12T11:11:57.000Z","size":3871,"stargazers_count":53,"open_issues_count":7,"forks_count":4,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-31T06:06:15.479Z","etag":null,"topics":["classloader","java","jvm","reflection"],"latest_commit_sha":null,"homepage":"https://github.com/toolfactory","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/toolfactory.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"custom":"https://www.paypal.com/donate/?cmd=_donations\u0026business=EY4TMTW8SWDAC\u0026item_name=Support+maintenance+and+improvement+of+ToolFactory+JVM+Driver\u0026currency_code=EUR\u0026source=url"}},"created_at":"2021-08-23T08:55:16.000Z","updated_at":"2025-01-20T21:29:58.000Z","dependencies_parsed_at":"2023-02-17T01:02:19.901Z","dependency_job_id":"39fff18a-7425-47d4-89e5-57d023b307e5","html_url":"https://github.com/toolfactory/jvm-driver","commit_stats":null,"previous_names":[],"tags_count":146,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toolfactory%2Fjvm-driver","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toolfactory%2Fjvm-driver/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toolfactory%2Fjvm-driver/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toolfactory%2Fjvm-driver/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/toolfactory","download_url":"https://codeload.github.com/toolfactory/jvm-driver/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247608160,"owners_count":20965953,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["classloader","java","jvm","reflection"],"created_at":"2024-11-13T12:39:33.752Z","updated_at":"2025-04-07T07:17:59.683Z","avatar_url":"https://github.com/toolfactory.png","language":"Java","readme":"# ToolFactory JVM Driver [![Tweet](https://img.shields.io/twitter/url/http/shields.io.svg?style=social)](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\u0026url=https://toolfactory.github.io/jvm-driver/)\n\n\u003ca href=\"https://github.com/toolfactory\"\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/toolfactory/jvm-driver/master/docs/logo.png\" alt=\"logo.png\" height=\"180px\" align=\"right\"/\u003e\n\u003c/a\u003e\n\n[![Maven Central with version prefix filter](https://img.shields.io/maven-central/v/io.github.toolfactory/jvm-driver/9)](https://maven-badges.herokuapp.com/maven-central/io.github.toolfactory/jvm-driver/)\n[![GitHub](https://img.shields.io/github/license/toolfactory/jvm-driver)](https://github.com/toolfactory/jvm-driver/blob/main/LICENSE)\n\n[![Platforms](https://img.shields.io/badge/platforms-Windows%2C%20Mac%20OS%2C%20Linux-orange)](https://github.com/toolfactory/jvm-driver/actions/runs/8919531180)\n\n[![Supported JVM](https://img.shields.io/badge/supported%20JVM-7%2C%208%2C%209+%20(22)-blueviolet)](https://github.com/toolfactory/jvm-driver/actions/runs/8919531180)\n\n[![GitHub open issues](https://img.shields.io/github/issues/toolfactory/jvm-driver)](https://github.com/toolfactory/jvm-driver/issues)\n[![GitHub closed issues](https://img.shields.io/github/issues-closed/toolfactory/jvm-driver)](https://github.com/toolfactory/jvm-driver/issues?q=is%3Aissue+is%3Aclosed)\n\n[![Repository dependents](https://badgen.net/github/dependents-repo/toolfactory/jvm-driver)](https://github.com/toolfactory/jvm-driver/network/dependents)\n\nExtracted 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**.\n\n\u003cbr/\u003e\n\nTo include ToolFactory JVM Driver in your projects simply use with **Apache Maven**:\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003eio.github.toolfactory\u003c/groupId\u003e\n    \u003cartifactId\u003ejvm-driver\u003c/artifactId\u003e\n    \u003cversion\u003e9.7.1\u003c/version\u003e\n\u003c/dependency\u003e\t\n```\n### Requiring the ToolFactory JVM Driver module\n\nTo use ToolFactory JMV Driver as a Java module, add the following to your `module-info.java`: \n\n```java\n//Mandatory if you use the dynamic, hybrid or native driver\nrequires io.github.toolfactory.narcissus;\n\n//Mandatory if you use the default, dynamic or hybrid driver\nrequires jdk.unsupported;\n\nrequires io.github.toolfactory.jvm;\n```\n\n\u003cbr/\u003e\n\n## Overview\n\nThere are four kinds of driver:\n\n* the **default driver** completely based on Java api\n* 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\n* the **hybrid driver** that extends the default driver and uses some JNI functions only when run on JVM 17 and later\n* the **native driver** that extends the hybrid driver and uses JNI functions more consistently regardless of the Java version it is running on\n\nBy 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:\n* Windows (x86, x64)\n* Linux (x86, x64)\n* MacOs (x64)\n\nIt 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/).\n\n\u003cbr/\u003e\n\n## Usage\n\nTo create a driver instance you should use this code:\n```java\nio.github.toolfactory.jvm.Driver driver = io.github.toolfactory.jvm.Driver.getNew();\n```\n\nThe 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**.\n\nIf you need to create a specific driver type you should use:\n\n* this code to create a default driver instance:\n\n```java\nio.github.toolfactory.jvm.Driver driver = io.github.toolfactory.jvm.Driver.Factory.getNewDefault();\n```\n\n* this code to create a dynamic driver instance:\n\n```java\nio.github.toolfactory.jvm.Driver driver = io.github.toolfactory.jvm.Driver.Factory.getNewDynamic();\n```\n\n* this code to create an hybrid driver instance:\n\n```java\nio.github.toolfactory.jvm.Driver driver = io.github.toolfactory.jvm.Driver.Factory.getNewHybrid();\n```\n\n* this code to create a native driver instance:\n\n```java\nio.github.toolfactory.jvm.Driver driver = io.github.toolfactory.jvm.Driver.Factory.getNewNative();\n```\n\n\u003cbr/\u003e\n\nEach 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()`.\n\nThe methods exposed by the Driver interface are the following:\n```java\npublic \u003cD extends Driver\u003e D init();\n\npublic \u003cT\u003e T allocateInstance(Class\u003c?\u003e cls);\n\n// Return a ClassLoaderDelegate or the input itself if the input is a \n// BuiltinClassLoader or null if the JVM version is less than 9\npublic ClassLoader convertToBuiltinClassLoader(ClassLoader classLoader);\n\npublic Class\u003c?\u003e defineHookClass(Class\u003c?\u003e clientClass, byte[] byteCode);\n\npublic Class\u003c?\u003e getBuiltinClassLoaderClass();\n\npublic Class\u003c?\u003e getClassLoaderDelegateClass();\n\npublic Class\u003c?\u003e getClassByName(String className, Boolean initialize, ClassLoader classLoader, Class\u003c?\u003e caller);\n\npublic MethodHandles.Lookup getConsulter(Class\u003c?\u003e cls);\n\npublic \u003cT\u003e Constructor\u003cT\u003e[] getDeclaredConstructors(Class\u003cT\u003e cls);\n\npublic Field[] getDeclaredFields(Class\u003c?\u003e cls);\n\npublic Method[] getDeclaredMethods(Class\u003c?\u003e cls);\n\npublic \u003cT\u003e T getFieldValue(Object target, Field field);\n\npublic Package getPackage(ClassLoader classLoader, String packageName);\n\npublic Collection\u003cURL\u003e getResources(String resourceRelativePath, boolean findFirst, ClassLoader... classLoaders);\n\npublic Collection\u003cURL\u003e getResources(String resourceRelativePath, boolean findFirst, Collection\u003cClassLoader\u003e classLoaders);\n\npublic \u003cT\u003e T invoke(Object target, Method method, Object[] params);\n\npublic boolean isBuiltinClassLoader(ClassLoader classLoader);\n\npublic boolean isClassLoaderDelegate(ClassLoader classLoader);\n\npublic \u003cT\u003e T newInstance(Constructor\u003cT\u003e ctor, Object[] params);\n\npublic CleanableSupplier\u003cCollection\u003cClass\u003c?\u003e\u003e\u003e getLoadedClassesRetriever(ClassLoader classLoader);\n\npublic Map\u003cString, ?\u003e retrieveLoadedPackages(ClassLoader classLoader);\n\npublic void setAccessible(AccessibleObject object, boolean flag);\n\npublic void setFieldValue(Object target, Field field, Object value);\n\npublic void stop(Thread thread);\n\npublic \u003cT\u003e T throwException(String message, Object... placeHolderReplacements);\n\npublic \u003cT\u003e T throwException(Throwable exception);\n```\n\n\u003cbr/\u003e\n\n\nIn 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`:\n\n```java\npublic static Reflection getNew();\n\npublic static Reflection getNewWithDefaultDriver();\n\npublic static Reflection getNewWithDynamicDriver();\n\npublic static Reflection getNewWithHybridDriver();\n\npublic static Reflection getNewWithNativeDriver();\n\npublic static Reflection getNewWith(Driver driver);\n```\n\nThe methods exposed by the `io.github.toolfactory.util.Reflection` component are the following:\n```java\npublic Driver getDriver();\n\npublic Collection\u003cMethod\u003e getDeclaredMethods(Class\u003c?\u003e cls);\n\npublic Collection\u003cMethod\u003e getAllMethods(Class\u003c?\u003e cls);\n\npublic \u003cT\u003e T getFieldValue(Object target, Field field);\n\npublic void setFieldValue(Object target, Field field, Object value);\n\npublic Field getDeclaredField(Class\u003c?\u003e cls, String name);\n\npublic Collection\u003cField\u003e getDeclaredFields(Class\u003c?\u003e cls);\n\npublic Collection\u003cField\u003e getAllFields(Class\u003c?\u003e cls);\n\npublic Collection\u003cConstructor\u003c?\u003e\u003e getDeclaredConstructors(Class\u003c?\u003e cls);\n\npublic Collection\u003cConstructor\u003c?\u003e\u003e getAllConstructors(Class\u003c?\u003e cls);\n```\n\n\u003cbr /\u003e\n\n## Compilation requirements\n\n**A JDK version 9 or higher is required to compile the project**.\n\u003cbr /\u003e\n\n# \u003ca name=\"Ask-for-assistance\"\u003e\u003c/a\u003eAsk for assistance\n**For assistance you can**:\n* [open a discussion](https://github.com/toolfactory/jvm-driver/discussions) here on GitHub\n* [report a bug](https://github.com/toolfactory/jvm-driver/issues) here on GitHub\n* ask on [Stack Overflow](https://stackoverflow.com/questions/ask)\n","funding_links":["https://www.paypal.com/donate/?cmd=_donations\u0026business=EY4TMTW8SWDAC\u0026item_name=Support+maintenance+and+improvement+of+ToolFactory+JVM+Driver\u0026currency_code=EUR\u0026source=url"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftoolfactory%2Fjvm-driver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftoolfactory%2Fjvm-driver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftoolfactory%2Fjvm-driver/lists"}