0
# Configuration
1

2
The configuration system provides comprehensive options for customizing Fury's behavior, performance characteristics, and compatibility features through the FuryBuilder pattern.
3

4
## FuryBuilder
5

6
Primary configuration class for creating and customizing Fury instances.
7

8
```java { .api }
9
public final class FuryBuilder {
10
    // Language and compatibility
11
    public FuryBuilder withLanguage(Language language);
12
    public FuryBuilder withCompatibleMode(CompatibleMode compatibleMode);
13
    
14
    // Security configuration
15
    public FuryBuilder requireClassRegistration(boolean requireClassRegistration);
16
    public FuryBuilder suppressClassRegistrationWarnings(boolean suppressClassRegistrationWarnings);
17
    
18
    // Performance options
19
    public FuryBuilder withCodegen(boolean codeGenEnabled);
20
    public FuryBuilder withAsyncCompilation(boolean asyncCompilationEnabled);
21
    public FuryBuilder withRefTracking(boolean trackingRef);
22
    public FuryBuilder withStringRefIgnored(boolean stringRefIgnored);
23
    public FuryBuilder withTimeRefIgnored(boolean timeRefIgnored);
24
    public FuryBuilder withBasicTypesRefIgnored(boolean basicTypesRefIgnored);
25
    
26
    // Compression and encoding
27
    public FuryBuilder withIntCompressed(boolean compressInt);
28
    public FuryBuilder withLongEncoding(LongEncoding longEncoding);
29
    public FuryBuilder withStringCompressed(boolean compressString);
30
    
31
    // Advanced options
32
    public FuryBuilder withMetaShare(boolean metaShareEnabled);
33
    public FuryBuilder withScopedMetaShare(boolean scopedMetaShareEnabled);
34
    public FuryBuilder withMetaCompressor(MetaCompressor metaCompressor);
35
    public FuryBuilder withClassLoader(ClassLoader classLoader);
36
    public FuryBuilder withBufferSizeLimit(int bufferSizeLimitBytes);
37
    
38
    // Serializer configuration
39
    public FuryBuilder registerGuavaTypes(boolean registerGuavaTypes);
40
    public FuryBuilder withScalaOptimizationEnabled(boolean scalaOptimizationEnabled);
41
    public FuryBuilder withDefaultJDKStreamSerializerType(Class<? extends Serializer> defaultJDKStreamSerializerType);
42
    
43
    // Build methods
44
    public Fury build();
45
    public ThreadSafeFury buildThreadSafeFury();
46
    public ThreadLocalFury buildThreadLocalFury();
47
    public ThreadPoolFury buildThreadPoolFury();
48
}
49
```
50

51
## Configuration Enums
52

53
### Language
54

55
Defines the serialization language mode for cross-language compatibility.
56

57
```java { .api }
58
public enum Language {
59
    JAVA,    // Java-specific optimizations (recommended for Java-only usage)
60
    XLANG    // Cross-language compatibility mode
61
}
62
```
63

64
### CompatibleMode
65

66
Schema compatibility modes for handling schema evolution.
67

68
```java { .api }
69
public enum CompatibleMode {
70
    SCHEMA_CONSISTENT,  // Schema must be consistent (faster)
71
    COMPATIBLE         // Support schema evolution (flexible)
72
}
73
```
74

75
### LongEncoding
76

77
Long integer encoding strategies for size optimization.
78

79
```java { .api }
80
public enum LongEncoding {
81
    LE_RAW_BYTES,  // Little-endian raw bytes (8 bytes)
82
    SLI,          // Small long integer encoding (variable length)
83
    PVL           // Positive variable length encoding
84
}
85
```
86

87
## Config Class
88

89
Immutable configuration object containing all Fury settings.
90

91
```java { .api }
92
public class Config implements Serializable {
93
    // Configuration properties are accessible via getters
94
    public Language getLanguage();
95
    public CompatibleMode getCompatibleMode();
96
    public boolean isClassRegistrationRequired();
97
    public boolean isCodeGenEnabled();
98
    public boolean isRefTrackingEnabled();
99
    // ... other configuration getters
100
}
101
```
102

103
## Usage Examples
104

105
### Basic Configuration
106

107
```java
108
import org.apache.fury.Fury;
109
import org.apache.fury.config.FuryBuilder;
110
import org.apache.fury.config.Language;
111

112
// Simple Java-only configuration
113
Fury fury = Fury.builder()
114
    .withLanguage(Language.JAVA)
115
    .requireClassRegistration(false)
116
    .build();
117
```
118

119
### High-Performance Configuration
120

121
```java
122
// Optimized for maximum performance
123
Fury fury = Fury.builder()
124
    .withLanguage(Language.JAVA)           // Java-specific optimizations
125
    .withCodegen(true)                     // Enable JIT compilation
126
    .withAsyncCompilation(true)            // Async compilation for startup time
127
    .withRefTracking(false)                // Disable if no circular references
128
    .withIntCompressed(true)               // Compress integers
129
    .withStringCompressed(false)           // Skip string compression for speed
130
    .requireClassRegistration(true)        // Enable for security and performance
131
    .build();
132
```
133

134
### Security-Focused Configuration
135

136
```java
137
import org.apache.fury.resolver.AllowListChecker;
138
import java.util.Set;
139

140
// Security-hardened configuration
141
Set<String> allowedClasses = Set.of(
142
    "com.myapp.User",
143
    "com.myapp.Order",
144
    "java.lang.String",
145
    "java.util.ArrayList"
146
);
147

148
Fury fury = Fury.builder()
149
    .withLanguage(Language.JAVA)
150
    .requireClassRegistration(true)        // Mandatory class registration
151
    .suppressClassRegistrationWarnings(false)  // Show warnings
152
    .build();
153

154
// Register allowed classes
155
for (String className : allowedClasses) {
156
    fury.register(Class.forName(className));
157
}
158
```
159

160
### Cross-Language Configuration
161

162
```java
163
// Configuration for cross-language serialization
164
Fury fury = Fury.builder()
165
    .withLanguage(Language.XLANG)          // Enable cross-language mode
166
    .withCompatibleMode(CompatibleMode.COMPATIBLE)  // Schema evolution support
167
    .withMetaShare(true)                   // Share metadata for efficiency
168
    .requireClassRegistration(false)       // More flexible for XLANG
169
    .build();
170
```
171

172
### Thread-Safe Configurations
173

174
```java
175
// ThreadLocal-based thread safety (recommended)
176
ThreadLocalFury threadLocalFury = Fury.builder()
177
    .withLanguage(Language.JAVA)
178
    .withCodegen(true)
179
    .buildThreadLocalFury();
180

181
// Pool-based thread safety
182
ThreadPoolFury threadPoolFury = Fury.builder()
183
    .withLanguage(Language.JAVA)
184
    .withCodegen(true)
185
    .buildThreadPoolFury();
186
```
187

188
### Memory-Optimized Configuration
189

190
```java
191
import org.apache.fury.config.LongEncoding;
192

193
// Optimized for memory usage
194
Fury fury = Fury.builder()
195
    .withLanguage(Language.JAVA)
196
    .withIntCompressed(true)               // Compress integers
197
    .withLongEncoding(LongEncoding.SLI)    // Small long integer encoding
198
    .withStringCompressed(true)            // Compress strings
199
    .withRefTracking(true)                 // Share object references
200
    .withStringRefIgnored(false)           // Track string references
201
    .withBufferSizeLimit(64 * 1024)        // Limit buffer size
202
    .build();
203
```
204

205
### Custom Serializer Configuration
206

207
```java
208
import org.apache.fury.serializer.ObjectStreamSerializer;
209
import org.apache.fury.serializer.JavaSerializer;
210

211
// Custom serializer configuration
212
Fury fury = Fury.builder()
213
    .withLanguage(Language.JAVA)
214
    .withDefaultJDKStreamSerializerType(ObjectStreamSerializer.class)
215
    .registerGuavaTypes(true)              // Register Guava collection serializers
216
    .withScalaOptimizationEnabled(true)    // Enable Scala optimizations
217
    .build();
218
```
219

220
### Development vs Production Configurations
221

222
```java
223
public class FuryConfig {
224
    public static Fury createDevelopmentInstance() {
225
        return Fury.builder()
226
            .withLanguage(Language.JAVA)
227
            .requireClassRegistration(false)       // Flexible for development
228
            .suppressClassRegistrationWarnings(true)  // Reduce noise
229
            .withAsyncCompilation(false)           // Synchronous for debugging
230
            .build();
231
    }
232
    
233
    public static Fury createProductionInstance() {
234
        return Fury.builder()
235
            .withLanguage(Language.JAVA)
236
            .requireClassRegistration(true)        // Security
237
            .withCodegen(true)                     // Performance
238
            .withAsyncCompilation(true)            // Startup optimization
239
            .withRefTracking(false)                // Performance (if no circular refs)
240
            .build();
241
    }
242
}
243
```
244

245
## Configuration Best Practices
246

247
### Performance Optimization
248

249
1. **Use Language.JAVA** for Java-only applications
250
2. **Enable code generation** for maximum performance
251
3. **Disable reference tracking** if circular references are not needed
252
4. **Enable class registration** for better performance and security
253
5. **Use async compilation** to improve startup time
254

255
### Security Hardening
256

257
1. **Require class registration** to prevent arbitrary class deserialization
258
2. **Use allow-list based validation** for additional security
259
3. **Avoid disabling class registration warnings** in production
260
4. **Validate input sources** before deserialization
261

262
### Memory Management
263

264
1. **Enable compression** for network/storage scenarios
265
2. **Configure appropriate buffer size limits**
266
3. **Use reference tracking** for object graphs with shared references
267
4. **Consider string reference tracking** for string-heavy data
268

269
### Thread Safety
270

271
1. **Use ThreadLocalFury** for most concurrent scenarios
272
2. **Consider ThreadPoolFury** when ThreadLocal is problematic
273
3. **Share configuration** across thread-safe instances for consistency
274
4. **Avoid sharing single Fury instance** across threads
275

276
## Environment Variables
277

278
Fury respects certain environment variables for global configuration:
279

280
- `ENABLE_CLASS_REGISTRATION_FORCIBLY`: Forces class registration requirement when set to "true" or "1"
281
- Custom class loader configuration through system properties