0
# Type Signature Parsing
1

2
Complete Java generic signature parsing and resolution system supporting all aspects of the Java generic type system including wildcards, bounds, and complex type hierarchies. This module provides comprehensive support for parsing and manipulating Java's generic type signatures as used in class files.
3

4
## Capabilities
5

6
### Signature Object Model
7

8
Java generic signature representation using structured objects that model the complete generic type system including type parameters, bounds, wildcards, and complex inheritance hierarchies.
9

10
```java { .api }
11
/**
12
 * Base interface for all signature types
13
 */
14
public interface Signature {
15
    // Marker interface for all signature objects
16
}
17

18
/**
19
 * Base interface for all Java type signatures
20
 */
21
public interface JavaTypeSignature extends Result {
22
    /**
23
     * Parse a Java type signature from string representation
24
     * @param signature The signature string to parse
25
     * @return Parsed JavaTypeSignature instance
26
     */
27
    @SuppressWarnings("unchecked")
28
    static <T extends JavaTypeSignature> T of(String signature);
29
}
30

31
/**
32
 * Interface for reference type signatures (classes, interfaces, arrays, type variables)
33
 */
34
public interface ReferenceTypeSignature extends JavaTypeSignature {
35
    // Marker interface for reference types
36
}
37
```
38

39
**Usage Examples:**
40

41
```java
42
import aQute.bnd.signatures.ClassSignature;
43
import aQute.bnd.signatures.MethodSignature;
44
import aQute.bnd.signatures.FieldSignature;
45

46
// Parse class signature with generics
47
ClassSignature classSig = ClassSignature.of(
48
    "<T:Ljava/lang/Object;>Ljava/lang/Object;Ljava/util/List<TT;>;"
49
);
50
System.out.println("Type parameters: " + classSig.typeParameters.length);
51

52
// Parse method signature
53
MethodSignature methodSig = MethodSignature.of(
54
    "<U:Ljava/lang/Object;>(TT;TU;)Ljava/util/Map<TT;TU;>;"
55
);
56
System.out.println("Parameters: " + methodSig.parameters.length);
57

58
// Parse field signature
59
FieldSignature fieldSig = FieldSignature.of("Ljava/util/List<Ljava/lang/String;>;");
60

61
// Access signature components
62
System.out.println("Super class: " + classSig.superClass.binary);
63
```
64

65
### Class Signatures
66

67
Representation of class-level generic signatures including type parameters and inheritance.
68

69
```java { .api }
70
/**
71
 * Represents class-level generic signatures
72
 */
73
public class ClassSignature implements Signature {
74
    /**
75
     * Formal type parameters declared on the class
76
     * Example: &lt;T, U extends Number&gt; results in two TypeParameter objects
77
     */
78
    public final TypeParameter[] typeParameters;
79
    
80
    /**
81
     * Generic signature of the superclass
82
     * Example: extends AbstractList&lt;T&gt;
83
     */
84
    public final ClassTypeSignature superClass;
85
    
86
    /**
87
     * Generic signatures of implemented interfaces
88
     * Example: implements List&lt;T&gt;, Serializable
89
     */
90
    public final ClassTypeSignature[] superInterfaces;
91
    
92
    /**
93
     * Parse class signature from string
94
     * @param signature Generic signature string from class file
95
     * @return Parsed ClassSignature object
96
     */
97
    public static ClassSignature of(String signature);
98
    
99
    public ClassSignature(TypeParameter[] typeParameters,
100
                         ClassTypeSignature superClass,
101
                         ClassTypeSignature[] superInterfaces);
102
}
103

104
/**
105
 * Represents type parameters in generic signatures
106
 */
107
public class TypeParameter {
108
    /**
109
     * Name of the type parameter
110
     * Example: "T" in &lt;T extends Number&gt;
111
     */
112
    public final String identifier;
113
    
114
    /**
115
     * Class bound for the type parameter
116
     * Example: Number in &lt;T extends Number&gt;
117
     */
118
    public final ReferenceTypeSignature classBound;
119
    
120
    /**
121
     * Interface bounds for the type parameter
122
     * Example: Serializable in &lt;T extends Number & Serializable&gt;
123
     */
124
    public final List<ReferenceTypeSignature> interfaceBounds;
125
    
126
    public TypeParameter(String identifier, ReferenceTypeSignature classBound, List<ReferenceTypeSignature> interfaceBounds);
127
}
128
```
129

130
### Method Signatures
131

132
Representation of method-level generic signatures including parameters and return types.
133

134
```java { .api }
135
/**
136
 * Represents method-level generic signatures
137
 */
138
public class MethodSignature implements Signature {
139
    /**
140
     * Formal type parameters declared on the method
141
     * Example: &lt;U&gt; in &lt;U&gt; List&lt;U&gt; transform(Function&lt;T, U&gt; mapper)
142
     */
143
    public final TypeParameter[] typeParameters;
144
    
145
    /**
146
     * Parameter type signatures
147
     * Ordered list of parameter types including generics
148
     */
149
    public final JavaTypeSignature[] parameterTypes;
150
    
151
    /**
152
     * Return type signature
153
     * Either JavaTypeSignature for typed returns or VoidDescriptor for void
154
     */
155
    public final Result resultType;
156
    
157
    /**
158
     * Exception signatures for throws declarations
159
     * Generic signatures of declared exceptions
160
     */
161
    public final ThrowsSignature[] throwTypes;
162
    
163
    /**
164
     * Parse method signature from string
165
     * @param signature Generic signature string from method
166
     * @return Parsed MethodSignature object
167
     */
168
    public static MethodSignature of(String signature);
169
    
170
    public MethodSignature(TypeParameter[] typeParameters,
171
                          JavaTypeSignature[] parameterTypes,
172
                          Result resultType,
173
                          ThrowsSignature[] throwTypes);
174
}
175

176
/**
177
 * Represents void return type
178
 */
179
public enum VoidDescriptor implements Result {
180
    V;
181
}
182
```
183

184
### Field Signatures
185

186
Representation of field-level generic signatures.
187

188
```java { .api }
189
/**
190
 * Represents field-level generic signatures
191
 */
192
public class FieldSignature implements Signature {
193
    /**
194
     * Type signature of the field
195
     * Generic type information for the field
196
     */
197
    public final ReferenceTypeSignature referenceTypeSignature;
198
    
199
    public FieldSignature(ReferenceTypeSignature referenceTypeSignature);
200
}
201
```
202

203
### Type Signatures
204

205
Core type signature interfaces and implementations.
206

207
```java { .api }
208
/**
209
 * Base interface for all Java type signatures
210
 */
211
public interface JavaTypeSignature extends Signature {
212
    // Marker interface for all Java types (primitive and reference)
213
}
214

215
/**
216
 * Interface for reference type signatures (classes, interfaces, arrays, type variables)
217
 */
218
public interface ReferenceTypeSignature extends JavaTypeSignature {
219
    // Marker interface for reference types
220
}
221

222
/**
223
 * Interface for exception signatures in throws clauses
224
 */
225
public interface ThrowsSignature {
226
    // Marker interface for throwable types
227
}
228

229
/**
230
 * Enumeration of Java primitive types in signatures
231
 */
232
public enum BaseType implements JavaTypeSignature {
233
    B, // byte
234
    C, // char
235
    D, // double
236
    F, // float
237
    I, // int
238
    J, // long
239
    S, // short
240
    Z; // boolean
241
}
242

243
/**
244
 * Represents array type signatures
245
 */
246
public class ArrayTypeSignature implements ReferenceTypeSignature {
247
    /**
248
     * Component type of the array (can be primitive or reference)
249
     */
250
    public final JavaTypeSignature javaTypeSignature;
251
    
252
    public ArrayTypeSignature(JavaTypeSignature javaTypeSignature);
253
}
254

255
/**
256
 * Represents class type signatures with generic parameters
257
 */
258
public class ClassTypeSignature implements ReferenceTypeSignature, ThrowsSignature {
259
    /**
260
     * Package name portion of the class
261
     * Example: "java/util/" for java.util.List
262
     */
263
    public final String packageSpecifier;
264
    
265
    /**
266
     * Simple class type signatures for the class hierarchy
267
     * Handles nested classes and their generic parameters
268
     */
269
    public final List<SimpleClassTypeSignature> simpleClassTypeSignatures;
270
    
271
    public ClassTypeSignature(String packageSpecifier, List<SimpleClassTypeSignature> simpleClassTypeSignatures);
272
}
273

274
/**
275
 * Represents type variable signatures
276
 */
277
public class TypeVariableSignature implements ReferenceTypeSignature, ThrowsSignature {
278
    /**
279
     * Name of the type variable
280
     * Example: "T" in List&lt;T&gt;
281
     */
282
    public final String identifier;
283
    
284
    public TypeVariableSignature(String identifier);
285
}
286
```
287

288
### Simple Class Types and Type Arguments
289

290
Detailed representation of class types and their generic arguments.
291

292
```java { .api }
293
/**
294
 * Simple class type signature without package qualification
295
 */
296
public class SimpleClassTypeSignature {
297
    /**
298
     * Simple name of the class
299
     * Example: "List" for java.util.List&lt;String&gt;
300
     */
301
    public final String identifier;
302
    
303
    /**
304
     * Type arguments for generic instantiation
305
     * Example: [String] for List&lt;String&gt;
306
     */
307
    public final List<TypeArgument> typeArguments;
308
    
309
    public SimpleClassTypeSignature(String identifier, List<TypeArgument> typeArguments);
310
}
311

312
/**
313
 * Represents type arguments in generic signatures
314
 */
315
public class TypeArgument {
316
    /**
317
     * Wildcard indicator for the type argument
318
     * NONE for concrete types, EXTENDS/SUPER for wildcards
319
     */
320
    public final WildcardIndicator wildcardIndicator;
321
    
322
    /**
323
     * Reference type signature for the argument
324
     * The actual type or bound for the argument
325
     */
326
    public final ReferenceTypeSignature referenceTypeSignature;
327
    
328
    public TypeArgument(WildcardIndicator wildcardIndicator, ReferenceTypeSignature referenceTypeSignature);
329
}
330

331
/**
332
 * Wildcard indicators for generic type arguments
333
 */
334
public enum WildcardIndicator {
335
    NONE,    // T (concrete type)
336
    EXTENDS, // ? extends T
337
    SUPER;   // ? super T
338
}
339
```
340

341
### Signature Resolution
342

343
Classes for resolving generic signatures in inheritance contexts.
344

345
```java { .api }
346
/**
347
 * Resolves class signatures in inheritance hierarchy
348
 */
349
public class ClassResolver {
350
    /**
351
     * Create resolver for class signature
352
     * @param signature Class signature to resolve
353
     */
354
    public ClassResolver(ClassSignature signature);
355
    
356
    // Resolution methods for type variables and bounds
357
}
358

359
/**
360
 * Resolves field signatures in class context
361
 */
362
public class FieldResolver extends ClassResolver {
363
    /**
364
     * Create resolver for field signature
365
     * @param classSignature Containing class signature
366
     * @param fieldSignature Field signature to resolve
367
     */
368
    public FieldResolver(ClassSignature classSignature, FieldSignature fieldSignature);
369
}
370

371
/**
372
 * Resolves method signatures in class context
373
 */
374
public class MethodResolver extends ClassResolver {
375
    /**
376
     * Create resolver for method signature
377
     * @param classSignature Containing class signature
378
     * @param methodSignature Method signature to resolve
379
     */
380
    public MethodResolver(ClassSignature classSignature, MethodSignature methodSignature);
381
}
382
```
383

384
**Usage Examples:**
385

386
```java
387
import aQute.bnd.signatures.*;
388

389
// Parse complex class signature
390
String complexSig = "<T:Ljava/lang/Number;U::Ljava/io/Serializable;>" +
391
                   "Ljava/util/AbstractList<TT;>;" +
392
                   "Ljava/util/List<TT;>;Ljava/lang/Cloneable;";
393

394
ClassSignature parsed = Signatures.parseClassSignature(complexSig);
395

396
// Examine type parameters
397
for (TypeParameter param : parsed.formalTypeParameters) {
398
    System.out.println("Type parameter: " + param.identifier);
399
    if (param.classBound != null) {
400
        System.out.println("  Class bound: " + param.classBound);
401
    }
402
    for (ReferenceTypeSignature bound : param.interfaceBounds) {
403
        System.out.println("  Interface bound: " + bound);
404
    }
405
}
406

407
// Parse method with wildcards
408
String methodSig = "<U:Ljava/lang/Object;>" +
409
                  "(Ljava/util/List<+TT;>;Ljava/util/Map<-TU;*>;)" +
410
                  "Ljava/util/Set<TU;>;";
411

412
MethodSignature method = Signatures.parseMethodSignature(methodSig);
413
System.out.println("Method type parameters: " + method.formalTypeParameters.size());
414
System.out.println("Parameters: " + method.parameters.size());
415

416
// Resolve in inheritance context
417
ClassResolver resolver = new ClassResolver(parsed);
418
// Use resolver to resolve type variables in specific contexts
419
```
420

421
## Base Interfaces
422

423
```java { .api }
424
/**
425
 * Base interface for all signature types
426
 */
427
public interface Signature {
428
    // Marker interface for all signature objects
429
}
430

431
/**
432
 * Result interface for method return types
433
 * Implemented by JavaTypeSignature and VoidDescriptor
434
 */
435
public interface Result {
436
    // Marker interface for method results
437
}
438
```