0
# Web Services
1
2
JAX-WS API for building SOAP-based web services with annotation-driven development, comprehensive client support, and WSDL generation.
3
4
## Web Service Development
5
6
### Web Service Annotations
7
8
```java { .api }
9
@Target({ElementType.TYPE})
10
@Retention(RetentionPolicy.RUNTIME)
11
public @interface WebService {
12
String name() default "";
13
String targetNamespace() default "";
14
String serviceName() default "";
15
String portName() default "";
16
String wsdlLocation() default "";
17
String endpointInterface() default "";
18
}
19
20
@Target({ElementType.METHOD})
21
@Retention(RetentionPolicy.RUNTIME)
22
public @interface WebMethod {
23
String operationName() default "";
24
String action() default "";
25
boolean exclude() default false;
26
}
27
28
@Target({ElementType.PARAMETER})
29
@Retention(RetentionPolicy.RUNTIME)
30
public @interface WebParam {
31
String name() default "";
32
String targetNamespace() default "";
33
Mode mode() default Mode.IN;
34
boolean header() default false;
35
String partName() default "";
36
}
37
38
@Target({ElementType.METHOD})
39
@Retention(RetentionPolicy.RUNTIME)
40
public @interface WebResult {
41
String name() default "";
42
String targetNamespace() default "";
43
boolean header() default false;
44
String partName() default "";
45
}
46
```
47
48
### Service Endpoint Interface
49
50
```java { .api }
51
@Target({ElementType.TYPE})
52
@Retention(RetentionPolicy.RUNTIME)
53
public @interface WebServiceProvider {
54
String targetNamespace() default "";
55
String serviceName() default "";
56
String portName() default "";
57
String wsdlLocation() default "";
58
}
59
60
public interface Provider<T> {
61
T invoke(T request);
62
}
63
```
64
65
## Client API
66
67
### Service and Port Access
68
69
```java { .api }
70
public class Service {
71
public static Service create(URL wsdlDocumentLocation, QName serviceName);
72
public static Service create(QName serviceName);
73
public <T> T getPort(QName portName, Class<T> serviceEndpointInterface);
74
public <T> T getPort(Class<T> serviceEndpointInterface);
75
public void addPort(QName portName, String bindingId, String endpointAddress);
76
77
public <T> Dispatch<T> createDispatch(QName portName, Class<T> type, Service.Mode mode);
78
public Dispatch<Source> createDispatch(QName portName, Service.Mode mode);
79
80
public Executor getExecutor();
81
public void setExecutor(Executor executor);
82
83
public HandlerResolver getHandlerResolver();
84
public void setHandlerResolver(HandlerResolver handlerResolver);
85
}
86
87
public interface Dispatch<T> extends BindingProvider {
88
T invoke(T msg);
89
Response<T> invokeAsync(T msg);
90
Future<?> invokeAsync(T msg, AsyncHandler<T> handler);
91
void invokeOneWay(T msg);
92
}
93
```
94
95
### Binding Provider Interface
96
97
```java { .api }
98
public interface BindingProvider {
99
Map<String, Object> getRequestContext();
100
Map<String, Object> getResponseContext();
101
Binding getBinding();
102
EndpointReference getEndpointReference();
103
<T extends EndpointReference> T getEndpointReference(Class<T> clazz);
104
105
String ENDPOINT_ADDRESS_PROPERTY = "javax.xml.ws.service.endpoint.address";
106
String USERNAME_PROPERTY = "javax.xml.ws.security.auth.username";
107
String PASSWORD_PROPERTY = "javax.xml.ws.security.auth.password";
108
String SESSION_MAINTAIN_PROPERTY = "javax.xml.ws.session.maintain";
109
String SOAPACTION_USE_PROPERTY = "javax.xml.ws.soap.http.soapaction.use";
110
String SOAPACTION_URI_PROPERTY = "javax.xml.ws.soap.http.soapaction.uri";
111
}
112
```
113
114
## Handler Framework
115
116
### Handler Interfaces
117
118
```java { .api }
119
public interface Handler<C extends MessageContext> {
120
boolean handleMessage(C context);
121
boolean handleFault(C context);
122
void close(MessageContext context);
123
}
124
125
public interface SOAPHandler<T extends SOAPMessageContext> extends Handler<T> {
126
Set<QName> getHeaders();
127
}
128
129
public interface LogicalHandler<C extends LogicalMessageContext> extends Handler<C> {
130
}
131
132
public interface HandlerResolver {
133
List<Handler> getHandlerChain(PortInfo portInfo);
134
}
135
```
136
137
### Message Context
138
139
```java { .api }
140
public interface MessageContext extends Map<String, Object> {
141
Scope getScope(String name);
142
void setScope(String name, Scope scope);
143
144
String MESSAGE_OUTBOUND_PROPERTY = "javax.xml.ws.handler.message.outbound";
145
String INBOUND_MESSAGE_ATTACHMENTS = "javax.xml.ws.binding.attachments.inbound";
146
String OUTBOUND_MESSAGE_ATTACHMENTS = "javax.xml.ws.binding.attachments.outbound";
147
148
enum Scope {
149
APPLICATION, HANDLER
150
}
151
}
152
153
public interface SOAPMessageContext extends MessageContext {
154
SOAPMessage getMessage();
155
void setMessage(SOAPMessage message);
156
Object[] getHeaders(QName header, JAXBContext context, boolean allRoles);
157
Set<String> getRoles();
158
}
159
160
public interface LogicalMessageContext extends MessageContext {
161
LogicalMessage getMessage();
162
}
163
```
164
165
## SOAP Binding and Faults
166
167
### SOAP Binding
168
169
```java { .api }
170
public interface SOAPBinding extends Binding {
171
Set<String> getRoles();
172
void setRoles(Set<String> roles);
173
boolean isMTOMEnabled();
174
void setMTOMEnabled(boolean flag);
175
176
String SOAP11HTTP_BINDING = "http://schemas.xmlsoap.org/wsdl/soap/http";
177
String SOAP12HTTP_BINDING = "http://www.w3.org/2003/05/soap/bindings/HTTP/";
178
String SOAP11HTTP_MTOM_BINDING = "http://schemas.xmlsoap.org/wsdl/soap/http?mtom=true";
179
String SOAP12HTTP_MTOM_BINDING = "http://www.w3.org/2003/05/soap/bindings/HTTP/?mtom=true";
180
}
181
```
182
183
### SOAP Faults
184
185
```java { .api }
186
public class SOAPFaultException extends ProtocolException {
187
public SOAPFaultException(SOAPFault fault);
188
public SOAPFault getFault();
189
}
190
191
@Target({ElementType.METHOD})
192
@Retention(RetentionPolicy.RUNTIME)
193
public @interface FaultAction {
194
String value() default "";
195
Class<? extends Exception> className();
196
}
197
```
198
199
## Usage Examples
200
201
### Simple Web Service
202
203
```java
204
@WebService
205
public class HelloWorldService {
206
207
@WebMethod
208
public String sayHello(@WebParam(name = "name") String name) {
209
return "Hello, " + name + "!";
210
}
211
}
212
```
213
214
### Web Service Client
215
216
```java
217
// Create service from WSDL
218
URL wsdlURL = new URL("http://localhost:8080/hello?wsdl");
219
QName serviceName = new QName("http://example.com/", "HelloWorldService");
220
Service service = Service.create(wsdlURL, serviceName);
221
222
// Get port
223
HelloWorldService port = service.getPort(HelloWorldService.class);
224
225
// Call web service
226
String result = port.sayHello("World");
227
```
228
229
### Provider-based Service
230
231
```java
232
@WebServiceProvider
233
@ServiceMode(Service.Mode.MESSAGE)
234
public class MessageProvider implements Provider<SOAPMessage> {
235
236
@Override
237
public SOAPMessage invoke(SOAPMessage request) {
238
// Process SOAP message
239
return response;
240
}
241
}
242
```