0
# Java Generic Signatures
1

2
Comprehensive processing and analysis of Java generic type signatures for advanced type introspection and OSGi metadata generation. This package handles the complete parsing and manipulation of Java's generic signature format as defined in the JVM specification.
3

4
## Capabilities
5

6
### Signature Base Interface
7

8
All signature types implement the base Signature interface for consistent processing.
9

10
```java { .api }
11
/**
12
 * Base interface for all Java signature types
13
 */
14
public interface Signature {
15
    /**
16
     * Get all erased binary references from this signature
17
     * Used for dependency analysis and OSGi import generation
18
     * @return Set of binary class names referenced by this signature
19
     */
20
    Set<String> erasedBinaryReferences();
21
}
22
```
23

24
### Class Signatures
25

26
Parse and manipulate class-level generic signatures including type parameters and bounds.
27

28
```java { .api }
29
/**
30
 * Represents a class signature with generic type parameters
31
 */
32
public class ClassSignature implements Signature {
33
    /** Type parameters declared by this class (e.g., <T, U extends Number>) */
34
    public final TypeParameter[] typeParameters;
35
    /** Signature of the superclass */
36
    public final ClassTypeSignature superClass;
37
    /** Signatures of implemented interfaces */
38
    public final ClassTypeSignature[] superInterfaces;
39
    
40
    /**
41
     * Constructor for class signatures
42
     * @param typeParameters Generic type parameters
43
     * @param superClass Superclass signature
44
     * @param superInterfaces Interface signatures
45
     */
46
    public ClassSignature(TypeParameter[] typeParameters, ClassTypeSignature superClass, 
47
                         ClassTypeSignature[] superInterfaces);
48
    
49
    /**
50
     * Parse a class signature from its string representation
51
     * @param signature Raw signature string from class file
52
     * @return Parsed ClassSignature instance
53
     * @throws IllegalArgumentException if signature is malformed
54
     */
55
    public static ClassSignature of(String signature);
56
    
57
    @Override
58
    public Set<String> erasedBinaryReferences();
59
    
60
    @Override
61
    public boolean equals(Object obj);
62
    
63
    @Override
64
    public int hashCode();
65
    
66
    @Override
67
    public String toString();
68
}
69
```
70

71
**Usage Example:**
72

73
```java
74
import aQute.bnd.signatures.ClassSignature;
75

76
// Parse a generic class signature
77
// Example: "class MyClass<T extends Number> extends ArrayList<T> implements Comparable<T>"
78
String signatureString = "<T:Ljava/lang/Number;>Ljava/util/ArrayList<TT;>;Ljava/lang/Comparable<TT;>;";
79
ClassSignature signature = ClassSignature.of(signatureString);
80

81
// Access type parameters
82
for (TypeParameter param : signature.typeParameters) {
83
    System.out.println("Type parameter: " + param.identifier);
84
    // Access bounds if any
85
}
86

87
// Access superclass
88
System.out.println("Superclass: " + signature.superClass);
89

90
// Access interfaces
91
for (ClassTypeSignature iface : signature.superInterfaces) {
92
    System.out.println("Interface: " + iface);
93
}
94

95
// Get all referenced types for dependency analysis
96
Set<String> references = signature.erasedBinaryReferences();
97
for (String ref : references) {
98
    System.out.println("References: " + ref);
99
}
100
```
101

102
### Method Signatures
103

104
Parse method-level generic signatures including type parameters, parameter types, return types, and exception specifications.
105

106
```java { .api }
107
/**
108
 * Represents a method signature with generic information
109
 */
110
public class MethodSignature implements Signature {
111
    /** Type parameters declared by this method (e.g., <T, U>) */
112
    public final TypeParameter[] typeParameters;
113
    /** Parameter type signatures */
114
    public final JavaTypeSignature[] parameterTypes;
115
    /** Return type signature */
116
    public final Result resultType;
117
    /** Exception type signatures */
118
    public final ThrowsSignature[] throwTypes;
119
    
120
    /**
121
     * Constructor for method signatures
122
     * @param typeParameters Generic type parameters
123
     * @param parameterTypes Parameter type signatures
124
     * @param resultType Return type signature
125
     * @param throwTypes Exception signatures
126
     */
127
    public MethodSignature(TypeParameter[] typeParameters, JavaTypeSignature[] parameterTypes,
128
                          Result resultType, ThrowsSignature[] throwTypes);
129
    
130
    /**
131
     * Parse a method signature from its string representation
132
     * @param signature Raw signature string from method
133
     * @return Parsed MethodSignature instance
134
     */
135
    public static MethodSignature of(String signature);
136
    
137
    @Override
138
    public Set<String> erasedBinaryReferences();
139
}
140
```
141

142
**Usage Example:**
143

144
```java
145
// Parse a generic method signature
146
// Example: "<T> List<T> process(T input, Class<? extends T> type) throws ProcessingException"
147
String methodSig = "<T:Ljava/lang/Object;>(TT;Ljava/lang/Class<+TT;>;)Ljava/util/List<TT;>;^Lcom/example/ProcessingException;";
148
MethodSignature signature = MethodSignature.of(methodSig);
149

150
// Access method type parameters
151
for (TypeParameter param : signature.typeParameters) {
152
    System.out.println("Method type parameter: " + param.identifier);
153
}
154

155
// Access parameter types
156
for (JavaTypeSignature param : signature.parameterTypes) {
157
    System.out.println("Parameter type: " + param);
158
}
159

160
// Access return type
161
System.out.println("Return type: " + signature.resultType);
162

163
// Access exceptions
164
for (ThrowsSignature exception : signature.throwTypes) {
165
    System.out.println("Throws: " + exception);
166
}
167
```
168

169
### Field Signatures
170

171
Parse field-level generic signatures for fields with parameterized types.
172

173
```java { .api }
174
/**
175
 * Represents a field signature with generic type information
176
 */
177
public class FieldSignature implements Signature {
178
    /** The type signature of the field */
179
    public final ReferenceTypeSignature type;
180
    
181
    /**
182
     * Constructor for field signatures
183
     * @param type Field type signature
184
     */
185
    public FieldSignature(ReferenceTypeSignature type);
186
    
187
    /**
188
     * Parse a field signature from its string representation
189
     * @param signature Raw signature string from field
190
     * @return Parsed FieldSignature instance
191
     */
192
    public static FieldSignature of(String signature);
193
    
194
    @Override
195
    public Set<String> erasedBinaryReferences();
196
}
197
```
198

199
### Type Parameters
200

201
Represent generic type parameters with their bounds and constraints.
202

203
```java { .api }
204
/**
205
 * Represents a generic type parameter with its bounds
206
 */
207
public class TypeParameter {
208
    /** The identifier name of the type parameter (e.g., "T", "K", "V") */
209
    public final String identifier;
210
    /** Class bound (extends constraint) - may be null */
211
    public final ReferenceTypeSignature classBound;
212
    /** Interface bounds (additional extends constraints) */
213
    public final ReferenceTypeSignature[] interfaceBounds;
214
    
215
    /**
216
     * Constructor for type parameters
217
     * @param identifier Type parameter name
218
     * @param classBound Class bound (extends clause)
219
     * @param interfaceBounds Interface bounds
220
     */
221
    public TypeParameter(String identifier, ReferenceTypeSignature classBound, 
222
                        ReferenceTypeSignature[] interfaceBounds);
223
}
224
```
225

226
**Usage Example:**
227

228
```java
229
// For a type parameter like "<T extends Number & Comparable<T>>"
230
TypeParameter typeParam = new TypeParameter(
231
    "T",
232
    numberClassSignature,  // extends Number
233
    new ReferenceTypeSignature[] { comparableInterfaceSignature } // & Comparable<T>
234
);
235

236
System.out.println("Type parameter: " + typeParam.identifier);
237
if (typeParam.classBound != null) {
238
    System.out.println("Extends: " + typeParam.classBound);
239
}
240
for (ReferenceTypeSignature bound : typeParam.interfaceBounds) {
241
    System.out.println("Also extends: " + bound);
242
}
243
```
244

245
### Type Signatures
246

247
Various signature types for representing different kinds of Java types.
248

249
```java { .api }
250
/**
251
 * Base interface for signature result types (return values and field types)
252
 */
253
public interface Result {
254
    // Marker interface for result types in signatures
255
}
256

257
/**
258
 * Base interface for all Java type signatures
259
 */
260
public interface JavaTypeSignature extends Result {
261
    // Marker interface for type signatures
262
}
263

264
/**
265
 * Signature for reference types (classes, interfaces, arrays, type variables)
266
 */
267
public interface ReferenceTypeSignature extends JavaTypeSignature {
268
    // Marker interface for reference type signatures
269
}
270

271
/**
272
 * Signature for class and interface types with generic parameters
273
 */
274
public class ClassTypeSignature implements ReferenceTypeSignature {
275
    /** Package path (e.g., "java/util/") */
276
    public final String packageSpecifier;
277
    /** Simple class type signature */
278
    public final SimpleClassTypeSignature simpleClassTypeSignature;
279
    /** Suffix for inner classes */
280
    public final SimpleClassTypeSignature[] suffix;
281
    
282
    /**
283
     * Constructor for class type signatures
284
     */
285
    public ClassTypeSignature(String packageSpecifier, SimpleClassTypeSignature simpleClassTypeSignature,
286
                             SimpleClassTypeSignature[] suffix);
287
}
288

289
/**
290
 * Simple class type signature with type arguments
291
 */
292
public class SimpleClassTypeSignature {
293
    /** Simple class name */
294
    public final String identifier;
295
    /** Type arguments for this class */
296
    public final TypeArgument[] typeArguments;
297
    
298
    /**
299
     * Constructor for simple class type signatures
300
     */
301
    public SimpleClassTypeSignature(String identifier, TypeArgument[] typeArguments);
302
}
303

304
/**
305
 * Array type signature
306
 */
307
public class ArrayTypeSignature implements ReferenceTypeSignature {
308
    /** Component type of the array */
309
    public final JavaTypeSignature component;
310
    
311
    /**
312
     * Constructor for array type signatures
313
     */
314
    public ArrayTypeSignature(JavaTypeSignature component);
315
}
316

317
/**
318
 * Type variable signature (references to type parameters)
319
 */
320
public class TypeVariableSignature implements ReferenceTypeSignature {
321
    /** Name of the type variable */
322
    public final String identifier;
323
    
324
    /**
325
     * Constructor for type variable signatures
326
     */
327
    public TypeVariableSignature(String identifier);
328
}
329
```
330

331
### Type Arguments and Wildcards
332

333
Handle generic type arguments including wildcards and bounds.
334

335
```java { .api }
336
/**
337
 * Represents a type argument in generic signatures
338
 */
339
public class TypeArgument {
340
    /** Wildcard indicator (*, +, -) or null for non-wildcard */
341
    public final WildcardIndicator wildcard;
342
    /** The actual type signature */
343
    public final ReferenceTypeSignature type;
344
    
345
    /**
346
     * Constructor for type arguments
347
     * @param wildcard Wildcard type (or null)
348
     * @param type Type signature
349
     */
350
    public TypeArgument(WildcardIndicator wildcard, ReferenceTypeSignature type);
351
}
352

353
/**
354
 * Wildcard indicators for generic type arguments
355
 */
356
public enum WildcardIndicator {
357
    /** Unbounded wildcard (?) */
358
    WILD,
359
    /** ? extends - upper bound wildcard */
360
    EXTENDS,
361
    /** ? super - lower bound wildcard */
362
    SUPER,
363
    /** No wildcard - exact type */
364
    EXACT
365
}
366
```
367

368
### Primitive Types
369

370
Represent primitive type signatures using an enum.
371

372
```java { .api }
373
/**
374
 * Base types (primitives) in Java signatures
375
 */
376
public enum BaseType implements JavaTypeSignature {
377
    /** byte primitive */
378
    B,
379
    /** char primitive */
380
    C,
381
    /** double primitive */
382
    D,
383
    /** float primitive */
384
    F,
385
    /** int primitive */
386
    I,
387
    /** long primitive */
388
    J,
389
    /** short primitive */
390
    S,
391
    /** boolean primitive */
392
    Z;
393
}
394

395
/**
396
 * Void descriptor for method return types
397
 */
398
public enum VoidDescriptor implements Result {
399
    /** void return type */
400
    V;
401
}
402
```
403

404
### Exception Signatures
405

406
Handle checked exception declarations in method signatures.
407

408
```java { .api }
409
/**
410
 * Marker interface for exception signatures in method throws clauses
411
 */
412
public interface ThrowsSignature {
413
    // Marker interface - implemented by signature types that can be thrown
414
}
415
```
416

417
## Parsing and Resolution
418

419
### Signature Resolution
420

421
Resolve signatures in the context of class hierarchies and type parameters.
422

423
```java { .api }
424
/**
425
 * Resolver for class signatures with context
426
 */
427
public class ClassResolver {
428
    /**
429
     * Resolve a class signature with given type parameter bindings
430
     * @param signature Class signature to resolve
431
     * @param bindings Type parameter to concrete type bindings
432
     * @return Resolved signature
433
     */
434
    public ClassSignature resolve(ClassSignature signature, Map<String, JavaTypeSignature> bindings);
435
}
436

437
/**
438
 * Resolver for method signatures
439
 */
440
public class MethodResolver {
441
    /**
442
     * Resolve a method signature with given type parameter bindings
443
     * @param signature Method signature to resolve
444
     * @param bindings Type parameter to concrete type bindings
445
     * @return Resolved signature
446
     */
447
    public MethodSignature resolve(MethodSignature signature, Map<String, JavaTypeSignature> bindings);
448
}
449

450
/**
451
 * Resolver for field signatures
452
 */
453
public class FieldResolver {
454
    /**
455
     * Resolve a field signature with given type parameter bindings
456
     * @param signature Field signature to resolve
457
     * @param bindings Type parameter to concrete type bindings
458
     * @return Resolved signature
459
     */
460
    public FieldSignature resolve(FieldSignature signature, Map<String, JavaTypeSignature> bindings);
461
}
462
```
463

464
## Complete Usage Example
465

466
```java
467
import aQute.bnd.signatures.*;
468

469
public class SignatureAnalyzer {
470
    public void analyzeClass(String className) {
471
        // Get signature from class file (implementation not shown)
472
        String signatureString = getClassSignature(className);
473
        
474
        if (signatureString != null) {
475
            ClassSignature signature = ClassSignature.of(signatureString);
476
            
477
            // Analyze type parameters
478
            System.out.println("Class " + className + " has " + 
479
                signature.typeParameters.length + " type parameters");
480
            
481
            for (TypeParameter param : signature.typeParameters) {
482
                System.out.println("  Type parameter: " + param.identifier);
483
                if (param.classBound != null) {
484
                    System.out.println("    Extends: " + param.classBound);
485
                }
486
                for (ReferenceTypeSignature bound : param.interfaceBounds) {
487
                    System.out.println("    Also extends: " + bound);
488
                }
489
            }
490
            
491
            // Analyze superclass
492
            if (signature.superClass != null) {
493
                System.out.println("Extends: " + signature.superClass);
494
                analyzeClassTypeSignature(signature.superClass);
495
            }
496
            
497
            // Analyze interfaces
498
            for (ClassTypeSignature iface : signature.superInterfaces) {
499
                System.out.println("Implements: " + iface);
500
                analyzeClassTypeSignature(iface);
501
            }
502
            
503
            // Get all dependencies for OSGi manifest generation
504
            Set<String> dependencies = signature.erasedBinaryReferences();
505
            System.out.println("Dependencies: " + dependencies);
506
        }
507
    }
508
    
509
    private void analyzeClassTypeSignature(ClassTypeSignature signature) {
510
        // Analyze type arguments
511
        if (signature.simpleClassTypeSignature.typeArguments.length > 0) {
512
            System.out.println("  Type arguments:");
513
            for (TypeArgument arg : signature.simpleClassTypeSignature.typeArguments) {
514
                if (arg.wildcard != WildcardIndicator.EXACT) {
515
                    System.out.println("    Wildcard: " + arg.wildcard + " " + arg.type);
516
                } else {
517
                    System.out.println("    Concrete: " + arg.type);
518
                }
519
            }
520
        }
521
    }
522
}
523
```
524

525
## OSGi Integration
526

527
The signature parsing is specifically designed for OSGi bundle analysis:
528

529
- **Dependency Analysis**: Extract all referenced types for Import-Package generation
530
- **Export Analysis**: Determine which generic types are exposed in exported packages
531
- **Version Compatibility**: Analyze signature changes for semantic versioning
532
- **Metadata Generation**: Generate OSGi metadata from generic type information
533

534
This makes it an essential tool for OSGi bundle development and analysis workflows.