0
# Java Class File Processing
1

2
Complete Java class file parsing, analysis, and manipulation capabilities for OSGi bundle tooling. This package provides comprehensive support for reading and writing Java bytecode, analyzing class file structures, and extracting metadata for OSGi bundle processing.
3

4
## Capabilities
5

6
### ClassFile Parsing
7

8
Parse complete Java class files from DataInput streams with full validation and error handling.
9

10
```java { .api }
11
/**
12
 * Parse a Java class file from a DataInput stream
13
 * @param in DataInput stream containing class file bytes
14
 * @return Complete ClassFile representation
15
 * @throws IOException if the class file is malformed or I/O error occurs
16
 */
17
public static ClassFile parseClassFile(DataInput in) throws IOException;
18

19
/**
20
 * Represents a complete Java class file structure
21
 */
22
public class ClassFile extends ElementInfo {
23
    /** Minor version number of the class file format */
24
    public final int minor_version;
25
    /** Major version number of the class file format */
26
    public final int major_version;
27
    /** Constant pool containing all symbolic references */
28
    public final ConstantPool constant_pool;
29
    /** Fully qualified name of this class */
30
    public final String this_class;
31
    /** Fully qualified name of the superclass (null for java.lang.Object) */
32
    public final String super_class;
33
    /** Array of implemented interface names */
34
    public final String[] interfaces;
35
    /** Array of field information structures */
36
    public final FieldInfo[] fields;
37
    /** Array of method information structures */
38
    public final MethodInfo[] methods;
39
    
40
    /**
41
     * Constructor for creating ClassFile instances
42
     */
43
    public ClassFile(int minor_version, int major_version, ConstantPool constant_pool,
44
                     int access_flags, String this_class, String super_class,
45
                     String[] interfaces, FieldInfo[] fields, MethodInfo[] methods,
46
                     Attribute[] attributes);
47
    
48
    /**
49
     * Write this class file to a DataOutput stream
50
     * @param out DataOutput stream to write to
51
     * @throws IOException if I/O error occurs
52
     */
53
    public void write(DataOutput out) throws IOException;
54
}
55
```
56

57
**Usage Example:**
58

59
```java
60
import aQute.bnd.classfile.ClassFile;
61
import java.io.DataInputStream;
62
import java.nio.file.Files;
63
import java.nio.file.Paths;
64

65
// Parse a class file
66
try (DataInputStream in = new DataInputStream(Files.newInputStream(Paths.get("MyClass.class")))) {
67
    ClassFile classFile = ClassFile.parseClassFile(in);
68
    
69
    System.out.println("Class name: " + classFile.this_class);
70
    System.out.println("Superclass: " + classFile.super_class);
71
    System.out.println("Version: " + classFile.major_version + "." + classFile.minor_version);
72
    System.out.println("Method count: " + classFile.methods.length);
73
    System.out.println("Field count: " + classFile.fields.length);
74
    
75
    // Analyze interfaces
76
    for (String iface : classFile.interfaces) {
77
        System.out.println("Implements: " + iface);
78
    }
79
}
80
```
81

82
### Constant Pool Operations
83

84
Access and manipulate the constant pool that contains all symbolic references used by the class file.
85

86
```java { .api }
87
/**
88
 * Represents the constant pool of a Java class file
89
 */
90
public class ConstantPool {
91
    /** The actual pool entries */
92
    public final Object[] pool;
93
    
94
    /**
95
     * Constructor for creating constant pool instances
96
     * @param pool Array of constant pool entries
97
     */
98
    public ConstantPool(Object[] pool);
99
    
100
    /** Get the number of entries in the constant pool */
101
    public int size();
102
    
103
    /** Get a constant pool entry by index */
104
    public Object entry(int index);
105
    
106
    /** Get the constant pool tag for an entry */
107
    public int tag(int index);
108
    
109
    /** Get a UTF-8 string from the constant pool */
110
    public String utf8(int index);
111
    
112
    /** Get a class name from the constant pool */
113
    public String className(int index);
114
    
115
    /** Get a module name from the constant pool */  
116
    public String moduleName(int index);
117
    
118
    /** Get a package name from the constant pool */
119
    public String packageName(int index);
120
    
121
    /** Get a string constant from the constant pool */
122
    public String string(int index);
123
    
124
    /**
125
     * Read constant pool from DataInput
126
     * @param in DataInput stream
127
     * @return ConstantPool instance
128
     * @throws IOException if I/O error occurs
129
     */
130
    public static ConstantPool read(DataInput in) throws IOException;
131
    
132
    /**
133
     * Write constant pool to DataOutput
134
     * @param out DataOutput stream
135
     * @throws IOException if I/O error occurs
136
     */
137
    public void write(DataOutput out) throws IOException;
138
}
139
```
140

141
### Field Information
142

143
Access field metadata including names, descriptors, access flags, and attributes.
144

145
```java { .api }
146
/**
147
 * Represents field information in a class file
148
 */
149
public class FieldInfo extends MemberInfo {
150
    /**
151
     * Constructor for creating field information
152
     * @param access_flags Field access flags (public, private, static, etc.)
153
     * @param name Field name
154
     * @param descriptor Field type descriptor
155
     * @param attributes Field attributes
156
     */
157
    public FieldInfo(int access_flags, String name, String descriptor, Attribute[] attributes);
158
    
159
    /**
160
     * Read field info from DataInput
161
     * @param in DataInput stream
162
     * @param constant_pool Associated constant pool
163
     * @return FieldInfo instance
164
     * @throws IOException if I/O error occurs
165
     */
166
    public static FieldInfo read(DataInput in, ConstantPool constant_pool) throws IOException;
167
}
168
```
169

170
### Method Information
171

172
Access method metadata including signatures, access flags, bytecode, and exception handling.
173

174
```java { .api }
175
/**
176
 * Represents method information in a class file
177
 */
178
public class MethodInfo extends MemberInfo {
179
    /**
180
     * Constructor for creating method information
181
     * @param access_flags Method access flags (public, private, static, etc.)
182
     * @param name Method name
183
     * @param descriptor Method signature descriptor
184
     * @param attributes Method attributes (Code, Exceptions, etc.)
185
     */
186
    public MethodInfo(int access_flags, String name, String descriptor, Attribute[] attributes);
187
    
188
    /**
189
     * Read method info from DataInput
190
     * @param in DataInput stream  
191
     * @param constant_pool Associated constant pool
192
     * @return MethodInfo instance
193
     * @throws IOException if I/O error occurs
194
     */
195
    public static MethodInfo read(DataInput in, ConstantPool constant_pool) throws IOException;
196
}
197
```
198

199
### Class File Attributes
200

201
Access various class file attributes including source file, line numbers, annotations, and signatures.
202

203
```java { .api }
204
/**
205
 * Base interface for all class file attributes
206
 */
207
public interface Attribute {
208
    /** Get the attribute name */
209
    String name();
210
    
211
    /** Get the attribute length */
212
    int attribute_length();
213
    
214
    /** Write the attribute to DataOutput */
215
    void write(DataOutput out, ConstantPool constant_pool) throws IOException;
216
    
217
    /**
218
     * Read attributes from DataInput
219
     * @param in DataInput stream
220
     * @param constant_pool Associated constant pool
221
     * @return Array of attributes
222
     * @throws IOException if I/O error occurs
223
     */
224
    static Attribute[] readAttributes(DataInput in, ConstantPool constant_pool) throws IOException;
225
}
226

227
/**
228
 * Code attribute containing method bytecode
229
 */
230
public class CodeAttribute implements Attribute {
231
    public final int max_stack;
232
    public final int max_locals;
233
    public final byte[] code;
234
    public final ExceptionHandler[] exception_table;
235
    public final Attribute[] attributes;
236
}
237

238
/**
239
 * SourceFile attribute containing source filename
240
 */
241
public class SourceFileAttribute implements Attribute {
242
    public final String sourcefile;
243
}
244

245
/**
246
 * Signature attribute for generic type information
247
 */
248
public class SignatureAttribute implements Attribute {
249
    public final String signature;
250
}
251

252
/**
253
 * Runtime visible annotations attribute
254
 */
255
public class RuntimeVisibleAnnotationsAttribute implements Attribute {
256
    public final AnnotationInfo[] annotations;
257
}
258
```
259

260
### Annotation Processing
261

262
Process Java annotations embedded in class files for OSGi metadata extraction.
263

264
```java { .api }
265
/**
266
 * Represents annotation information in class files
267
 */
268
public class AnnotationInfo {
269
    /** Annotation type descriptor */
270
    public final String type;
271
    /** Annotation element-value pairs */
272
    public final ElementValueInfo[] values;
273
    
274
    /**
275
     * Constructor for annotation information
276
     * @param type Annotation type descriptor
277
     * @param values Element-value pairs
278
     */
279
    public AnnotationInfo(String type, ElementValueInfo[] values);
280
    
281
    /**
282
     * Read annotation from DataInput
283
     * @param in DataInput stream
284
     * @param constant_pool Associated constant pool
285
     * @return AnnotationInfo instance
286
     * @throws IOException if I/O error occurs
287
     */
288
    public static AnnotationInfo read(DataInput in, ConstantPool constant_pool) throws IOException;
289
    
290
    /**
291
     * Write annotation to DataOutput
292
     * @param out DataOutput stream
293
     * @param constant_pool Associated constant pool
294
     * @throws IOException if I/O error occurs
295
     */
296
    public void write(DataOutput out, ConstantPool constant_pool) throws IOException;
297
}
298
```
299

300
## Constant Pool Types
301

302
The constant pool supports all standard Java constant types:
303

304
- `CONSTANT_Utf8` - UTF-8 encoded strings
305
- `CONSTANT_Integer` - Integer literals
306
- `CONSTANT_Float` - Float literals  
307
- `CONSTANT_Long` - Long literals
308
- `CONSTANT_Double` - Double literals
309
- `CONSTANT_Class` - Class references
310
- `CONSTANT_String` - String literals
311
- `CONSTANT_Fieldref` - Field references
312
- `CONSTANT_Methodref` - Method references
313
- `CONSTANT_InterfaceMethodref` - Interface method references
314
- `CONSTANT_NameAndType` - Name and type descriptors
315
- `CONSTANT_MethodHandle` - Method handles (Java 7+)
316
- `CONSTANT_MethodType` - Method types (Java 7+)
317
- `CONSTANT_InvokeDynamic` - Dynamic method invocation (Java 7+)
318
- `CONSTANT_Module` - Module references (Java 9+)
319
- `CONSTANT_Package` - Package references (Java 9+)
320

321
## Error Handling
322

323
All parsing operations can throw `IOException` for malformed class files or I/O errors. The library provides comprehensive validation to ensure class file integrity and compatibility with different Java versions.
324

325
**Usage Example:**
326

327
```java
328
try {
329
    ClassFile classFile = ClassFile.parseClassFile(inputStream);
330
    // Process class file...
331
} catch (IOException e) {
332
    System.err.println("Failed to parse class file: " + e.getMessage());
333
    // Handle error appropriately
334
}
335
```