SRO.CLSJVM.RefResolution

A multi-platform .NET library that provides reference resolution for JVM-targeting compilers. It resolves class, field, and method information from two complementary sources:

• Manual registration — a compiler's front-end registers entities it has already parsed from source code so they can be looked up later during semantic analysis.
• Binary classpath scanning — compiled JVM artifacts (class directories, JAR archives, and JIMAGE module files) are inspected on demand so that external library types can participate in name resolution without requiring source code.

Target Frameworks

Dependencies

Quick Start

// 1. Configure the library – provide a JVM-style classpath.
var config = new LibraryConfiguration("/opt/java/jdk-21/lib/ct.sym:/myapp/libs/*", verbose: false);

// 2. Create and initialise the library.
var library = new CodeAssetsLibrary();
library.Initialize(config);

// 3. Register source-derived entities.
var stringClass = new ClassData("java.lang.String");
library.RegisterClass(stringClass);

var lengthMethod = new MethodData("length", stringClass);
library.RegisterMethod(lengthMethod);

// 4. Query by fully qualified name.
ClassData result = library.FindClass(new ClassCriteria("java.lang.String"));
if (result.Result == QueryResult.Success)
{
    Console.WriteLine($"Found: {result.FullClassName}");
}

// 5. Query when only a simple name and a set of candidate packages are known.
var ambiguous = new AmbiguousClassCriteria(
    new List<string> { "com.example.mypackage", "java.lang" },
    "String");
ClassData ambiguousResult = library.FindClass(ambiguous);

Core Concepts

CodeAssetsLibrary

CodeAssetsLibrary is the central facade for the library. It maintains in-memory dictionaries of registered classes, fields, and methods and delegates binary lookups to BinaryClassManager.

LibraryConfiguration

Carries the settings passed to Initialize or Reinitialize.

// Default – empty classpath, verbose off.
var cfg = new LibraryConfiguration();

// Explicit.
var cfg = new LibraryConfiguration(classpath: "/usr/lib/jvm/java-21/lib/*", verbose: true);

Query Criteria

ClassCriteria

Use ClassCriteria when the fully qualified class name is known at query time.

// Top-level class.
var c = new ClassCriteria("java.util.ArrayList");

// Named inner class.
var inner = new ClassCriteria("java.util.AbstractMap") { InnerClassName = "SimpleEntry" };

// Anonymous class (JVM synthetic index).
var anon = new ClassCriteria("com.example.Outer") { AnonymousClassIndex = 1 };

AmbiguousClassCriteria

Use AmbiguousClassCriteria when only a simple name is available and the fully qualified package must be resolved by trying candidate namespaces in order.

// Regular class – tries "com.example" then "java.lang".
var a = new AmbiguousClassCriteria(
    new List<string> { "com.example", "java.lang" }, "String");

// Anonymous class factory.
var anon = AmbiguousClassCriteria.ForAnonymousClass(namespaces, "Outer", anonymousIndex: 1);

// Inner named class factory.
var inner = AmbiguousClassCriteria.ForInnerClass(namespaces, "AbstractMap", "SimpleEntry");

MethodCriteria

var host = new ClassCriteria("java.util.ArrayList");

// Match all overloads of "add".
var allOverloads = new MethodCriteria(host, "add");

// Match a specific overload.
var exact = new MethodCriteria(
    host,
    "add",
    parameters: new List<ParameterCriteria>
    {
        new ParameterCriteria(new TypeCriteria("java.lang.Object"))
    },
    returnType: new TypeCriteria("boolean"),
    methodType: MethodType.Regular);

FieldCriteria

var host = new ClassCriteria("java.lang.System");

// Match by name only (returns MultipleMatches if the name is overloaded).
var byName = new FieldCriteria(host, "out");

// Match with an explicit type.
var exact = new FieldCriteria(host, "out", new TypeCriteria("java.io.PrintStream"));

Result Types

All Find* methods return a *Data object. Inspect the Result property before using any other fields.

ClassData cd = library.FindClass(new ClassCriteria("java.lang.String"));
switch (cd.Result)
{
    case QueryResult.Success:         /* use cd */                          break;
    case QueryResult.MultipleMatches: /* ambiguous – narrow the query */    break;
    case QueryResult.NotFound:        /* not in registry or on classpath */ break;
}

Data Holders

MemberAccess Flags

MemberAccess is a [Flags] enumeration that maps directly to the JVM access_flags bitmask defined in the class-file specification, while providing human-readable names for each bit position.

bool isPublicStatic = classData.Access.HasFlag(MemberAccess.Public)
                   && classData.Access.HasFlag(MemberAccess.Static);

Context-dependent bits follow the JVM convention:

Binary Classpath Infrastructure

BinaryClassManager

BinaryClassManager is a process-scoped singleton that manages binary class loading from the configured classpath. CodeAssetsLibrary.Initialize calls it automatically; direct access is rarely needed.

// Automatically initialised by CodeAssetsLibrary.Initialize().
// Direct use (advanced):
BinaryClassManager mgr = BinaryClassManager.GetInstance();
bool exists = mgr.Exists("java.lang.String");
BinaryClassData bcd = mgr.LoadClass("java.util.ArrayList");

LoadClass caches loaded classes in memory so each .class entry in the classpath is read only once per process lifetime.

ClassLocator

ClassLocator is the low-level search engine used by BinaryClassManager. It accepts JAR files, plain class directories, and wildcard directory expansions as classpath entries and resolves dot-notation class names to the appropriate binary stream.

var locator = new ClassLocator();
locator.SetUp();                                          // auto-discovers JAVA_HOME
locator.LoadClassPath("/mylibs/*:/myproject/bin");

string fqn  = locator.ExpandNameViaImports("ArrayList", importList);
string fqn2 = locator.ExpandNameViaUsing("String", usingList);
string fqn3 = locator.ExpandNameUsingNamespace("String", "java.lang");

ClassPathHandler

ClassPathHandler deserialises the Eclipse .classpath XML project file format and computes a JVM classpath string from its entries. This is useful when the library is hosted inside an Eclipse-layout workspace.

var handler = new ClassPathHandler();
handler.Load("/path/to/project/.classpath");
string cp = handler.Classpath;   // ready to pass to LibraryConfiguration

Utility Types

FileSystemItem

A cross-platform file-system abstraction modelled after java.io.File. It wraps a path and provides directory listing, existence testing, and child-item construction, isolating the rest of the library from direct System.IO usage.

var root     = new FileSystemItem("/opt/java");
var lib      = new FileSystemItem(root, "lib");
FileSystemItem[] children = lib.ListFiles();

The static constants FileSystemItem.Separator and FileSystemItem.PathSeparator expose the platform-specific directory and path-list separator characters respectively.

JarFilter / FilenameFilter

FilenameFilter is an interface with a single Accept(FileSystemItem dir, string name) method. JarFilter is the built-in implementation that accepts files whose names end with .jar.

Exceptions

License

Copyright © 2026 Serengeti Research Organization. All rights reserved.