0
# ClassLoader Management
1

2
Jetty WebApp provides specialized classloaders that implement servlet specification compliant class loading with advanced visibility controls, caching capabilities, and support for class transformation.
3

4
## Capabilities
5

6
### WebAppClassLoader
7

8
Servlet specification compliant classloader with fine-grained class visibility controls.
9

10
```java { .api }
11
/**
12
 * Specialized classloader for web applications with servlet spec compliant
13
 * loading behavior and class visibility controls.
14
 */
15
public class WebAppClassLoader extends URLClassLoader implements ClassVisibilityChecker {
16
    
17
    /**
18
     * Create classloader with context configuration
19
     */
20
    public WebAppClassLoader(Context context) throws IOException;
21
    
22
    /**
23
     * Create classloader with parent and context
24
     */
25
    public WebAppClassLoader(ClassLoader parent, Context context) throws IOException;
26
    
27
    /**
28
     * Get/set the classloader name for debugging
29
     */
30
    public String getName();
31
    public void setName(String name);
32
    
33
    /**
34
     * Get the configuration context
35
     */
36
    public Context getContext();
37
}
38
```
39

40
**Usage Examples:**
41

42
```java
43
// Create with webapp context
44
WebAppClassLoader loader = new WebAppClassLoader(webAppContext);
45
loader.setName("MyWebApp ClassLoader");
46

47
// Create with custom parent
48
WebAppClassLoader loader = new WebAppClassLoader(
49
    Thread.currentThread().getContextClassLoader(),
50
    webAppContext
51
);
52
```
53

54
### Classpath Management
55

56
Methods for managing the classloader's classpath.
57

58
```java { .api }
59
/**
60
 * Add a resource to the classpath
61
 */
62
public void addClassPath(Resource resource) throws IOException;
63

64
/**
65
 * Add classpath entries from string (semicolon/colon separated)
66
 */
67
public void addClassPath(String classPath) throws IOException;
68

69
/**
70
 * Add all JAR files from a directory to the classpath
71
 */
72
public void addJars(Resource lib) throws IOException;
73
```
74

75
**Usage Examples:**
76

77
```java
78
// Add individual JAR
79
loader.addClassPath(Resource.newResource("lib/mylib.jar"));
80

81
// Add classpath string
82
loader.addClassPath("lib/jar1.jar:lib/jar2.jar:classes");
83

84
// Add all JARs from directory
85
loader.addJars(Resource.newResource("WEB-INF/lib"));
86
```
87

88
### Class Visibility Controls
89

90
Methods for controlling class visibility and delegation behavior.
91

92
```java { .api }
93
/**
94
 * Check if a class should be loaded by the system classloader
95
 */
96
public boolean isSystemClass(Class<?> clazz);
97

98
/**
99
 * Check if a class should be loaded by the server classloader
100
 */
101
public boolean isServerClass(Class<?> clazz);
102
```
103

104
**Usage Examples:**
105

106
```java
107
// Check class visibility
108
if (loader.isSystemClass(MyClass.class)) {
109
    // Class will be loaded by system classloader
110
}
111

112
if (loader.isServerClass(SomeJettyClass.class)) {
113
    // Class will be loaded by server classloader (hidden from webapp)
114
}
115
```
116

117
### Class Transformation
118

119
Support for bytecode transformation during class loading.
120

121
```java { .api }
122
/**
123
 * Add a class file transformer for bytecode modification
124
 */
125
public void addTransformer(ClassFileTransformer transformer);
126

127
/**
128
 * Remove a class file transformer
129
 */
130
public boolean removeTransformer(ClassFileTransformer transformer);
131
```
132

133
**Usage Examples:**
134

135
```java
136
// Add instrumentation transformer
137
ClassFileTransformer transformer = new MyInstrumentationTransformer();
138
loader.addTransformer(transformer);
139

140
// Remove transformer
141
loader.removeTransformer(transformer);
142
```
143

144
### Security and Privileged Access
145

146
Methods for executing code with specific class loading privileges.
147

148
```java { .api }
149
/**
150
 * Run action with server class access privileges
151
 */
152
public static <T> T runWithServerClassAccess(PrivilegedExceptionAction<T> action) 
153
    throws PrivilegedActionException;
154
```
155

156
**Usage Examples:**
157

158
```java
159
// Execute with server class access
160
String result = WebAppClassLoader.runWithServerClassAccess(() -> {
161
    // This code can access server classes normally hidden from webapp
162
    return ServerUtility.getInternalInfo();
163
});
164
```
165

166
### Resource Management
167

168
Methods for managing classloader lifecycle.
169

170
```java { .api }
171
/**
172
 * Close the classloader and release all resources
173
 */
174
public void close() throws IOException;
175
```
176

177
### CachingWebAppClassLoader
178

179
Performance-optimized classloader with resource and class caching for improved performance.
180

181
```java { .api }
182
/**
183
 * WebAppClassLoader that caches resource lookups and class loading
184
 * for improved performance in development and production environments.
185
 * Implements JMX management for cache control.
186
 */
187
@ManagedObject("Caching WebApp ClassLoader")
188
public class CachingWebAppClassLoader extends WebAppClassLoader {
189
    
190
    /**
191
     * Create caching classloader with context
192
     */
193
    public CachingWebAppClassLoader(Context context) throws IOException;
194
    
195
    /**
196
     * Create caching classloader with parent and context
197
     */
198
    public CachingWebAppClassLoader(ClassLoader parent, Context context) throws IOException;
199
    
200
    /**
201
     * Create caching classloader with all parameters
202
     */
203
    public CachingWebAppClassLoader(ClassLoader parent, Context context, 
204
                                   ClassLoader parentPriorityClassLoader) throws IOException;
205
    
206
    /**
207
     * Clear all cached resources and classes (JMX managed operation)
208
     */
209
    @ManagedOperation(value = "Clear cache", impact = "ACTION")
210
    public void clearCache();
211
    
212
    /**
213
     * Get the number of cached classes
214
     */
215
    @ManagedAttribute("Cached Class Count")
216
    public int getCachedClassCount();
217
    
218
    /**
219
     * Get the number of cached resources  
220
     */
221
    @ManagedAttribute("Cached Resource Count")
222
    public int getCachedResourceCount();
223
    
224
    /**
225
     * Check if caching is enabled
226
     */
227
    @ManagedAttribute("Caching Enabled")
228
    public boolean isCaching();
229
    
230
    /**
231
     * Enable or disable caching
232
     */
233
    public void setCaching(boolean cache);
234
}
235
```
236

237
**Usage Examples:**
238

239
```java
240
// Create caching classloader
241
CachingWebAppClassLoader loader = new CachingWebAppClassLoader(webAppContext);
242

243
// Clear cache when needed (e.g., during development)
244
loader.clearCache();
245
```
246

247
### Overridden Methods
248

249
Key methods overridden to provide webapp-specific behavior.
250

251
```java { .api }
252
/**
253
 * Get resource with caching (CachingWebAppClassLoader only)
254
 */
255
public URL getResource(String name);
256

257
/**
258
 * Load class with caching (CachingWebAppClassLoader only)  
259
 */
260
public Class<?> loadClass(String name) throws ClassNotFoundException;
261
```
262

263
## Context Interface
264

265
The Context interface provides configuration and resource access for classloaders.
266

267
```java { .api }
268
/**
269
 * Context interface providing classloader configuration and resource access
270
 */
271
public interface Context extends ClassVisibilityChecker {
272
    
273
    /**
274
     * Convert URL/path to resource
275
     */
276
    Resource newResource(String urlOrPath) throws IOException;
277
    
278
    /**
279
     * Get permissions for the webapp
280
     */
281
    PermissionCollection getPermissions();
282
    
283
    /**
284
     * Check if parent classloader has priority
285
     */
286
    boolean isParentLoaderPriority();
287
    
288
    /**
289
     * Get extra classpath resources
290
     */
291
    List<Resource> getExtraClasspath();
292
    
293
    /**
294
     * Check if resource should be loaded by server classloader
295
     */
296
    boolean isServerResource(String name, URL parentUrl);
297
    
298
    /**
299
     * Check if resource should be loaded by system classloader
300
     */
301
    boolean isSystemResource(String name, URL webappUrl);
302
}
303
```
304

305
## ClassVisibilityChecker Interface
306

307
Base interface for class visibility checking.
308

309
```java { .api }
310
/**
311
 * Interface for checking class visibility and loading delegation
312
 */
313
public interface ClassVisibilityChecker {
314
    
315
    /**
316
     * Check if class should be loaded by parent classloader
317
     */
318
    boolean isSystemClass(Class<?> clazz);
319
    
320
    /**
321
     * Check if class should be hidden from webapp
322
     */
323
    boolean isServerClass(Class<?> clazz);
324
}
325
```
326

327
## Usage Patterns
328

329
### Standard Webapp Setup
330

331
```java
332
// Create webapp with standard classloader
333
WebAppContext webapp = new WebAppContext();
334
webapp.setContextPath("/myapp");
335
webapp.setWar("myapp.war");
336

337
// Classloader is created automatically during webapp.start()
338
WebAppClassLoader loader = webapp.getClassLoader();
339
```
340

341
### Custom Classloader Configuration
342

343
```java
344
// Create webapp with caching classloader
345
WebAppContext webapp = new WebAppContext() {
346
    @Override
347
    protected void startContext() throws Exception {
348
        // Set custom classloader before starting
349
        setClassLoader(new CachingWebAppClassLoader(this));
350
        super.startContext();
351
    }
352
};
353
```
354

355
### Development Mode with Cache Clearing
356

357
```java
358
// Clear classloader cache during development
359
if (isDevelopmentMode()) {
360
    WebAppClassLoader loader = webapp.getClassLoader();
361
    if (loader instanceof CachingWebAppClassLoader) {
362
        ((CachingWebAppClassLoader) loader).clearCache();
363
    }
364
}
365
```
366

367
### Class Transformation Example
368

369
```java
370
// Add instrumentation transformer
371
ClassFileTransformer transformer = new ClassFileTransformer() {
372
    @Override
373
    public byte[] transform(ClassLoader loader, String className,
374
                          Class<?> classBeingRedefined, ProtectionDomain protectionDomain,
375
                          byte[] classfileBuffer) throws IllegalClassFormatException {
376
        if (className.startsWith("com/myapp/")) {
377
            // Transform classes in com.myapp package
378
            return instrumentClass(classfileBuffer);
379
        }
380
        return null; // No transformation
381
    }
382
};
383

384
WebAppClassLoader loader = webapp.getClassLoader();
385
loader.addTransformer(transformer);
386
```