0
# Developer Utilities
1

2
Advanced developer APIs providing fine-grained control over JAX-WS behavior, including streaming attachment support, schema validation, custom features, and JAX-WS RI specific properties and extensions.
3

4
## Capabilities
5

6
### JAX-WS RI Properties
7

8
Constants and property names for configuring JAX-WS RI specific behavior.
9

10
```java { .api }
11
/**
12
 * JAX-WS RI specific property constants for advanced configuration
13
 */
14
package com.sun.xml.ws.developer;
15
public final class JAXWSProperties {
16
    /** Content negotiation property for client */
17
    public static final String CONTENT_NEGOTIATION_PROPERTY = "com.sun.xml.ws.client.ContentNegotiation";
18
    
19
    /** MTOM threshold value for attachment handling */
20
    public static final String MTOM_THRESHOLOD_VALUE = "com.sun.xml.ws.common.MtomThresholdValue";
21
    
22
    /** HTTP exchange property for accessing raw HTTP */
23
    public static final String HTTP_EXCHANGE = "com.sun.xml.ws.http.exchange";
24
    
25
    /** Connect timeout property */
26
    public static final String CONNECT_TIMEOUT = "com.sun.xml.ws.connect.timeout";
27
    
28
    /** Request timeout property */
29
    public static final String REQUEST_TIMEOUT = "com.sun.xml.ws.request.timeout";
30
    
31
    /** HTTP response code property */
32
    public static final String HTTP_RESPONSE_CODE = "com.sun.xml.ws.http.response.code";
33
    
34
    /** Inbound header list map property */
35
    public static final String INBOUND_HEADER_LIST_PROPERTY = "com.sun.xml.ws.api.message.HeaderList";
36
    
37
    /** Hostname verifier property for SSL */
38
    public static final String HOSTNAME_VERIFIER = "com.sun.xml.ws.transport.https.client.hostname.verifier";
39
    
40
    /** SSL socket factory property */
41
    public static final String SSL_SOCKET_FACTORY = "com.sun.xml.ws.transport.https.client.SSLSocketFactory";
42
    
43
    /** Disable XML security property */
44
    public static final String DISABLE_XML_SECURITY = "com.sun.xml.ws.disableXmlSecurity";
45
}
46
```
47

48
### Extended Binding Provider
49

50
Enhanced binding provider interface with JAX-WS RI specific extensions.
51

52
```java { .api }
53
/**
54
 * Extended binding provider interface with JAX-WS RI extensions
55
 */
56
public interface WSBindingProvider extends BindingProvider {
57
    /** Set endpoint address */
58
    void setAddress(String address);
59
    
60
    /** Get WS-Addressing endpoint reference */
61
    WSEndpointReference getWSEndpointReference();
62
    
63
    /** Get port information */
64
    WSPortInfo getPortInfo();
65
    
66
    /** Set outbound headers for next request */
67
    void setOutboundHeaders(Headers headers);
68
    
69
    /** Set outbound headers from objects */
70
    void setOutboundHeaders(Object... headers);
71
    
72
    /** Set outbound headers from list */
73
    void setOutboundHeaders(List<Header> headers);
74
    
75
    /** Get inbound headers from last response */
76
    Headers getInboundHeaders();
77
    
78
    /** Get request context as property set */
79
    PropertySet getRequestContext();
80
    
81
    /** Get response context as property set */
82
    PropertySet getResponseContext();
83
}
84
```
85

86
### Streaming Attachment Support
87

88
Feature and utilities for streaming large attachments efficiently.
89

90
```java { .api }
91
/**
92
 * Feature for enabling streaming attachment processing
93
 */
94
@WebServiceFeature.ID("http://java.sun.com/xml/ns/jaxws/")
95
public final class StreamingAttachmentFeature extends WebServiceFeature {
96
    /** Default constructor with system temp directory */
97
    public StreamingAttachmentFeature();
98
    
99
    /** Constructor with custom directory and settings */
100
    public StreamingAttachmentFeature(String dir, boolean parseEagerly, long memoryThreshold);
101
    
102
    /** Get directory for temporary files */
103
    public String getDir();
104
    
105
    /** Check if attachments are parsed eagerly */
106
    public boolean isParseEagerly();
107
    
108
    /** Get memory threshold for streaming */
109
    public long getMemoryThreshold();
110
    
111
    /** Get feature ID */
112
    public String getID();
113
}
114

115
/**
116
 * Streaming data handler for efficient attachment processing
117
 */
118
public final class StreamingDataHandler extends DataHandler {
119
    /** Create streaming data handler */
120
    public StreamingDataHandler(Object obj, String type);
121
    
122
    /** Create from URL */
123
    public StreamingDataHandler(URL url);
124
    
125
    /** Get content as streaming source */
126
    public StreamingDataSource getDataSource();
127
    
128
    /** Check if content is buffered in memory */
129
    public boolean isBuffered();
130
    
131
    /** Move content to file system */
132
    public void moveTo(File file) throws IOException;
133
    
134
    /** Close and clean up temporary resources */
135
    public void close() throws IOException;
136
}
137
```
138

139
### Schema Validation
140

141
Schema validation feature and utilities for validating SOAP messages.
142

143
```java { .api }
144
/**
145
 * Feature for enabling schema validation of SOAP messages
146
 */
147
@WebServiceFeature.ID("http://java.sun.com/xml/ns/jaxws/schemaValidation")
148
public final class SchemaValidationFeature extends WebServiceFeature {
149
    /** Default constructor enabling validation */
150
    public SchemaValidationFeature();
151
    
152
    /** Constructor with enable/disable flag */
153
    public SchemaValidationFeature(boolean enabled);
154
    
155
    /** Constructor with custom error handler */
156
    public SchemaValidationFeature(Class<? extends ValidationErrorHandler> errorHandler);
157
    
158
    /** Get error handler class */
159
    public Class<? extends ValidationErrorHandler> getErrorHandler();
160
    
161
    /** Get feature ID */
162
    public String getID();
163
}
164

165
/**
166
 * Schema validation annotation for per-service configuration
167
 */
168
@Retention(RetentionPolicy.RUNTIME)
169
@Target({ElementType.TYPE, ElementType.METHOD, ElementType.FIELD, ElementType.PARAMETER})
170
@WebServiceFeatureAnnotation(id = SchemaValidationFeature.ID, bean = SchemaValidationFeature.class)
171
public @interface SchemaValidation {
172
    /** Enable or disable validation */
173
    boolean enabled() default true;
174
    
175
    /** Custom error handler class */
176
    Class<? extends ValidationErrorHandler> handler() default ValidationErrorHandler.class;
177
}
178

179
/**
180
 * Custom validation error handler interface
181
 */
182
public abstract class ValidationErrorHandler implements ErrorHandler {
183
    /** Handle validation warning */
184
    public abstract void warning(SAXParseException exception) throws SAXException;
185
    
186
    /** Handle validation error */
187
    public abstract void error(SAXParseException exception) throws SAXException;
188
    
189
    /** Handle fatal validation error */
190
    public abstract void fatalError(SAXParseException exception) throws SAXException;
191
}
192
```
193

194
### Stateful Web Services
195

196
Support for stateful web service instances with session management.
197

198
```java { .api }
199
/**
200
 * Annotation for enabling stateful web service behavior
201
 */
202
@Retention(RetentionPolicy.RUNTIME)
203
@Target(ElementType.TYPE)
204
public @interface Stateful {
205
    /** Timeout for stateful instances in milliseconds */
206
    long timeout() default 600000; // 10 minutes default
207
    
208
    /** Maximum number of stateful instances */
209
    int maxInstances() default 100;
210
    
211
    /** Cleanup policy for expired instances */
212
    CleanupPolicy cleanupPolicy() default CleanupPolicy.ON_TIMEOUT;
213
    
214
    /** Cleanup policy enumeration */
215
    enum CleanupPolicy {
216
        ON_TIMEOUT,
217
        ON_MAX_INSTANCES,
218
        MANUAL
219
    }
220
}
221

222
/**
223
 * Stateful web service context for managing instance state
224
 */
225
public final class StatefulWebServiceContext {
226
    /** Get current stateful instance ID */
227
    public static String getInstanceId(WebServiceContext context);
228
    
229
    /** Invalidate current stateful instance */
230
    public static void invalidate(WebServiceContext context);
231
    
232
    /** Get instance timeout */
233
    public static long getInstanceTimeout(WebServiceContext context);
234
    
235
    /** Set instance timeout */
236
    public static void setInstanceTimeout(WebServiceContext context, long timeout);
237
}
238
```
239

240
### Member Submission Addressing
241

242
Support for Member Submission WS-Addressing specification.
243

244
```java { .api }
245
/**
246
 * Feature for Member Submission WS-Addressing support
247
 */
248
@WebServiceFeature.ID("http://schemas.xmlsoap.org/ws/2004/08/addressing/")
249
public final class MemberSubmissionAddressingFeature extends WebServiceFeature {
250
    /** Default constructor enabling MS addressing */
251
    public MemberSubmissionAddressingFeature();
252
    
253
    /** Constructor with enable/disable flag */
254
    public MemberSubmissionAddressingFeature(boolean enabled);
255
    
256
    /** Constructor with validation flag */
257
    public MemberSubmissionAddressingFeature(boolean enabled, boolean required);
258
    
259
    /** Check if addressing is required */
260
    public boolean isRequired();
261
    
262
    /** Get feature ID */
263
    public String getID();
264
}
265

266
/**
267
 * Member Submission addressing annotation
268
 */
269
@Retention(RetentionPolicy.RUNTIME)
270
@Target({ElementType.TYPE, ElementType.METHOD, ElementType.FIELD, ElementType.PARAMETER})
271
@WebServiceFeatureAnnotation(id = MemberSubmissionAddressingFeature.ID, 
272
                           bean = MemberSubmissionAddressingFeature.class)
273
public @interface MemberSubmissionAddressing {
274
    /** Enable or disable addressing */
275
    boolean enabled() default true;
276
    
277
    /** Require addressing headers */
278
    boolean required() default false;
279
}
280

281
/**
282
 * Member Submission endpoint reference implementation
283
 */
284
public final class MemberSubmissionEndpointReference extends EndpointReference {
285
    /** Create MS endpoint reference from Source */
286
    public MemberSubmissionEndpointReference(Source eprInfoset);
287
    
288
    /** Get endpoint reference address */
289
    public String getAddress();
290
    
291
    /** Get reference parameters */
292
    public List<Element> getReferenceParameters();
293
    
294
    /** Get reference properties */
295
    public List<Element> getReferenceProperties();
296
    
297
    /** Get port type */
298
    public QName getPortType();
299
    
300
    /** Get service name */
301
    public QName getServiceName();
302
}
303
```
304

305
### Advanced Configuration Features
306

307
Additional features for fine-tuning JAX-WS behavior.
308

309
```java { .api }
310
/**
311
 * Feature for specifying JAXB context usage
312
 */
313
@WebServiceFeature.ID("http://java.sun.com/xml/ns/jaxws/jaxbcontext/")
314
public final class UsesJAXBContextFeature extends WebServiceFeature {
315
    /** Constructor with JAXB context */
316
    public UsesJAXBContextFeature(JAXBContext jaxbContext);
317
    
318
    /** Get JAXB context */
319
    public JAXBContext getJAXBContext();
320
    
321
    /** Get feature ID */
322
    public String getID();
323
}
324

325
/**
326
 * Annotation for specifying JAXB context
327
 */
328
@Retention(RetentionPolicy.RUNTIME)
329
@Target({ElementType.TYPE, ElementType.METHOD, ElementType.FIELD, ElementType.PARAMETER})
330
@WebServiceFeatureAnnotation(id = UsesJAXBContextFeature.ID, bean = UsesJAXBContextFeature.class)
331
public @interface UsesJAXBContext {
332
    /** JAXB context factory method */
333
    String value();
334
}
335

336
/**
337
 * Feature for customizing binding type
338
 */
339
public final class BindingTypeFeature extends WebServiceFeature {
340
    /** Constructor with binding ID */
341
    public BindingTypeFeature(String bindingId);
342
    
343
    /** Get binding ID */
344
    public String getBindingId();
345
    
346
    /** Get feature ID */
347
    public String getID();
348
}
349

350
/**
351
 * Feature for customizing serialization behavior
352
 */
353
public final class SerializationFeature extends WebServiceFeature {
354
    /** Constructor with encoding */
355
    public SerializationFeature(String encoding);
356
    
357
    /** Get character encoding */
358
    public String getEncoding();
359
    
360
    /** Get feature ID */
361
    public String getID();
362
}
363
```
364

365
### Servlet Integration Utilities
366

367
Utilities for servlet-based web service development.
368

369
```java { .api }
370
/**
371
 * HTTP session scope annotation for servlet environments
372
 */
373
package com.sun.xml.ws.developer.servlet;
374
@Retention(RetentionPolicy.RUNTIME)
375
@Target(ElementType.TYPE)
376
public @interface HttpSessionScope {
377
    /** Session timeout in minutes */
378
    int timeout() default 30;
379
    
380
    /** Create session if none exists */
381
    boolean create() default true;
382
}
383

384
/**
385
 * HTTP session context for accessing servlet session
386
 */
387
public final class HttpSessionContext {
388
    /** Get HTTP session from web service context */
389
    public static HttpSession getSession(WebServiceContext context);
390
    
391
    /** Get HTTP session with create flag */
392
    public static HttpSession getSession(WebServiceContext context, boolean create);
393
    
394
    /** Get servlet request */
395
    public static HttpServletRequest getRequest(WebServiceContext context);
396
    
397
    /** Get servlet response */
398
    public static HttpServletResponse getResponse(WebServiceContext context);
399
}
400
```
401

402
**Usage Examples:**
403

404
```java
405
import com.sun.xml.ws.developer.*;
406
import com.sun.xml.ws.developer.servlet.*;
407

408
// Streaming attachment configuration
409
@WebService
410
@StreamingAttachment(dir = "/tmp/attachments", threshold = 4096, parseEagerly = true)
411
public class FileUploadService {
412
    @WebMethod
413
    public String uploadFile(@WebParam(name = "file") DataHandler file) throws IOException {
414
        // Handle large file with streaming
415
        StreamingDataHandler streamingHandler = (StreamingDataHandler) file;
416
        
417
        if (!streamingHandler.isBuffered()) {
418
            // File is being streamed, move to permanent location
419
            File destination = new File("/uploads/" + UUID.randomUUID() + ".dat");
420
            streamingHandler.moveTo(destination);
421
            return "File uploaded: " + destination.getName();
422
        }
423
        
424
        return "File buffered in memory";
425
    }
426
}
427

428
// Schema validation configuration
429
@WebService
430
@SchemaValidation(enabled = true, handler = CustomValidationErrorHandler.class)
431
public class ValidatingService {
432
    @WebMethod
433
    public Response processData(@WebParam(name = "request") Request request) {
434
        // Request is automatically validated against schema
435
        return new Response();
436
    }
437
}
438

439
public class CustomValidationErrorHandler extends ValidationErrorHandler {
440
    public void error(SAXParseException exception) throws SAXException {
441
        // Log validation error
442
        logger.error("Schema validation error: " + exception.getMessage());
443
        throw exception; // Fail the request
444
    }
445
    
446
    public void warning(SAXParseException exception) throws SAXException {
447
        // Log warning but continue
448
        logger.warn("Schema validation warning: " + exception.getMessage());
449
    }
450
    
451
    public void fatalError(SAXParseException exception) throws SAXException {
452
        logger.fatal("Fatal schema validation error: " + exception.getMessage());
453
        throw exception;
454
    }
455
}
456

457
// Stateful web service
458
@WebService
459
@Stateful(timeout = 300000, maxInstances = 50) // 5 minute timeout, max 50 instances
460
public class StatefulCalculator {
461
    private double accumulator = 0.0;
462
    
463
    @WebMethod
464
    public double add(@WebParam(name = "value") double value, @Resource WebServiceContext context) {
465
        accumulator += value;
466
        
467
        // Extend session timeout
468
        StatefulWebServiceContext.setInstanceTimeout(context, 600000); // 10 minutes
469
        
470
        return accumulator;
471
    }
472
    
473
    @WebMethod  
474
    public void clear(@Resource WebServiceContext context) {
475
        accumulator = 0.0;
476
        // Optionally invalidate session
477
        // StatefulWebServiceContext.invalidate(context);
478
    }
479
}
480

481
// Client-side advanced configuration
482
MyService service = new MyService();
483
MyServiceInterface port = service.getMyServicePort(
484
    new StreamingAttachmentFeature("/tmp", false, 8192),
485
    new SchemaValidationFeature(true),
486
    new MemberSubmissionAddressingFeature(true, true)
487
);
488

489
WSBindingProvider wsBP = (WSBindingProvider) port;
490

491
// Configure request properties
492
Map<String, Object> requestContext = wsBP.getRequestContext();
493
requestContext.put(JAXWSProperties.CONNECT_TIMEOUT, 30000);
494
requestContext.put(JAXWSProperties.REQUEST_TIMEOUT, 60000);
495
requestContext.put(JAXWSProperties.CONTENT_NEGOTIATION_PROPERTY, ContentNegotiation.optimistic);
496

497
// Custom JAXB context usage
498
@WebService
499
@UsesJAXBContext("createCustomJAXBContext")
500
public class CustomJAXBService {
501
    @WebMethod
502
    public CustomResponse processCustomData(@WebParam(name = "data") CustomData data) {
503
        return new CustomResponse();
504
    }
505
    
506
    public static JAXBContext createCustomJAXBContext() throws JAXBException {
507
        return JAXBContext.newInstance(CustomData.class, CustomResponse.class);
508
    }
509
}
510

511
// Servlet-based stateful service
512
@WebService
513
@HttpSessionScope(timeout = 60, create = true)
514
public class ShoppingCartService {
515
    @WebMethod
516
    public void addItem(@WebParam(name = "item") Item item, @Resource WebServiceContext context) {
517
        HttpSession session = HttpSessionContext.getSession(context);
518
        
519
        @SuppressWarnings("unchecked")
520
        List<Item> cart = (List<Item>) session.getAttribute("cart");
521
        if (cart == null) {
522
            cart = new ArrayList<>();
523
            session.setAttribute("cart", cart);
524
        }
525
        
526
        cart.add(item);
527
    }
528
    
529
    @WebMethod
530
    public List<Item> getCart(@Resource WebServiceContext context) {
531
        HttpSession session = HttpSessionContext.getSession(context, false);
532
        if (session != null) {
533
            @SuppressWarnings("unchecked")
534
            List<Item> cart = (List<Item>) session.getAttribute("cart");
535
            return cart != null ? cart : new ArrayList<>();
536
        }
537
        return new ArrayList<>();
538
    }
539
}
540

541
// Advanced client configuration with SSL
542
BindingProvider bp = (BindingProvider) port;
543
Map<String, Object> requestContext = bp.getRequestContext();
544

545
// SSL configuration
546
requestContext.put(JAXWSProperties.SSL_SOCKET_FACTORY, createCustomSSLSocketFactory());
547
requestContext.put(JAXWSProperties.HOSTNAME_VERIFIER, createCustomHostnameVerifier());
548

549
// Custom headers
550
WSBindingProvider wsBP = (WSBindingProvider) port;
551
Header authHeader = Headers.create(new QName("http://example.com", "Authentication"), "Bearer token123");
552
wsBP.setOutboundHeaders(authHeader);
553
```