0
# Type System and Reflection
1

2
Apache Fury's type system provides advanced type handling with generic type support, reflection utilities, and cross-language type compatibility for efficient serialization.
3

4
## Type Enumeration
5

6
Comprehensive type system for representing all supported data types.
7

8
```java { .api }
9
public enum Type {
10
    // Primitive types
11
    BOOL,
12
    BYTE, SHORT, INT, LONG,
13
    FLOAT, DOUBLE,
14
    CHAR,
15
    
16
    // Object types
17
    STRING,
18
    ENUM,
19
    
20
    // Collection types
21
    ARRAY,
22
    LIST, SET, MAP,
23
    
24
    // Time types
25
    DATE, TIMESTAMP, INSTANT,
26
    LOCAL_DATE, LOCAL_TIME, LOCAL_DATE_TIME,
27
    
28
    // Special types
29
    NULL,
30
    NOT_NULL,
31
    REF,
32
    
33
    // Fury-specific types
34
    FURY_TYPE_TAG,
35
    FURY_SET,
36
    FURY_PRIMITIVE_BOOL_ARRAY,
37
    FURY_PRIMITIVE_SHORT_ARRAY,
38
    FURY_PRIMITIVE_INT_ARRAY,
39
    FURY_PRIMITIVE_LONG_ARRAY,
40
    FURY_PRIMITIVE_FLOAT_ARRAY,
41
    FURY_PRIMITIVE_DOUBLE_ARRAY,
42
    FURY_STRING_ARRAY,
43
    
44
    // Complex types
45
    OBJECT,
46
    SUBCLASS,
47
    FINAL_OBJECT_TYPE,
48
    
49
    // Cross-language types  
50
    TUPLE,
51
    ARROW_RECORD_BATCH,
52
    ARROW_TABLE;
53
    
54
    public short getId();
55
    public boolean isNullable();
56
    public boolean isPrimitive();
57
}
58
```
59

60
## Type References
61

62
Generic type handling for preserving type information during serialization.
63

64
```java { .api }
65
public class TypeRef<T> {
66
    // Type creation
67
    public static <T> TypeRef<T> of(Class<T> type);
68
    public static <T> TypeRef<T> of(Type type);
69
    
70
    // Type information
71
    public Type getType();
72
    public Class<T> getRawType();
73
    public java.lang.reflect.Type getGenericType();
74
    public TypeParameter<T>[] getTypeParameters();
75
    
76
    // Type checking
77
    public boolean isAssignableFrom(TypeRef<?> other);
78
    public boolean isGeneric();
79
    public boolean isArray();
80
    public boolean isCollection();
81
    public boolean isMap();
82
}
83
```
84

85
## Type Parameters
86

87
Abstract base class for capturing generic type parameters at runtime.
88

89
```java { .api }
90
public abstract class TypeParameter<X> {
91
    // Type parameter information
92
    public java.lang.reflect.Type getType();
93
    public Class<X> getRawType();
94
    
95
    // Usage: new TypeParameter<List<String>>() {}
96
}
97
```
98

99
## Generics Utilities
100

101
Utilities for working with generic types and type parameters.
102

103
```java { .api }
104
public class Generics {
105
    // Generic type operations
106
    public static java.lang.reflect.Type[] getTypeArguments(java.lang.reflect.Type type);
107
    public static Class<?> getRawType(java.lang.reflect.Type type);
108
    public static boolean isGeneric(java.lang.reflect.Type type);
109
    
110
    // Collection type handling
111
    public static java.lang.reflect.Type getCollectionElementType(java.lang.reflect.Type collectionType);
112
    public static java.lang.reflect.Type[] getMapKeyValueTypes(java.lang.reflect.Type mapType);
113
    
114
    // Type construction
115
    public static java.lang.reflect.ParameterizedType buildParameterizedType(Class<?> rawType, java.lang.reflect.Type... typeArguments);
116
    public static java.lang.reflect.GenericArrayType buildGenericArrayType(java.lang.reflect.Type componentType);
117
}
118
```
119

120
## Type Utilities
121

122
General type manipulation and analysis utilities.
123

124
```java { .api }
125
public class TypeUtils {
126
    // Type analysis
127
    public static boolean isPrimitive(Class<?> type);
128
    public static boolean isBoxedPrimitive(Class<?> type);
129
    public static boolean isFinal(Class<?> type);
130
    public static boolean isAbstract(Class<?> type);
131
    public static boolean isInterface(Class<?> type);
132
    public static boolean isEnum(Class<?> type);
133
    
134
    // Array utilities
135
    public static boolean isArray(Class<?> type);
136
    public static Class<?> getArrayComponentType(Class<?> type);
137
    public static int getArrayDimensions(Class<?> type);
138
    
139
    // Collection utilities
140
    public static boolean isCollection(Class<?> type);
141
    public static boolean isList(Class<?> type);
142
    public static boolean isSet(Class<?> type);
143
    public static boolean isMap(Class<?> type);
144
    
145
    // Type conversion
146
    public static Class<?> boxedType(Class<?> primitiveType);
147
    public static Class<?> unboxedType(Class<?> boxedType);
148
    
149
    // Class hierarchy
150
    public static List<Class<?>> getAllSuperTypes(Class<?> type);
151
    public static boolean isAssignableFrom(Class<?> superType, Class<?> subType);
152
}
153
```
154

155
## Reflection Utilities
156

157
Advanced reflection operations optimized for serialization.
158

159
```java { .api }
160
public class ReflectionUtils {
161
    // Field access
162
    public static Field[] getFields(Class<?> clazz);
163
    public static Field[] getDeclaredFields(Class<?> clazz);
164
    public static Field getField(Class<?> clazz, String fieldName);
165
    public static void setField(Field field, Object target, Object value);
166
    public static Object getField(Field field, Object target);
167
    
168
    // Constructor access
169
    public static <T> Constructor<T> getDefaultConstructor(Class<T> clazz);
170
    public static <T> T newInstance(Class<T> clazz);
171
    public static <T> T newInstance(Constructor<T> constructor, Object... args);
172
    
173
    // Method access
174
    public static Method getMethod(Class<?> clazz, String methodName, Class<?>... parameterTypes);
175
    public static Object invoke(Method method, Object target, Object... args);
176
    
177
    // Class loading
178
    public static Class<?> loadClass(String className);
179
    public static Class<?> loadClass(String className, ClassLoader classLoader);
180
    
181
    // Type introspection
182
    public static boolean hasDefaultConstructor(Class<?> clazz);
183
    public static boolean isInstantiable(Class<?> clazz);
184
    public static boolean isSerializable(Class<?> clazz);
185
    
186
    // Annotation utilities
187
    public static <A extends Annotation> A getAnnotation(Class<?> clazz, Class<A> annotationType);
188
    public static <A extends Annotation> A getAnnotation(Field field, Class<A> annotationType);
189
    public static boolean hasAnnotation(Class<?> clazz, Class<? extends Annotation> annotationType);
190
}
191
```
192

193
## Field Access
194

195
High-performance field access abstractions.
196

197
```java { .api }
198
public abstract class FieldAccessor {
199
    // Factory methods
200
    public static FieldAccessor createAccessor(Field field);
201
    public static FieldAccessor createUnsafeAccessor(Field field);
202
    
203
    // Field operations
204
    public abstract Object get(Object target);
205
    public abstract void set(Object target, Object value);
206
    
207
    // Primitive specializations
208
    public abstract boolean getBoolean(Object target);
209
    public abstract void setBoolean(Object target, boolean value);
210
    public abstract byte getByte(Object target);
211
    public abstract void setByte(Object target, byte value);
212
    public abstract int getInt(Object target);
213
    public abstract void setInt(Object target, int value);
214
    public abstract long getLong(Object target);
215
    public abstract void setLong(Object target, long value);
216
    public abstract float getFloat(Object target);
217
    public abstract void setFloat(Object target, float value);
218
    public abstract double getDouble(Object target);
219
    public abstract void setDouble(Object target, double value);
220
    
221
    // Field information
222
    public abstract Field getField();
223
    public abstract Class<?> getType();
224
    public abstract String getName();
225
}
226
```
227

228
## Generic Type Handling
229

230
Advanced generic type operations for complex type scenarios.
231

232
```java { .api }
233
public class GenericType {
234
    // Generic type construction
235
    public static GenericType of(java.lang.reflect.Type type);
236
    public static GenericType of(Class<?> rawType, GenericType... typeArguments);
237
    
238
    // Type information
239
    public Class<?> getRawType();
240
    public GenericType[] getTypeArguments();
241
    public boolean isGeneric();
242
    public boolean isWildcard();
243
    public boolean isBounded();
244
    
245
    // Type operations
246
    public GenericType getComponentType(); // For arrays
247
    public GenericType getKeyType(); // For maps
248
    public GenericType getValueType(); // For maps and collections
249
    
250
    // Type matching
251
    public boolean isAssignableFrom(GenericType other);
252
    public boolean matches(java.lang.reflect.Type type);
253
}
254
```
255

256
## Usage Examples
257

258
### Basic Type Operations
259

260
```java
261
import org.apache.fury.type.Type;
262
import org.apache.fury.type.TypeRef;
263

264
// Working with Type enum
265
Type stringType = Type.STRING;
266
Type listType = Type.LIST;
267

268
// Creating type references
269
TypeRef<String> stringRef = TypeRef.of(String.class);
270
TypeRef<List<String>> listRef = new TypeRef<List<String>>() {};
271

272
// Type information
273
Class<String> rawType = stringRef.getRawType();
274
boolean isGeneric = listRef.isGeneric();
275
```
276

277
### Generic Type Handling
278

279
```java
280
import org.apache.fury.type.Generics;
281
import org.apache.fury.type.GenericType;
282

283
// Extract generic type information
284
java.lang.reflect.Type listStringType = new TypeParameter<List<String>>() {}.getType();
285
java.lang.reflect.Type elementType = Generics.getCollectionElementType(listStringType);
286

287
// Working with map types
288
java.lang.reflect.Type mapType = new TypeParameter<Map<String, Integer>>() {}.getType();
289
java.lang.reflect.Type[] keyValueTypes = Generics.getMapKeyValueTypes(mapType);
290
java.lang.reflect.Type keyType = keyValueTypes[0]; // String
291
java.lang.reflect.Type valueType = keyValueTypes[1]; // Integer
292

293
// Build parameterized types
294
java.lang.reflect.Type listIntType = Generics.buildParameterizedType(List.class, Integer.class);
295
```
296

297
### Reflection Operations
298

299
```java
300
import org.apache.fury.reflect.ReflectionUtils;
301
import org.apache.fury.reflect.FieldAccessor;
302

303
public class User {
304
    private String name;
305
    private int age;
306
    
307
    // constructors, getters, setters...
308
}
309

310
// Field access
311
Field nameField = ReflectionUtils.getField(User.class, "name");
312
FieldAccessor nameAccessor = FieldAccessor.createAccessor(nameField);
313

314
User user = new User();
315
nameAccessor.set(user, "Alice");
316
String name = (String) nameAccessor.get(user);
317

318
// High-performance field access
319
FieldAccessor ageAccessor = FieldAccessor.createUnsafeAccessor(
320
    ReflectionUtils.getField(User.class, "age"));
321
ageAccessor.setInt(user, 30);
322
int age = ageAccessor.getInt(user);
323
```
324

325
### Type Analysis
326

327
```java
328
import org.apache.fury.type.TypeUtils;
329

330
// Type checking
331
boolean isPrimitive = TypeUtils.isPrimitive(int.class);
332
boolean isCollection = TypeUtils.isCollection(List.class);
333
boolean isArray = TypeUtils.isArray(String[].class);
334

335
// Type conversion
336
Class<?> boxedInt = TypeUtils.boxedType(int.class); // Integer.class
337
Class<?> unboxedInteger = TypeUtils.unboxedType(Integer.class); // int.class
338

339
// Array analysis
340
Class<?> componentType = TypeUtils.getArrayComponentType(String[].class); // String.class
341
int dimensions = TypeUtils.getArrayDimensions(int[][][].class); // 3
342
```
343

344
### Complex Generic Scenarios
345

346
```java
347
// Nested generic types
348
TypeRef<Map<String, List<Integer>>> complexRef = new TypeRef<Map<String, List<Integer>>>() {};
349

350
// Extract nested type information
351
GenericType complexType = GenericType.of(complexRef.getGenericType());
352
GenericType keyType = complexType.getKeyType(); // String
353
GenericType valueType = complexType.getValueType(); // List<Integer>
354
GenericType listElementType = valueType.getComponentType(); // Integer
355
```
356

357
### Runtime Type Construction
358

359
```java
360
// Construct types at runtime
361
java.lang.reflect.Type runtimeListType = Generics.buildParameterizedType(
362
    List.class, 
363
    String.class);
364

365
GenericType genericType = GenericType.of(runtimeListType);
366

367
// Use with serialization
368
TypeRef<?> dynamicRef = TypeRef.of(genericType.getRawType());
369
```
370

371
### Performance-Optimized Field Access
372

373
```java
374
public class HighPerformanceSerializer {
375
    private final FieldAccessor[] fieldAccessors;
376
    
377
    public HighPerformanceSerializer(Class<?> clazz) {
378
        Field[] fields = ReflectionUtils.getFields(clazz);
379
        fieldAccessors = new FieldAccessor[fields.length];
380
        
381
        for (int i = 0; i < fields.length; i++) {
382
            // Use unsafe accessor for maximum performance
383
            fieldAccessors[i] = FieldAccessor.createUnsafeAccessor(fields[i]);
384
        }
385
    }
386
    
387
    public void serializeFields(Object obj, MemoryBuffer buffer) {
388
        for (FieldAccessor accessor : fieldAccessors) {
389
            Class<?> fieldType = accessor.getType();
390
            
391
            if (fieldType == int.class) {
392
                buffer.writeInt(accessor.getInt(obj));
393
            } else if (fieldType == String.class) {
394
                buffer.writeString((String) accessor.get(obj));
395
            }
396
            // ... handle other types
397
        }
398
    }
399
}
400
```
401

402
## Performance Considerations
403

404
### Type System Optimization
405

406
- **Type Caching**: Fury caches type information to avoid repeated reflection
407
- **Unsafe Field Access**: Used for maximum performance in hot paths
408
- **Generic Type Resolution**: Resolved once and cached for subsequent use
409
- **Primitive Specialization**: Optimized code paths for primitive types
410

411
### Best Practices
412

413
1. **Use TypeRef for Generic Types**: Preserves full type information at runtime
414
2. **Cache FieldAccessor Instances**: Create once and reuse for multiple operations
415
3. **Prefer Unsafe Accessors**: For performance-critical serialization paths
416
4. **Minimize Reflection**: Use cached accessors rather than repeated reflection calls
417
5. **Handle Type Erasure**: Use TypeParameter pattern for capturing generic types
418

419
### Memory Considerations
420

421
- **Type Metadata Caching**: Reduces repeated type analysis overhead
422
- **Field Accessor Pooling**: Reuse accessors to minimize object creation
423
- **Generic Type Optimization**: Efficient representation of complex generic types