Utility tooling for instrumentation, test scaffolding, etc

In-memory/on-disk support for compilation and archiving, power-proxing and dynamic instrumentation, supporting JDKs 8, 9 and 10.

You could:

  • Compile from a string, with dependencies from Maven artifact coordinates, stuffed into a signed, in-memory, multi-release JAR, complete with annotations processed, performing bytecode class transformation, an OSGi bundle manifest and a JPMS module-info, then load into current. runtime or publish to a maven repo…
  • Attach a JavaAgent to a JUnit test without modifying the JVM start-up parameters (i.e. out-of-the-box IDE support)
  • Proxy concrete classes with convenience of vanilla InvocationHandlers
Tests as Examples and Examples as Documentation

At this initial stage the aim is to prove minimal documentation through examples extracted from tests. Currently some modules have no documentation; these are typically of limited value to the end user. See the module list.

A ridiculous Hello World example demonstrates the use of multiple modules; it creates 3 interdependent JARs, and then executes as OSGi, JPMS and vanilla Java applications, entirely in-memory. A smaller example of just dynamic in-memory JPMS can be found in lade.jpms.

Otherwise, a sensible place to start is instrumental.archive, which lists the various extension modules, each of which has a brief example.

Module Graph

Module Graph

Module List

Module Description Examples
io.earcam.instrumental.reflect Gentle reflection of types, names and resources
io.earcam.instrumental.compile Compile from memory/filesystem to memory/filesystem, easily
io.earcam.instrumental.compile.glue Glues instrumental.compile to instrumental.archive, compile to JAR entirely in-memory
io.earcam.instrumental.lade Not just the usual fudge of ClassLoader.defineClass() - loads in-memory JARs returning valid resource URLs
io.earcam.instrumental.lade.jpms Create and run dynamic JPMS module layers from an in-memory classloader
io.earcam.instrumental.fluent Annotation to demarcate fluent API methods
io.earcam.instrumental.fluency Annotation processor of fluently annotated methods, generating APIs with fluency
io.earcam.instrumental.module.manifest Abstraction of java.util.jar.Manifest, extended variously
io.earcam.instrumental.module.auto Bytecode parsing sufficient to enable auto-importing for programmatic modules
io.earcam.instrumental.module.jpms JPMS module tooling; read/write bytecode/sourcecode
io.earcam.instrumental.module.osgi OSGi module tooling; read/write bundle manifests
io.earcam.instrumental.archive Create/read archives in-memory/on-disk, supports Multi-Release JARs
io.earcam.instrumental.archive.jpms Archive extension for JPMS modules
io.earcam.instrumental.archive.osgi Archive extension for OSGi bundles
io.earcam.instrumental.archive.sign Archive extension for digital signing
io.earcam.instrumental.archive.glue Glues instrumental.archive to to instrumental.compile, enabling in-memory archives as dependencies
io.earcam.instrumental.archive.maven Install/Resolve archives to/from Maven repositories
io.earcam.instrumental.proxy Smoother API than java.lang.reflect and various InvocationHandlers
io.earcam.instrumental.proxy.concrete Proxy classes using standard java.lang.reflect.InvocationHandler
io.earcam.instrumental.agent Dynamically load a Java Agent or acquire java.lang.instrument.Instrumentation via SPI
io.earcam.instrumental.agent.junit Use Java Agents in JUnit tests (4.12 and 5.3.0-M1) without any external configuration
io.earcam.instrumental.agent.defy Java Agent to remove final modifiers from classes, methods and fields

Back to top

Version: 0.1.0. Last Published: 2018-10-08.

Earcam Maven Skin.