0
# JAX-WS Runtime (jaxws-rt)
1

2
JAX-WS Runtime (jaxws-rt) is a comprehensive implementation of Jakarta XML Web Services providing complete SOAP web service capabilities for Java applications. It serves as the reference implementation of the Jakarta Web Services specifications, offering high-performance enterprise web service functionality with support for SOAP message processing, WS-Policy, WS-Addressing, and multiple transport protocols.
3

4
## Package Information
5

6
- **Package Name**: com.sun.xml.ws:jaxws-rt
7
- **Package Type**: Maven
8
- **Language**: Java
9
- **Installation**: Add to your Maven pom.xml:
10

11
```xml
12
<dependency>
13
    <groupId>com.sun.xml.ws</groupId>
14
    <artifactId>jaxws-rt</artifactId>
15
    <version>3.0.2</version>
16
</dependency>
17
```
18

19
## Core Imports
20

21
```java
22
// Core JAX-WS API (included as transitive dependency)
23
import jakarta.xml.ws.Service;
24
import jakarta.xml.ws.WebServiceFeature;
25
import jakarta.xml.ws.spi.Provider;
26

27
// JAX-WS RI specific APIs
28
import com.sun.xml.ws.api.WSBinding;
29
import com.sun.xml.ws.api.server.WSEndpoint;
30
import com.sun.xml.ws.api.client.ServiceInterceptor;
31
```
32

33
Module system import (Java 9+):
34
```java
35
module myapp {
36
    requires com.sun.xml.ws;
37
}
38
```
39

40
## Basic Usage
41

42
### Client-side Web Service Consumption
43

44
```java
45
import jakarta.xml.ws.Service;
46
import jakarta.xml.ws.WebServiceFeature;
47
import com.sun.xml.ws.developer.JAXWSProperties;
48

49
// Create service from WSDL
50
URL wsdlLocation = new URL("http://localhost:8080/MyService?wsdl");
51
QName serviceName = new QName("http://example.com/", "MyService");
52
Service service = Service.create(wsdlLocation, serviceName);
53

54
// Get port with features
55
MyServiceInterface port = service.getPort(MyServiceInterface.class);
56

57
// Configure request context
58
Map<String, Object> requestContext = ((BindingProvider) port).getRequestContext();
59
requestContext.put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY, "http://localhost:8080/MyService");
60

61
// Make web service call
62
String result = port.myOperation("parameter");
63
```
64

65
### Server-side Web Service Publishing
66

67
```java
68
import jakarta.xml.ws.Endpoint;
69
import com.sun.xml.ws.api.server.WSEndpoint;
70

71
// Simple endpoint publishing
72
@WebService
73
public class MyServiceImpl {
74
    @WebMethod
75
    public String myOperation(String input) {
76
        return "Processed: " + input;
77
    }
78
}
79

80
// Publish endpoint
81
Endpoint endpoint = Endpoint.publish("http://localhost:8080/MyService", new MyServiceImpl());
82
```
83

84
## Architecture
85

86
JAX-WS Runtime is built around several key architectural components:
87

88
- **Message Pipeline**: Extensible tube/pipe architecture for processing SOAP messages with pluggable handlers
89
- **Databinding System**: Flexible XML-to-Java binding supporting JAXB and custom databinding providers  
90
- **Transport Layer**: Pluggable transport system supporting HTTP, HTTPS, JMS, and custom protocols
91
- **Policy Framework**: WS-Policy implementation for declarative configuration of web service capabilities
92
- **Feature System**: WebServiceFeature-based extensibility for adding cross-cutting concerns
93
- **Service Provider Interfaces (SPIs)**: Extensive extension points for customizing behavior at all layers
94

95
The runtime aggregates five core modules: rt (core runtime), policy (WS-Policy), rt-fi (Fast Infoset), httpspi-servlet (HTTP SPI), and servlet (servlet container integration).
96

97
## Capabilities
98

99
### Core Message Processing
100

101
Central message processing APIs providing SOAP message abstraction, pipeline processing, and attachment handling. Forms the foundation for all web service communication.
102

103
```java { .api }
104
// Message abstraction
105
package com.sun.xml.ws.api.message;
106
public abstract class Message {
107
    public abstract boolean hasPayload();
108
    public abstract Source readPayloadAsSource();
109
    public abstract SOAPMessage readAsSOAPMessage() throws SOAPException;
110
    public abstract void writeTo(ContentHandler contentHandler, ErrorHandler errorHandler) throws SAXException;
111
}
112

113
// Message container with metadata
114
public final class Packet {
115
    public Message getMessage();
116
    public void setMessage(Message msg);
117
    public Map<String, Object> asMap();
118
    public <T> T getSatellite(Class<T> satelliteClass);
119
}
120

121
// Pipeline processing
122
package com.sun.xml.ws.api.pipe;
123
public interface Tube {
124
    NextAction processRequest(Packet request);
125
    NextAction processResponse(Packet response);
126
    void preDestroy();
127
}
128
```
129

130
[Message Processing](./message-processing.md)
131

132
### Server-side Endpoint Management
133

134
Server-side web service endpoint creation, lifecycle management, and request processing with support for various deployment scenarios.
135

136
```java { .api }
137
// Root server processing object
138
package com.sun.xml.ws.api.server;
139
public abstract class WSEndpoint<T> {
140
    public static <T> WSEndpoint<T> create(Class<T> implType, boolean processHandlerAnnotation, 
141
                                         Invoker invoker, QName serviceName, QName portName, 
142
                                         Container container, WSBinding binding, 
143
                                         SDDocumentSource primaryWsdl, Collection<? extends SDDocumentSource> metadata, 
144
                                         EntityResolver resolver, boolean isTransportSynchronous);
145
    public abstract Codec createCodec();
146
    public abstract ServiceDefinition getServiceDefinition();
147
    public abstract SEIModel getSEIModel();
148
}
149

150
// Transport adapter
151
public abstract class Adapter<TK> {
152
    public abstract ToolkitAdapter<TK> getToolkit();
153
    public abstract void handle(TK toolkit) throws IOException;
154
}
155

156
// Container abstraction  
157
public abstract class Container {
158
    public abstract <T> T getSPI(Class<T> spiType);
159
}
160
```
161

162
[Server Endpoints](./server-endpoints.md)
163

164
### Client-side Service Access
165

166
Client-side APIs for consuming web services with support for dynamic proxies, dispatch clients, and service interception.
167

168
```java { .api }
169
// Service interception
170
package com.sun.xml.ws.api.client;
171
public interface ServiceInterceptor {
172
    List<WebServiceFeature> preCreateBinding(WSPortInfo portInfo, List<WebServiceFeature> features);
173
    void postCreateProxy(WSBindingProvider bindingProvider, Class<?> serviceEndpointInterface);
174
}
175

176
// Extended binding provider
177
package com.sun.xml.ws.developer;
178
public interface WSBindingProvider extends BindingProvider {
179
    void setAddress(String address);
180
    WSEndpointReference getWSEndpointReference();
181
    WSPortInfo getPortInfo();
182
}
183
```
184

185
[Client Services](./client-services.md)
186

187
### Policy Framework
188

189
WS-Policy implementation providing declarative configuration of web service capabilities, policy attachment, and assertion processing.
190

191
```java { .api }
192
// Core policy representation
193
package com.sun.xml.ws.policy;
194
public final class Policy implements Iterable<AssertionSet> {
195
    public static Policy createPolicy(PolicySourceModel model) throws PolicyException;
196
    public boolean isEmpty();
197
    public Iterator<AssertionSet> iterator();
198
    public Policy normalize(boolean isClientAssertion);
199
}
200

201
// Policy assertions
202
public abstract class PolicyAssertion {
203
    public abstract QName getName();
204
    public abstract AssertionData getData();
205
    public abstract boolean isOptional();
206
    public abstract boolean isPrivate();
207
}
208

209
// Policy map for storage
210
public final class PolicyMap {
211
    public Policy getEndpointEffectivePolicy(PolicyMapKey key) throws PolicyException;
212
    public Policy getOperationEffectivePolicy(PolicyMapKey key) throws PolicyException;
213
    public Policy getPortEffectivePolicy(PolicyMapKey key) throws PolicyException;
214
}
215
```
216

217
[Policy Framework](./policy-framework.md)
218

219
### Transport Integration
220

221
HTTP transport implementation and servlet container integration with support for various hosting scenarios.
222

223
```java { .api }
224
// HTTP transport
225
package com.sun.xml.ws.transport.http;
226
public final class HttpAdapter extends Adapter<HttpConnection> {
227
    public static HttpAdapter createAlone(WSEndpoint<?> endpoint, Map<String, String> urlPattern);
228
    public void handle(HttpConnection connection) throws IOException;
229
}
230

231
// Servlet integration
232
package com.sun.xml.ws.transport.http.servlet;
233
public final class WSServlet extends HttpServlet {
234
    protected void doGet(HttpServletRequest request, HttpServletResponse response) 
235
        throws ServletException, IOException;
236
    protected void doPost(HttpServletRequest request, HttpServletResponse response) 
237
        throws ServletException, IOException;
238
}
239
```
240

241
[Transport Integration](./transport-integration.md)
242

243
### Databinding System
244

245
XML-to-Java databinding with JAXB integration and support for custom databinding providers.
246

247
```java { .api }
248
// Core databinding interface
249
package com.oracle.webservices.api.databinding;
250
public interface Databinding {
251
    EndpointCallBridge createCallBridge(JavaCallInfo callInfo);
252
    ClientCallBridge createCallBridge(JavaCallInfo callInfo);
253
    void generateWSDL(WSDLGenInfo wsdlGenInfo);
254
}
255

256
// Databinding factory
257
public abstract class DatabindingFactory {
258
    public static DatabindingFactory newInstance();
259
    public abstract Databinding createDatabinding(DatabindingConfig config);
260
}
261

262
// SPI for custom providers
263
package com.sun.xml.ws.spi.db;
264
public interface DatabindingProvider {
265
    boolean isFor(String databindingMode);
266
    void init(Map<String, Object> properties);
267
    Databinding create(DatabindingConfig config);
268
}
269
```
270

271
[Databinding System](./databinding-system.md)
272

273
### Developer Utilities
274

275
Advanced developer APIs providing fine-grained control over JAX-WS behavior, streaming, validation, and custom features.
276

277
```java { .api }
278
// JAX-WS RI properties
279
package com.sun.xml.ws.developer;
280
public final class JAXWSProperties {
281
    public static final String CONTENT_NEGOTIATION_PROPERTY = "com.sun.xml.ws.client.ContentNegotiation";
282
    public static final String MTOM_THRESHOLOD_VALUE = "com.sun.xml.ws.common.MtomThresholdValue";
283
    public static final String HTTP_EXCHANGE = "com.sun.xml.ws.http.exchange";
284
}
285

286
// Extended binding provider
287
public interface WSBindingProvider extends BindingProvider {
288
    void setAddress(String address);
289
    WSEndpointReference getWSEndpointReference();
290
    WSPortInfo getPortInfo();
291
}
292

293
// Streaming attachment feature
294
@WebServiceFeature.ID("http://java.sun.com/xml/ns/jaxws/")
295
public final class StreamingAttachmentFeature extends WebServiceFeature {
296
    public StreamingAttachmentFeature(String dir, boolean parseEagerly, long memoryThreshold);
297
    public String getDir();
298
    public boolean isParseEagerly();
299
    public long getMemoryThreshold();
300
}
301
```
302

303
[Developer Utilities](./developer-utilities.md)
304

305
### Addressing Support
306

307
WS-Addressing implementation supporting both W3C and Member Submission specifications for message addressing and correlation.
308

309
```java { .api }
310
// Addressing version support
311
package com.sun.xml.ws.api.addressing;
312
public enum AddressingVersion {
313
    W3C("http://www.w3.org/2005/08/addressing"),
314
    MEMBER("http://schemas.xmlsoap.org/ws/2004/08/addressing");
315
    
316
    public String getNsUri();
317
    public QName getWsdlExtensionAttribute();
318
    public String getPrefix();
319
}
320

321
// Endpoint reference
322
public final class WSEndpointReference {
323
    public WSEndpointReference(Source eprInfoset, AddressingVersion version);
324
    public Source asSource(String localName);
325
    public WSEndpointReference createWithAddress(String address);
326
}
327
```
328

329
[Addressing Support](./addressing-support.md)
330

331
## Types
332

333
### Core Types
334

335
```java { .api }
336
// Binding representation
337
package com.sun.xml.ws.api;
338
public interface WSBinding extends Binding {
339
    SOAPVersion getSOAPVersion();
340
    AddressingVersion getAddressingVersion();
341
    boolean isFeatureEnabled(Class<? extends WebServiceFeature> feature);
342
    <F extends WebServiceFeature> F getFeature(Class<F> featureType);
343
}
344

345
// SOAP version constants
346
public enum SOAPVersion {
347
    SOAP_11("http://schemas.xmlsoap.org/soap/", "1.1"),
348
    SOAP_12("http://www.w3.org/2003/05/soap-envelope", "1.2");
349
    
350
    public String getHttpContentType();
351
    public String getHttpBindingId();
352
    public QName getFaultCodeClientLocalName();
353
}
354

355
// Attachment representation
356
package com.sun.xml.ws.api.message;
357
public interface Attachment {
358
    String getContentId();
359
    String getContentType();
360
    byte[] asByteArray();
361
    DataHandler asDataHandler();
362
    Source asSource();
363
    InputStream asInputStream();
364
}
365
```
366

367
### Exception Types
368

369
```java { .api }
370
// Policy exceptions
371
package com.sun.xml.ws.policy;
372
public class PolicyException extends Exception {
373
    public PolicyException(String message);
374
    public PolicyException(String message, Throwable cause);
375
}
376

377
// Web service exceptions
378
package com.sun.xml.ws.util.exception;
379
public abstract class JAXWSExceptionBase extends WebServiceException implements Localizable {
380
    protected JAXWSExceptionBase(String key, Object... args);
381
    protected JAXWSExceptionBase(Throwable throwable);
382
}
383
```
384

385
## Service Provider Interfaces (SPIs)
386

387
JAX-WS Runtime provides extensive customization through Service Provider Interfaces:
388

389
### Core Extension Points
390

391
```java { .api }
392
// Custom binding types
393
package com.sun.xml.ws.api;
394
public abstract class BindingIDFactory {
395
    public abstract BindingID parse(String lexical) throws WebServiceException;
396
}
397

398
// Custom transport implementations  
399
package com.sun.xml.ws.api.pipe;
400
public abstract class TransportTubeFactory {
401
    public abstract Tube doCreate(ClientTubeAssemblerContext context);
402
}
403

404
// Custom tubeline assembly
405
public abstract class TubelineAssemblerFactory {
406
    public abstract TubelineAssembler doCreate(BindingID bindingId);
407
}
408

409
// Custom policy assertions
410
package com.sun.xml.ws.policy.spi;
411
public interface PolicyAssertionCreator {
412
    String[] getSupportedDomainNamespaceURIs();
413
    PolicyAssertion createAssertion(AssertionData data, Collection<PolicyAssertion> nestedPolicy);
414
}
415
```
416

417
### Standard Implementations
418

419
The runtime provides standard implementations for:
420

421
- **jakarta.xml.ws.spi.Provider**: `com.sun.xml.ws.spi.ProviderImpl` 
422
- **DatabindingProvider**: `com.sun.xml.ws.db.DatabindingProviderImpl`
423
- **BindingContextFactory**: `com.sun.xml.ws.db.glassfish.JAXBRIContextFactory`
424
- **LoggingProvider**: `com.sun.xml.ws.policy.jaxws.XmlWsLoggingProvider`