Runtime-friendly view over parsed Java class files
Introduction
The jclassfile crate parses a Java class file into a structure that mirrors the
Java Virtual Machine Specification (JVMS), Chapter §4 exactly: constant pool entries hold
raw u16 indexes into each other, attributes are an untyped list, and names are only reachable by
following an index to a Utf8 entry.
That faithfulness is the right shape for a parser, but not for a consumer. Anything that actually
uses a class file has to do the same postprocessing first: resolve name and descriptor indexes
into strings, key methods by name and descriptor, group attributes by kind, and turn the Code
attribute into something with resolved exception handlers and line numbers.
jclassmodel does that work once, on top of jclassfile, and hands back a view meant for use
rather than for inspection.
Usage
Parse the bytes, turn them into a model, and read it. No constant-pool index appears after the first line.
use ;
let bytecode = read?;
let model = parse?.into_model_with_recorded_name?;
println!;
if let Some = &model.super_class_name
for interface in &model.interfaces
for field in &model.fields
for method in &model.methods
Which name is the class loaded under?
into_model_with_recorded_name names the class the way its own constant pool does, and derives the
external name by replacing / with .. That is correct for any class read from a .class file,
so it is the entry point to reach for.
The lower-level ParsedClass::into_model(internal_name, external_name) exists because a JVM does
not always load a class under the name recorded in it. A hidden class
(Lookup.defineHiddenClass, and therefore every lambda) is defined from a class file that records
my/package/MyClass while the VM loads it as my/package/MyClass/0xABCDEF; the suffix is minted
at definition time and appears nowhere in the file. Such a name is also not a plain /-to-.
replacement, since the final separator stays a slash: my.package.MyClass/0xABCDEF. The same
applies to classes a VM invents outright, such as primitives (I is externally int) and arrays.
If that is you, read the recorded name with ParsedClass::this_class_name(), apply your own naming
policy, and pass both names in. Otherwise ignore this entirely.
Relationship to jclassfile
jclassfile |
jclassmodel |
|
|---|---|---|
| Shape | 1:1 with JVMS §4 | organized for lookup |
| Constant pool | Vec of raw entries, indexes unresolved |
typed accessors returning resolved values |
| Attributes | flat Vec<Attribute> |
grouped by kind |
| Cross-references | u16 indexes |
resolved names and descriptors |
The dividing line is whether a step requires an interpretation choice. Decoding the byte layout belongs to the parser; deciding how a consumer wants the result indexed belongs here.
jclassfile is a private implementation detail: it does not appear anywhere in this crate's public
API, so depending on jclassmodel does not tie you to a particular jclassfile version.
Relationship to jdescriptor
jdescriptor is treated the other way round, on purpose. MethodModel::descriptor and
FieldModel::descriptor hand back its MethodDescriptor and TypeDescriptor, because a parsed
descriptor is vocabulary a consumer needs to pass around, not a detail worth hiding. That makes
jdescriptor a public dependency: its version is part of this crate's semver contract.
Rust type identity is per compiled copy of a crate, so a build that resolves a second,
semver-incompatible jdescriptor gets a MethodDescriptor that is a distinct type from this one,
and the two cannot be exchanged. To keep that from happening, jdescriptor is re-exported. Reach
for jclassmodel::MethodDescriptor, or the whole crate at jclassmodel::jdescriptor, instead of
declaring your own dependency on it.
Type mapping
Top-level structures
jclassfile |
jclassmodel |
What the conversion does |
|---|---|---|
ClassFile |
ClassModel |
this_class/super_class indexes become name/super_class_name: Option<String>; interfaces: Vec<u16> becomes Vec<String> |
major_version/minor_version |
ClassFileVersion |
Two loose u16s become one ordered value with is_preview(); also readable from ParsedClass::version() before resolving the class |
Vec<ConstantPool> |
ConstantPool |
A flat vector of entries becomes a lookup: get_utf8, get_class_name, get_full_method_info, get_method_handle, … each resolving the indexes an entry points at |
ConstantPool (one entry) |
ConstantTag |
The entry's kind, without its payload, for callers that only need the tag byte |
Vec<Attribute> |
Attributes |
An untyped list becomes a map keyed by attribute kind |
MethodInfo |
MethodModel |
name_index/descriptor_index become name: String and descriptor: MethodDescriptor (parsed via jdescriptor), plus name_signature ("name:descriptor") |
FieldInfo |
FieldModel |
name_index/descriptor_index become name: String and descriptor: TypeDescriptor |
jclassfile::error::Error |
jclassmodel::Error |
A coarse ErrorKind (ClassFile, ConstantPool, Descriptor, Structure); the parser error stays reachable via Error::source |
Attributes and the records inside them
jclassfile |
jclassmodel |
What the conversion does |
|---|---|---|
Attribute::Code |
CodeModel |
Keeps max_stack/max_locals/bytecode, and resolves the tables nested inside it |
ExceptionRecord |
ExceptionTableRecord |
catch_type: u16 becomes a CatchType: Class(name), or Any for the 0 catch-all a finally compiles to |
LineNumberRecord |
line_numbers: BTreeMap<u16, u16> |
A sequence of records becomes a lookup from bytecode index to source line |
LocalVariableTableRecord |
LocalVariableInfo |
name_index becomes name: String; index is renamed slot |
BootstrapMethodRecord |
BootstrapMethodInfo |
bootstrap_method_ref is resolved into ref_kind + class, method name and descriptor, joined with the invokedynamic name and descriptor |
Attribute::InnerClasses |
ClassModel::declaring_class + nested_class_modifiers |
Finds the record describing this class, resolves its outer class name and keeps its inner_class_access_flags |
Attribute::MethodParameters |
MethodModel::parameters |
name_index becomes name: Option<String> (zero means unnamed), flags become ParameterModifier |
Attribute::EnclosingMethod |
EnclosingMethodInfo |
Two indexes become an enclosing class name plus an Option method name and descriptor, since JVMS §4.7.7 allows method_index to be zero |
Attribute::Exceptions |
MethodModel::exceptions |
exception_index_table: Vec<u16> becomes Vec<String> of thrown class names, in declaration order |
Attribute::SourceFile |
ClassModel::source_file |
Index becomes Option<String> |
Attribute::NestHost |
Attributes::get_nest_host |
Host class index becomes Option<String>; None means the class hosts its own nest |
Attribute::NestMembers |
Attributes::get_nest_members |
classes: Vec<u16> becomes Option<Vec<String>> of member class names |
Attribute::PermittedSubclasses |
Attributes::get_permitted_subclasses |
classes: Vec<u16> becomes Option<Vec<String>>; None (not sealed) is kept apart from an empty list |
Attribute::RuntimeVisibleAnnotations |
runtime_visible_annotations: HashSet<String> |
Annotation type indexes become type names; the raw bytes stay available as annotations_raw for reflection |
ClassFlags |
ClassModifier |
Same bits, owned by this crate so jclassfile stays private |
MethodFlags |
MethodModifier |
Same bits, plus MethodModel::is_polymorphic_signature() for the MethodHandle case |
FieldFlags |
FieldModifier |
Same bits, plus FieldModel::is_static() for the common case |
NestedClassFlags |
NestedClassModifier |
Same bits; this is where private/protected/static live for a nested class, since ClassModifier cannot express them |
MethodParameterFlags |
ParameterModifier |
Same bits (Final, Synthetic, Mandated) |
Not surfaced
Because jclassfile is a private dependency, this crate cannot hand you a raw Attribute as an
escape hatch: an attribute is reachable only once it has been modelled here. Anything below is
parsed by jclassfile and held in Attributes, but has no accessor yet. Each is a small, additive
change when a consumer needs it, so treat this as a roadmap rather than a limitation.
Needed by a JVM eventually, roughly in that order:
| Attribute | What it unblocks |
|---|---|
ConstantValue |
Static final initializers. JVMS §5.4.2 has the JVM set these during preparation and javac emits no <clinit> store for them, so today they are visible only because javac inlines compile-time constants at their use sites; a reflective field read would see the default value |
Record |
Reflection over record components |
Signature |
Generic type information for reflection |
Deliberately out of scope for now: StackMapTable. It exists for the bytecode verifier, so it is
worth modelling the day there is one, and jclassfile already parses it into Vec<StackMapFrame>
for that day. The same goes for SourceDebugExtension, LocalVariableTypeTable, the
RuntimeInvisible* and type-annotation variants, and the Module* family.
magic is never surfaced: it is 0xCAFEBABE or parsing already failed, so it carries no
information.
Status
Early development. This crate is extracted from the rusty-jvm project, where this postprocessing layer has been exercised against the whole OpenJDK standard library.
Contributing
Contributions are welcome! Feel free to open an issue or submit a pull request.
License
This project is licensed under the MIT License – see the LICENSE file for details.