0
# Client Services
1

2
Client-side APIs for consuming web services with support for dynamic proxies, dispatch clients, service interception, and advanced client-side configuration. These APIs provide comprehensive client-side web service functionality.
3

4
## Capabilities
5

6
### Service Interception
7

8
Client-side service interception providing extension points for customizing service behavior and proxy creation.
9

10
```java { .api }
11
/**
12
 * Client-side service interception for customizing web service behavior
13
 */
14
package com.sun.xml.ws.api.client;
15
public interface ServiceInterceptor {
16
    /** Customize features before binding creation */
17
    List<WebServiceFeature> preCreateBinding(WSPortInfo portInfo, List<WebServiceFeature> features);
18
    
19
    /** Customize proxy after creation */
20
    void postCreateProxy(WSBindingProvider bindingProvider, Class<?> serviceEndpointInterface);
21
}
22

23
/**
24
 * Factory for service interceptors
25
 */
26
public abstract class ServiceInterceptorFactory {
27
    /** Create interceptor for service */
28
    public abstract ServiceInterceptor create(WSPortInfo portInfo);
29
    
30
    /** Load interceptor factories via ServiceLoader */
31
    public static List<ServiceInterceptorFactory> load();
32
}
33

34
/**
35
 * Port information for service interception
36
 */
37
public interface WSPortInfo extends PortInfo {
38
    /** Get endpoint address */
39
    String getEndpointAddress();
40
    
41
    /** Get WSDL service name */
42
    QName getServiceName();
43
    
44
    /** Get WSDL port name */
45
    QName getPortName();
46
    
47
    /** Get binding ID */
48
    BindingID getBindingId();
49
    
50
    /** Get port model */
51
    WSDLPort getPort();
52
    
53
    /** Get owner service */
54
    WSService getOwner();
55
}
56
```
57

58
### Extended Binding Provider
59

60
Enhanced binding provider interface with JAX-WS RI specific extensions.
61

62
```java { .api }
63
/**
64
 * Extended binding provider with JAX-WS RI specific functionality
65
 */
66
package com.sun.xml.ws.developer;
67
public interface WSBindingProvider extends BindingProvider {
68
    /** Set endpoint address */
69
    void setAddress(String address);
70
    
71
    /** Get WS-Addressing endpoint reference */
72
    WSEndpointReference getWSEndpointReference();
73
    
74
    /** Get port information */
75
    WSPortInfo getPortInfo();
76
    
77
    /** Get outbound headers for next request */
78
    Headers getInboundHeaders();
79
    
80
    /** Set outbound headers for next request */
81
    void setOutboundHeaders(Headers headers);
82
    
83
    /** Set outbound headers from Objects */
84
    void setOutboundHeaders(Object... headers);
85
    
86
    /** Set outbound headers from list */
87
    void setOutboundHeaders(List<Header> headers);
88
    
89
    /** Get inbound headers from last response */
90
    Headers getInboundHeaders();
91
}
92
```
93

94
### Client Configuration
95

96
Client-side configuration and context management.
97

98
```java { .api }
99
/**
100
 * Client request context implementation
101
 */
102
package com.sun.xml.ws.client;
103
public final class RequestContext extends BasePropertySet {
104
    /** Create request context with fallback */
105
    public RequestContext(MapContext fallback);
106
    
107
    /** Get endpoint address */
108
    public String getEndpointAddress();
109
    
110
    /** Set endpoint address */
111
    public void setEndpointAddress(String address);
112
    
113
    /** Copy context */
114
    public RequestContext copy();
115
    
116
    /** Fill request packet with context properties */
117
    public void fill(Packet packet, boolean isAddressingEnabled);
118
}
119

120
/**
121
 * Client response context implementation  
122
 */
123
public final class ResponseContext extends BasePropertySet {
124
    /** Create response context from packet */
125
    public ResponseContext(Packet packet);
126
    
127
    /** Get HTTP response code */
128
    public Integer getResponseCode();
129
    
130
    /** Get response headers */
131
    public Map<String, List<String>> getResponseHeaders();
132
}
133
```
134

135
### Content Negotiation
136

137
Client-side content negotiation for optimizing message formats.
138

139
```java { .api }
140
/**
141
 * Content negotiation for optimal encoding selection
142
 */
143
package com.sun.xml.ws.client;
144
public enum ContentNegotiation {
145
    /** No content negotiation */
146
    none,
147
    
148
    /** Pessimistic negotiation - assume server doesn't support optimized encodings */
149
    pessimistic,
150
    
151
    /** Optimistic negotiation - assume server supports optimized encodings */
152
    optimistic;
153
    
154
    /** Get property name for configuration */
155
    public static final String PROPERTY = "com.sun.xml.ws.client.ContentNegotiation";
156
}
157
```
158

159
### Dispatch Client
160

161
Type-safe dispatch client for dynamic web service invocation.
162

163
```java { .api }
164
/**
165
 * Enhanced dispatch implementation with JAX-WS RI extensions
166
 */
167
package com.sun.xml.ws.client.dispatch;
168
public abstract class DispatchImpl<T> implements Dispatch<T>, WSBindingProvider {
169
    /** Get request context */
170
    public Map<String, Object> getRequestContext();
171
    
172
    /** Get response context */
173
    public Map<String, Object> getResponseContext();
174
    
175
    /** Get binding */
176
    public Binding getBinding();
177
    
178
    /** Invoke operation synchronously */
179
    public abstract T invoke(T msg);
180
    
181
    /** Invoke operation asynchronously with callback */
182
    public abstract Future<?> invokeAsync(T msg, AsyncHandler<T> handler);
183
    
184
    /** Invoke operation asynchronously */
185
    public abstract Response<T> invokeAsync(T msg);
186
    
187
    /** Invoke one-way operation */
188
    public abstract void invokeOneWay(T msg);
189
}
190

191
/**
192
 * Message-based dispatch for SOAP messages
193
 */
194
public final class MessageDispatch extends DispatchImpl<Message> {
195
    /** Invoke with Message object */
196
    public Message invoke(Message message);
197
    
198
    /** Async invoke with Message */
199
    public Future<?> invokeAsync(Message message, AsyncHandler<Message> handler);
200
    
201
    /** One-way invoke with Message */
202
    public void invokeOneWay(Message message);
203
}
204

205
/**
206
 * Packet-based dispatch for low-level message processing
207
 */
208
public final class PacketDispatch extends DispatchImpl<Packet> {
209
    /** Invoke with Packet object */
210
    public Packet invoke(Packet packet);
211
    
212
    /** Process packet through client pipeline */
213
    public Packet process(Packet request);
214
}
215
```
216

217
### Exception Handling
218

219
Client-side exception handling and completion features.
220

221
```java { .api }
222
/**
223
 * Feature for handling exceptions in packet completion
224
 */
225
public final class ThrowableInPacketCompletionFeature extends WebServiceFeature {
226
    /** Feature ID */
227
    public static final String ID = "com.sun.xml.ws.api.client.ThrowableInPacketCompletionFeature";
228
    
229
    /** Default constructor enabling the feature */
230
    public ThrowableInPacketCompletionFeature();
231
    
232
    /** Constructor with enable/disable flag */
233
    public ThrowableInPacketCompletionFeature(boolean enabled);
234
    
235
    /** Get feature ID */
236
    public String getID();
237
}
238
```
239

240
### Async Processing
241

242
Asynchronous processing support for client operations.
243

244
```java { .api }
245
/**
246
 * Asynchronous response context
247
 */
248
package com.sun.xml.ws.api.client;
249
public interface AsyncResponseContext {
250
    /** Get response when available */
251
    Response<?> getResponse();
252
    
253
    /** Set response */
254
    void setResponse(Response<?> response);
255
    
256
    /** Check if response is available */
257
    boolean isComplete();
258
}
259

260
/**
261
 * Async provider interface for custom async handling
262
 */
263
public interface AsyncProvider<T> {
264
    /** Process async request */
265
    void invoke(T request, AsyncProviderCallback<T> callback, WebServiceContext context);
266
}
267
```
268

269
**Usage Examples:**
270

271
```java
272
import com.sun.xml.ws.api.client.*;
273
import com.sun.xml.ws.developer.*;
274
import com.sun.xml.ws.client.*;
275

276
// Service interception
277
public class MyServiceInterceptor implements ServiceInterceptor {
278
    public List<WebServiceFeature> preCreateBinding(WSPortInfo portInfo, List<WebServiceFeature> features) {
279
        // Add custom features
280
        features.add(new StreamingAttachmentFeature());
281
        return features;
282
    }
283
    
284
    public void postCreateProxy(WSBindingProvider bindingProvider, Class<?> serviceEndpointInterface) {
285
        // Configure proxy
286
        bindingProvider.getRequestContext().put(
287
            BindingProvider.ENDPOINT_ADDRESS_PROPERTY, 
288
            "http://new-endpoint.com/service"
289
        );
290
    }
291
}
292

293
// Register interceptor factory
294
public class MyServiceInterceptorFactory extends ServiceInterceptorFactory {
295
    public ServiceInterceptor create(WSPortInfo portInfo) {
296
        return new MyServiceInterceptor();
297
    }
298
}
299

300
// Enhanced binding provider usage
301
MyService service = new MyService();
302
MyServiceInterface port = service.getMyServicePort();
303
WSBindingProvider wsBP = (WSBindingProvider) port;
304

305
// Set outbound headers
306
Header customHeader = Headers.create(new QName("http://example.com", "Auth"), "token123");
307
wsBP.setOutboundHeaders(customHeader);
308

309
// Configure endpoint
310
wsBP.setAddress("http://localhost:8080/myservice");
311

312
// Make call
313
String result = port.myOperation("input");
314

315
// Get inbound headers
316
Headers inboundHeaders = wsBP.getInboundHeaders();
317
Header responseHeader = inboundHeaders.get(new QName("http://example.com", "ResponseInfo"), false);
318

319
// Content negotiation
320
Map<String, Object> requestContext = ((BindingProvider) port).getRequestContext();
321
requestContext.put(ContentNegotiation.PROPERTY, ContentNegotiation.optimistic);
322

323
// Dispatch client usage
324
Service service = Service.create(wsdlURL, serviceName);
325
Dispatch<Message> dispatch = service.createDispatch(portName, Message.class, Service.Mode.MESSAGE);
326

327
// Configure dispatch
328
dispatch.getRequestContext().put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY, endpointAddress);
329

330
// Create message
331
Message requestMessage = Messages.create(jaxbContext, requestObject, SOAPVersion.SOAP_11);
332

333
// Synchronous invoke
334
Message responseMessage = dispatch.invoke(requestMessage);
335

336
// Asynchronous invoke  
337
Future<Message> futureResponse = dispatch.invokeAsync(requestMessage);
338
Message response = futureResponse.get();
339

340
// With callback
341
dispatch.invokeAsync(requestMessage, new AsyncHandler<Message>() {
342
    public void handleResponse(Response<Message> response) {
343
        try {
344
            Message result = response.get();
345
            // Process result
346
        } catch (Exception e) {
347
            // Handle error
348
        }
349
    }
350
});
351
```