SRO.CLSJVM.LookingGlass - Looking Glass

Looking Glass - A view from one binary world to another.

LookingGlass is a research-grade .NET library from the Serengeti Research Organization (SRO) that provides full programmatic creation, reading, and manipulation of JVM (Java Virtual Machine) class files — the .class binary format — entirely from managed .NET code. No Java compiler or JDK toolchain is required to generate valid class files; the library implements the JVM Class File Specification directly.

The library targets both .NET Framework 4.8 and .NET 8.0, making it usable in both legacy Windows desktop applications and modern cross-platform environments.

Table of Contents

• Why Looking Glass?
• Solution Layout
• Library Architecture
  • Foundation Layer
  • Model Layer
  • Translation Engine
• Project Structure
• Getting Started
  • Creating a Class from Scratch
  • Reading an Existing Class File
• Key Concepts
  • ClassModel Hierarchy
  • JVM Version Emulation
  • Automatic Allocation
  • Stack Map Frame Generation
  • IBCEngineIOContract - Pluggable I/O
• Building
• Test Projects
• NuGet Package
• Dependencies
• License

Why Looking Glass?

The Microsoft Roslyn compiler platform emits .NET IL binary files. LookingGlass is the research equivalent for the JVM side of that boundary — a toolkit powerful enough to serve as the back-end of a compiler that targets the JVM instead of the CLR. Because it works entirely in managed .NET code it can be embedded in any .NET application, service, or toolchain without requiring a JDK installation at runtime.

Concrete scenarios enabled by the library include:

• Cross-platform code generation — emit .class files for any supported JDK version (1.1 through Java SE 28) from .NET code.
• JVM bytecode tooling — read, disassemble, inspect, or transform existing .class files inside a .NET process.
• Compiler back-ends — use LookingGlass as the code-generation stage for a language targeting the JVM.
• Research and education — explore the JVM class file format, constant pool layout, access flags, and stack map frame verification without leaving the .NET ecosystem.

Solution Layout

SRO.CLSJVM.LookingGlass/
+-- SRO.CLSJVM.LookingGlass.sln          # Solution file
+-- README.md                             # This file
|
+-- SRO.CLSJVM.LookingGlass/             # Main library project (net48 + net8.0)
|   +-- SRO.CLSJVM.LookingGlass.csproj
|   +-- Foundation/                      # Foundation namespace -- binary I/O primitives
|   +-- ByteCodeEngine/                  # Translation engine -- Model <-> binary
|   +-- [ModelAPI source files]          # Root namespace -- high-level object model
|
+-- LookingGlassTests/                   # WinForms visual test harness (net48)
|   +-- LookingGlassTests.csproj
|
+-- UnitTests/                           # xUnit automated test suite (net8.0)
    +-- UnitTests.csproj

Library Architecture

LookingGlass ships as a single NuGet package (SRO.CLSJVM.LookingGlass) containing three conceptual layers organized by namespace. The Foundation layer uses the sub-namespace SRO.CLSJVM.LookingGlass.Foundation; the Model and Translation layers share the root SRO.CLSJVM.LookingGlass namespace.

+------------------------------------------+
|      Your Application / Compiler         |
+-------------------+----------------------+
                    |
        +-----------v---------------------------------+
        |         SRO.CLSJVM.LookingGlass            |
        |         (single library / package)         |
        |                                            |
        |  +--------------------------------------+  |
        |  | Model Layer  (root namespace)        |  |
        |  | ClassModel, MethodModel, CodeBlock   |  |
        |  +----------+------------------+--------+  |
        |             |                  |           |
        |  +----------+------+  +--------+---------+ |
        |  | Foundation      |  | Translation      | |
        |  | (.Foundation    |  | Engine           | |
        |  |  namespace)     |  | ClassBuilder     | |
        |  | ClassEditor     |  | ClassDeconstructor| |
        |  | MethodEditor    |  +------------------+ |
        |  +-----------------+                       |
        +---------------------------------------------+

Foundation Layer

Namespace: SRO.CLSJVM.LookingGlass.Foundation

The Foundation layer implements every detail of the JVM Class File Specification at the byte level. It is the lowest layer and is what ultimately reads and writes the 0xCAFEBABE magic-number binary format.

Model Layer

Namespace: SRO.CLSJVM.LookingGlass

The Model layer provides a clean, high-level object model that insulates callers from the binary-level details of the Foundation layer. It is the primary surface for application code and compiler back-ends.

Translation Engine

Namespace: SRO.CLSJVM.LookingGlass

The Translation Engine bridges the Model and Foundation layers by implementing the translation in both directions.

Project Structure

Getting Started

Creating a Class from Scratch

The typical workflow using the Model and Translation layers:

using SRO.CLSJVM.LookingGlass;

// 1. Describe the class
ClassModel cm = new ClassModel();
cm.ClassName      = "com/example/Hello";
cm.SuperClassName = "java/lang/Object";
cm.Public         = true;
cm.Emulation      = "SE11";  // target Java 11 class-file format

// 2. Add a default constructor
MethodModel ctor = new MethodModel();
ctor.Name                  = Constants.CONSTRUCTOR_NAME;  // "<init>"
ctor.Public                = true;
ctor.ReturnsTypeDescriptor = "V";

CodeBlock ctorBody = new CodeBlock();
ctorBody.AddInstruction(new Instruction(OpcodeValues.ALOAD_0));
Instruction superCall = new Instruction(OpcodeValues.INVOKESPECIAL);
superCall.AddMethodSpecArgument("java/lang/Object", "<init>", "()V");
ctorBody.AddInstruction(superCall);
ctorBody.AddInstruction(new Instruction(OpcodeValues.RETURN));
ctor.Block = ctorBody;
ctor.AutoAllocate();
cm.AddMethod(ctor);

// 3. Add a main method that prints "Hello, World!"
MethodModel main = new MethodModel();
main.Name                  = "main";
main.Public                = true;
main.Static                = true;
main.ReturnsTypeDescriptor = "V";
main.AddParameterDescriptor("[Ljava/lang/String;");

CodeBlock mainBody = new CodeBlock();
Instruction getStatic = new Instruction(OpcodeValues.GETSTATIC);
getStatic.AddFieldSpecArgument("java/lang/System", "out", "Ljava/io/PrintStream;");
mainBody.AddInstruction(getStatic);
Instruction ldc = new Instruction(OpcodeValues.LDC);
ldc.AddStringArgument("Hello, World!");
mainBody.AddInstruction(ldc);
Instruction println = new Instruction(OpcodeValues.INVOKEVIRTUAL);
println.AddMethodSpecArgument("java/io/PrintStream", "println", "(Ljava/lang/String;)V");
mainBody.AddInstruction(println);
mainBody.AddInstruction(new Instruction(OpcodeValues.RETURN));
main.Block = mainBody;
main.AutoAllocate();
cm.AddMethod(main);

// 4. Emit the class file
ModelFileIO.SaveBinary("Hello.class", cm);

Reading an Existing Class File

using SRO.CLSJVM.LookingGlass;

// Load a .class file back into an object model
ClassModel cm = ModelFileIO.LoadBinary("Hello.class");

Console.WriteLine("Class   : " + cm.ClassName);
Console.WriteLine("Super   : " + cm.SuperClassName);
Console.WriteLine("JVM ver : " + cm.Emulation);

foreach (MethodModel m in cm.Methods)
{
	Console.WriteLine("  Method: " + m.SourceView);
}

Key Concepts

ClassModel Hierarchy

ClassModel
 +-- List<FieldModel>            - fields with descriptors and access flags
 +-- List<MethodModel>           - methods
 |    +-- CodeBlock              - instruction stream + exception handlers
 |         +-- List<Instruction>
 |         +-- List<ExceptionHandlerModel>
 +-- List<InnerClassModel>       - inner/nested class declarations
 +-- List<string>                - implemented interfaces

JVM Version Emulation

The ClassModel.Emulation property selects the target JVM major/minor version written into the class file header. Supported values span the full range from "1.1" through "SE28". The Translation Engine automatically adjusts whether a StackMapTable attribute is required (mandatory for class files with major_version >= 50, i.e., JDK 6+).

cm.Emulation = "SE17";   // Java SE 17 -- major_version = 61

Automatic Allocation

Callers do not need to manually compute maximum stack depth, local variable slot counts, or stack map frame entries. Calling AutoAllocate() on a MethodModel (or ClassModel) triggers automatic analysis:

mm.AutoAllocate();   // computes MaxLocals, MaxStack, and StackMapTable entries

The AutoAllocationDirective flags allow fine-grained control when manual values are preferred:

mm.AutomaticStackMapGeneration = true;  // let LookingGlass generate the StackMapTable
mm.AutomaticStackSize          = true;  // compute max_stack automatically
mm.AutomaticLocals             = true;  // compute max_locals automatically

Stack Map Frame Generation

Class files targeting Java SE 6 or later require a StackMapTable attribute on any method that contains control-flow branches (conditionals, loops, exception handlers). LookingGlass generates this attribute automatically via StackMapFrameProcesser (Foundation layer), which performs a code-flow simulation over the opcode stream, tracking operand stack and local variable types at each branch target.

IBCEngineIOContract - Pluggable I/O

The IBCEngineIOContract interface separates the high-level model from the binary serialisation implementation:

public interface IBCEngineIOContract
{
	void       SaveBinary(string path, ClassModel model);
	ClassModel LoadBinary(string path);
	void       SaveStream(Stream stream, ClassModel model);
	ClassModel LoadStream(Stream stream);
}

ModelFileIO discovers a concrete implementation by scanning the application's assembly directory at startup, so alternative or extended engines can be substituted by dropping a replacement assembly alongside the host application — no recompilation required.

Building

The library is an SDK-style, multi-target project. Build from within the solution directory:

# Restore and build all projects
dotnet build SRO.CLSJVM.LookingGlass.sln

# Build only the main library
dotnet build SRO.CLSJVM.LookingGlass\SRO.CLSJVM.LookingGlass.csproj

# Produce a NuGet package (GeneratePackageOnBuild is enabled by default)
dotnet pack SRO.CLSJVM.LookingGlass\SRO.CLSJVM.LookingGlass.csproj -c Release

NuGet packages are generated automatically on each build (GeneratePackageOnBuild = true) and land in the project's bin\Debug or bin\Release output folder.

Test Projects

UnitTests (xUnit - .NET 8.0)

The automated test suite in UnitTests\UnitTestsFramework.cs drives the full round-trip workflow: generate a ClassModel, emit a .class file, invoke the host JRE to execute the class, and assert the standard output matches expectations.

Tests are organized by scenario:

Note: A JRE installation accessible on the system PATH is required for the xUnit tests that execute generated class files.

LookingGlassTests (WinForms - .NET Framework 4.8)

A Windows Forms GUI harness for interactive and visual testing. It allows a developer to load any .class file, inspect the resulting ClassModel (fields, methods, constant pool, XML serialisation view), edit class-level properties, and save a modified class back to disk. Run this project directly from Visual Studio.

NuGet Package

This README.md is embedded as the NuGet package README file.

Dependencies

License

Copyright (c) 2011-2026 Serengeti Research Organization. All rights reserved.