1 /*
2 * Copyright (c) 2005, 2017, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package javax.xml.ws;
27
28 import java.util.List;
29 import java.util.Map;
30 import javax.xml.ws.spi.Provider;
31 import javax.xml.ws.spi.http.HttpContext;
32 import javax.xml.ws.wsaddressing.W3CEndpointReference;
33 import org.w3c.dom.Element;
34
35
36 /**
37 * A Web service endpoint.
38 *
39 * <p>Endpoints are created using the static methods defined in this
40 * class. An endpoint is always tied to one {@code Binding}
41 * and one implementor, both set at endpoint creation time.
42 *
43 * <p>An endpoint is either in a published or an unpublished state.
44 * The {@code publish} methods can be used to start publishing
45 * an endpoint, at which point it starts accepting incoming requests.
46 * Conversely, the {@code stop} method can be used to stop
47 * accepting incoming requests and take the endpoint down.
48 * Once stopped, an endpoint cannot be published again.
49 *
50 * <p>An {@code Executor} may be set on the endpoint in order
51 * to gain better control over the threads used to dispatch incoming
52 * requests. For instance, thread pooling with certain parameters
53 * can be enabled by creating a {@code ThreadPoolExecutor} and
54 * registering it with the endpoint.
55 *
56 * <p>Handler chains can be set using the contained {@code Binding}.
57 *
58 * <p>An endpoint may have a list of metadata documents, such as WSDL
59 * and XMLSchema documents, bound to it. At publishing time, the
60 * JAX-WS implementation will try to reuse as much of that metadata
61 * as possible instead of generating new ones based on the annotations
62 * present on the implementor.
63 *
64 * @since 1.6, JAX-WS 2.0
65 *
66 * @see javax.xml.ws.Binding
67 * @see javax.xml.ws.BindingType
68 * @see javax.xml.ws.soap.SOAPBinding
69 * @see java.util.concurrent.Executor
70 *
71 **/
72 public abstract class Endpoint {
73
74 /** Standard property: name of WSDL service.
75 * <p>Type: javax.xml.namespace.QName
76 **/
77 public static final String WSDL_SERVICE = "javax.xml.ws.wsdl.service";
78
79 /** Standard property: name of WSDL port.
80 * <p>Type: javax.xml.namespace.QName
81 **/
82 public static final String WSDL_PORT = "javax.xml.ws.wsdl.port";
83
84 /**
85 * Creates an endpoint with the specified implementor object. If there is
86 * a binding specified via a BindingType annotation then it MUST be used else
87 * a default of SOAP 1.1 / HTTP binding MUST be used.
88 * <p>
89 * The newly created endpoint may be published by calling
90 * one of the {@link javax.xml.ws.Endpoint#publish(String)} and
91 * {@link javax.xml.ws.Endpoint#publish(Object)} methods.
92 *
93 *
94 * @param implementor The endpoint implementor.
95 *
96 * @return The newly created endpoint.
97 *
98 **/
99 public static Endpoint create(Object implementor) {
100 return create(null, implementor);
101 }
102
103 /**
104 * Creates an endpoint with the specified implementor object and web
105 * service features. If there is a binding specified via a BindingType
106 * annotation then it MUST be used else a default of SOAP 1.1 / HTTP
107 * binding MUST be used.
108 * <p>
109 * The newly created endpoint may be published by calling
110 * one of the {@link javax.xml.ws.Endpoint#publish(String)} and
111 * {@link javax.xml.ws.Endpoint#publish(Object)} methods.
112 *
113 *
114 * @param implementor The endpoint implementor.
115 * @param features A list of WebServiceFeature to configure on the
116 * endpoint. Supported features not in the {@code features
117 * } parameter will have their default values.
118 *
119 *
120 * @return The newly created endpoint.
121 * @since 1.7, JAX-WS 2.2
122 *
123 */
124 public static Endpoint create(Object implementor, WebServiceFeature ... features) {
125 return create(null, implementor, features);
126 }
127
128 /**
129 * Creates an endpoint with the specified binding type and
130 * implementor object.
131 * <p>
132 * The newly created endpoint may be published by calling
133 * one of the {@link javax.xml.ws.Endpoint#publish(String)} and
134 * {@link javax.xml.ws.Endpoint#publish(Object)} methods.
135 *
136 * @param bindingId A URI specifying the binding to use. If the bindingID is
137 * {@code null} and no binding is specified via a BindingType
138 * annotation then a default SOAP 1.1 / HTTP binding MUST be used.
139 *
140 * @param implementor The endpoint implementor.
141 *
142 * @return The newly created endpoint.
143 *
144 **/
145 public static Endpoint create(String bindingId, Object implementor) {
146 return Provider.provider().createEndpoint(bindingId, implementor);
147 }
148
149 /**
150 * Creates an endpoint with the specified binding type,
151 * implementor object, and web service features.
152 * <p>
153 * The newly created endpoint may be published by calling
154 * one of the {@link javax.xml.ws.Endpoint#publish(String)} and
155 * {@link javax.xml.ws.Endpoint#publish(Object)} methods.
156 *
157 * @param bindingId A URI specifying the binding to use. If the bindingID is
158 * {@code null} and no binding is specified via a BindingType
159 * annotation then a default SOAP 1.1 / HTTP binding MUST be used.
160 *
161 * @param implementor The endpoint implementor.
162 *
163 * @param features A list of WebServiceFeature to configure on the
164 * endpoint. Supported features not in the {@code features
165 * } parameter will have their default values.
166 *
167 * @return The newly created endpoint.
168 * @since 1.7, JAX-WS 2.2
169 */
170 public static Endpoint create(String bindingId, Object implementor, WebServiceFeature ... features) {
171 return Provider.provider().createEndpoint(bindingId, implementor, features);
172 }
173
174 /**
175 * Returns the binding for this endpoint.
176 *
177 * @return The binding for this endpoint
178 **/
179 public abstract Binding getBinding();
180
181 /**
182 * Returns the implementation object for this endpoint.
183 *
184 * @return The implementor for this endpoint
185 **/
186 public abstract Object getImplementor();
187
188 /**
189 * Publishes this endpoint at the given address.
190 * The necessary server infrastructure will be created and
191 * configured by the JAX-WS implementation using some default configuration.
192 * In order to get more control over the server configuration, please
193 * use the {@link javax.xml.ws.Endpoint#publish(Object)} method instead.
194 *
195 * @param address A URI specifying the address to use. The address
196 * MUST be compatible with the binding specified at the
197 * time the endpoint was created.
198 *
199 * @throws java.lang.IllegalArgumentException
200 * If the provided address URI is not usable
201 * in conjunction with the endpoint's binding.
202 *
203 * @throws java.lang.IllegalStateException
204 * If the endpoint has been published already or it has been stopped.
205 *
206 * @throws java.lang.SecurityException
207 * If a {@code java.lang.SecurityManger}
208 * is being used and the application doesn't have the
209 * {@code WebServicePermission("publishEndpoint")} permission.
210 **/
211 public abstract void publish(String address);
212
213 /**
214 * Creates and publishes an endpoint for the specified implementor
215 * object at the given address.
216 * <p>
217 * The necessary server infrastructure will be created and
218 * configured by the JAX-WS implementation using some default configuration.
219 *
220 * In order to get more control over the server configuration, please
221 * use the {@link javax.xml.ws.Endpoint#create(String,Object)} and
222 * {@link javax.xml.ws.Endpoint#publish(Object)} methods instead.
223 *
224 * @param address A URI specifying the address and transport/protocol
225 * to use. A http: URI MUST result in the SOAP 1.1/HTTP
226 * binding being used. Implementations may support other
227 * URI schemes.
228 * @param implementor The endpoint implementor.
229 *
230 * @return The newly created endpoint.
231 *
232 * @throws java.lang.SecurityException
233 * If a {@code java.lang.SecurityManger}
234 * is being used and the application doesn't have the
235 * {@code WebServicePermission("publishEndpoint")} permission.
236 *
237 **/
238 public static Endpoint publish(String address, Object implementor) {
239 return Provider.provider().createAndPublishEndpoint(address, implementor);
240 }
241
242 /**
243 * Creates and publishes an endpoint for the specified implementor
244 * object at the given address. The created endpoint is configured
245 * with the web service features.
246 * <p>
247 * The necessary server infrastructure will be created and
248 * configured by the JAX-WS implementation using some default configuration.
249 *
250 * In order to get more control over the server configuration, please
251 * use the {@link javax.xml.ws.Endpoint#create(String,Object)} and
252 * {@link javax.xml.ws.Endpoint#publish(Object)} methods instead.
253 *
254 * @param address A URI specifying the address and transport/protocol
255 * to use. A http: URI MUST result in the SOAP 1.1/HTTP
256 * binding being used. Implementations may support other
257 * URI schemes.
258 * @param implementor The endpoint implementor.
259 * @param features A list of WebServiceFeature to configure on the
260 * endpoint. Supported features not in the {@code features
261 * } parameter will have their default values.
262 * @return The newly created endpoint.
263 *
264 * @throws java.lang.SecurityException
265 * If a {@code java.lang.SecurityManger}
266 * is being used and the application doesn't have the
267 * {@code WebServicePermission("publishEndpoint")} permission.
268 * @since 1.7, JAX-WS 2.2
269 */
270 public static Endpoint publish(String address, Object implementor, WebServiceFeature ... features) {
271 return Provider.provider().createAndPublishEndpoint(address, implementor, features);
272 }
273
274 /**
275 * Publishes this endpoint at the provided server context.
276 * A server context encapsulates the server infrastructure
277 * and addressing information for a particular transport.
278 * For a call to this method to succeed, the server context
279 * passed as an argument to it MUST be compatible with the
280 * endpoint's binding.
281 *
282 * @param serverContext An object representing a server
283 * context to be used for publishing the endpoint.
284 *
285 * @throws java.lang.IllegalArgumentException
286 * If the provided server context is not
287 * supported by the implementation or turns
288 * out to be unusable in conjunction with the
289 * endpoint's binding.
290 *
291 * @throws java.lang.IllegalStateException
292 * If the endpoint has been published already or it has been stopped.
293 *
294 * @throws java.lang.SecurityException
295 * If a {@code java.lang.SecurityManger}
296 * is being used and the application doesn't have the
297 * {@code WebServicePermission("publishEndpoint")} permission.
298 **/
299 public abstract void publish(Object serverContext);
300
301 /**
302 * Publishes this endpoint at the provided server context.
303 * A server context encapsulates the server infrastructure
304 * and addressing information for a particular transport.
305 * For a call to this method to succeed, the server context
306 * passed as an argument to it MUST be compatible with the
307 * endpoint's binding.
308 *
309 * <p>
310 * This is meant for container developers to publish the
311 * the endpoints portably and not intended for the end
312 * developers.
313 *
314 *
315 * @param serverContext An object representing a server
316 * context to be used for publishing the endpoint.
317 *
318 * @throws java.lang.IllegalArgumentException
319 * If the provided server context is not
320 * supported by the implementation or turns
321 * out to be unusable in conjunction with the
322 * endpoint's binding.
323 *
324 * @throws java.lang.IllegalStateException
325 * If the endpoint has been published already or it has been stopped.
326 *
327 * @throws java.lang.SecurityException
328 * If a {@code java.lang.SecurityManger}
329 * is being used and the application doesn't have the
330 * {@code WebServicePermission("publishEndpoint")} permission.
331 * @since 1.7, JAX-WS 2.2
332 */
333 public void publish(HttpContext serverContext) {
334 throw new UnsupportedOperationException("JAX-WS 2.2 implementation must override this default behaviour.");
335 }
336
337 /**
338 * Stops publishing this endpoint.
339 *
340 * If the endpoint is not in a published state, this method
341 * has no effect.
342 *
343 **/
344 public abstract void stop();
345
346 /**
347 * Returns true if the endpoint is in the published state.
348 *
349 * @return {@code true} if the endpoint is in the published state.
350 **/
351 public abstract boolean isPublished();
352
353 /**
354 * Returns a list of metadata documents for the service.
355 *
356 * @return {@code List<javax.xml.transform.Source>} A list of metadata documents for the service
357 **/
358 public abstract List<javax.xml.transform.Source> getMetadata();
359
360 /**
361 * Sets the metadata for this endpoint.
362 *
363 * @param metadata A list of XML document sources containing
364 * metadata information for the endpoint (e.g.
365 * WSDL or XML Schema documents)
366 *
367 * @throws java.lang.IllegalStateException If the endpoint
368 * has already been published.
369 **/
370 public abstract void setMetadata(List<javax.xml.transform.Source> metadata);
371
372 /**
373 * Returns the executor for this {@code Endpoint}instance.
374 *
375 * The executor is used to dispatch an incoming request to
376 * the implementor object.
377 *
378 * @return The {@code java.util.concurrent.Executor} to be
379 * used to dispatch a request.
380 *
381 * @see java.util.concurrent.Executor
382 **/
383 public abstract java.util.concurrent.Executor getExecutor();
384
385 /**
386 * Sets the executor for this {@code Endpoint} instance.
387 *
388 * The executor is used to dispatch an incoming request to
389 * the implementor object.
390 *
391 * If this {@code Endpoint} is published using the
392 * {@code publish(Object)} method and the specified server
393 * context defines its own threading behavior, the executor
394 * may be ignored.
395 *
396 * @param executor The {@code java.util.concurrent.Executor}
397 * to be used to dispatch a request.
398 *
399 * @throws SecurityException If the instance does not support
400 * setting an executor for security reasons (e.g. the
401 * necessary permissions are missing).
402 *
403 * @see java.util.concurrent.Executor
404 **/
405 public abstract void setExecutor(java.util.concurrent.Executor executor);
406
407 /**
408 * Returns the property bag for this {@code Endpoint} instance.
409 *
410 * @return Map<String,Object> The property bag
411 * associated with this instance.
412 **/
413 public abstract Map<String,Object> getProperties();
414
415 /**
416 * Sets the property bag for this {@code Endpoint} instance.
417 *
418 * @param properties The property bag associated with
419 * this instance.
420 **/
421 public abstract void setProperties(Map<String,Object> properties);
422
423 /**
424 * Returns the {@code EndpointReference} associated with
425 * this {@code Endpoint} instance.
426 * <p>
427 * If the Binding for this {@code bindingProvider} is
428 * either SOAP1.1/HTTP or SOAP1.2/HTTP, then a
429 * {@code W3CEndpointReference} MUST be returned.
430 *
431 * @param referenceParameters Reference parameters to be associated with the
432 * returned {@code EndpointReference} instance.
433 * @return EndpointReference of this {@code Endpoint} instance.
434 * If the returned {@code EndpointReference} is of type
435 * {@code W3CEndpointReference} then it MUST contain the
436 * the specified {@code referenceParameters}.
437
438 * @throws WebServiceException If any error in the creation of
439 * the {@code EndpointReference} or if the {@code Endpoint} is
440 * not in the published state.
441 * @throws UnsupportedOperationException If this {@code BindingProvider}
442 * uses the XML/HTTP binding.
443 *
444 * @see W3CEndpointReference
445 *
446 * @since 1.6, JAX-WS 2.1
447 **/
448 public abstract EndpointReference getEndpointReference(Element... referenceParameters);
449
450 /**
451 * Returns the {@code EndpointReference} associated with
452 * this {@code Endpoint} instance.
453 *
454 * @param <T> The type of EndpointReference.
455 * @param clazz Specifies the type of EndpointReference that MUST be returned.
456 * @param referenceParameters Reference parameters to be associated with the
457 * returned {@code EndpointReference} instance.
458 * @return EndpointReference of type {@code clazz} of this
459 * {@code Endpoint} instance.
460 * If the returned {@code EndpointReference} is of type
461 * {@code W3CEndpointReference} then it MUST contain the
462 * the specified {@code referenceParameters}.
463
464 * @throws WebServiceException If any error in the creation of
465 * the {@code EndpointReference} or if the {@code Endpoint} is
466 * not in the published state or if the {@code clazz} is not a supported
467 * {@code EndpointReference} type.
468 * @throws UnsupportedOperationException If this {@code BindingProvider}
469 * uses the XML/HTTP binding.
470 *
471 *
472 * @since 1.6, JAX-WS 2.1
473 **/
474 public abstract <T extends EndpointReference> T getEndpointReference(Class<T> clazz,
475 Element... referenceParameters);
476
477 /**
478 * By setting a {@code EndpointContext}, JAX-WS runtime knows about
479 * addresses of other endpoints in an application. If multiple endpoints
480 * share different ports of a WSDL, then the multiple port addresses
481 * are patched when the WSDL is accessed.
482 *
483 * <p>
484 * This needs to be set before publishing the endpoints.
485 *
486 * @param ctxt that is shared for multiple endpoints
487 * @throws java.lang.IllegalStateException
488 * If the endpoint has been published already or it has been stopped.
489 *
490 * @since 1.7, JAX-WS 2.2
491 */
492 public void setEndpointContext(EndpointContext ctxt) {
493 throw new UnsupportedOperationException("JAX-WS 2.2 implementation must override this default behaviour.");
494 }
495 }