the class file

the picture

you know how .class files feel like opaque blobs that only the JVM is allowed to look at? they're not. they're one of the most readable binary formats around, and javac's output for a tiny class fits on one screen.

think of it like a recipe book with a glossary in the front. the glossary (the constant pool) lists every ingredient and every technique once, numbered. the recipes themselves just say "use #7" instead of spelling it out. that's why the pool is most of the file: the rest is mostly numbers pointing back into it.

here's the class:

public class Point {
    int x;
    int getX() { return x; }
}

compiled with javac -g:source Point.java on jdk 25 (that flag keeps the file name but skips line numbers, so the file stays tiny). the result is 224 bytes. here's every one of them.

see the strip on top? 122 of the 224 bytes are the constant pool. the actual code (both methods' instructions) is 10 bytes.

the shape

the JVM spec defines the whole file as one struct. u2 and u4 are unsigned 2 and 4 byte numbers, big-endian:

ClassFile {
    u4             magic;
    u2             minor_version;
    u2             major_version;
    u2             constant_pool_count;
    cp_info        constant_pool[constant_pool_count-1];
    u2             access_flags;
    u2             this_class;
    u2             super_class;
    u2             interfaces_count;
    u2             interfaces[interfaces_count];
    u2             fields_count;
    field_info     fields[fields_count];
    u2             methods_count;
    method_info    methods[methods_count];
    u2             attributes_count;
    attribute_info attributes[attributes_count];
}

no padding, no alignment, no offsets table. the only way to find the methods is to walk the pool entry by entry (each tag tells you how long that entry is). that's what the JVM's class file parser does, and it's what javap -v prints for you:

public class Point
  minor version: 0
  major version: 69
  flags: (0x0021) ACC_PUBLIC, ACC_SUPER
  this_class: #8                          // Point
  super_class: #2                         // java/lang/Object
  interfaces: 0, fields: 1, methods: 2, attributes: 1
Constant pool:
   #1 = Methodref          #2.#3          // java/lang/Object."<init>":()V
   #2 = Class              #4             // java/lang/Object
   #3 = NameAndType        #5:#6          // "<init>":()V
   #4 = Utf8               java/lang/Object
   ...
   #7 = Fieldref           #8.#9          // Point.x:I

the constant pool is a graph

the pool isn't a flat list of strings. entries point at other entries. getfield #7 in getX names a field, and resolving what that means takes four hops:

this indirection is why linking is lazy. the bytes say "the field x of type I in class Point", by name. the first time getfield #7 runs, the JVM looks that up, finds the field's real byte offset inside a Point object, and caches the answer in the runtime constant pool. after that it's a plain memory read. more in class loading.

descriptors

types in a class file are written as compact strings called descriptors. you just saw I and ()V. the full alphabet:

B C D F I J S Z

byte, char, double, float, int, long, short, boolean. (J and Z because L and B were taken.)

Ljava/lang/String;

a class type: L, the internal name with slashes, a semicolon.

[I · [[Ljava/lang/Object;

arrays: one [ per dimension.

V

void. only allowed as a return type.

(ILjava/lang/String;)Z

a method: parameters in parentheses, then the return type. this one is boolean m(int, String).

notice what's not in a descriptor: generic type arguments (List<String> is just Ljava/util/List;, see type erasure) and parameter names. generics survive only in an optional Signature attribute, for reflection and the compiler.

versions

bytes 6 and 7 are the major version. each java release bumps it by one, and a JVM refuses anything newer than itself.

# Point.class from above, with byte 7 changed from 0x45 (69) to 0x46 (70)
$ java -cp . Run

writing one without javac

since java 24, the JDK can read and write class files itself: the Class-File API (java.lang.classfile, JEP 484) java 24+. here's a class built from nothing, loaded and called, no source code involved:

void main() throws Throwable {
    byte[] bytes = ClassFile.of().build(ClassDesc.of("Answer"), cls -> cls
        .withMethodBody("get", MethodTypeDesc.of(ConstantDescs.CD_int),
            ClassFile.ACC_PUBLIC | ClassFile.ACC_STATIC,
            code -> code.bipush(42).ireturn()));
 
    IO.println(HexFormat.of().formatHex(bytes, 0, 4));
    Class<?> answer = MethodHandles.lookup().defineClass(bytes);
    IO.println(answer.getMethod("get").invoke(null));
}

cafebabe
42

on jdk 25 that's a 106-byte class: magic, version 69, a constant pool, one method whose code is bipush 42, ireturn. frameworks that generate classes at runtime (mocking libraries, proxies, ORMs) have always needed a library like ASM or ByteBuddy for this. the JDK itself has been moving its own class generation (lambdas, proxies, records) off an internal copy of ASM and onto this API.