1 /*
2 * Copyright (c) 2005, 2015, 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
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 /**
86 * Creates an endpoint with the specified implementor object. If there is
87 * a binding specified via a BindingType annotation then it MUST be used else
88 * a default of SOAP 1.1 / HTTP binding MUST be used.
89 * <p>
90 * The newly created endpoint may be published by calling
91 * one of the {@link javax.xml.ws.Endpoint#publish(String)} and
92 * {@link javax.xml.ws.Endpoint#publish(Object)} methods.
93 *
94 *
95 * @param implementor The endpoint implementor.
96 *
97 * @return The newly created endpoint.
98 *
99 **/
100 public static Endpoint create(Object implementor) {
101 return create(null, implementor);
102 }
103
104 /**
255 * @param address A URI specifying the address and transport/protocol
256 * to use. A http: URI MUST result in the SOAP 1.1/HTTP
257 * binding being used. Implementations may support other
258 * URI schemes.
259 * @param implementor The endpoint implementor.
260 * @param features A list of WebServiceFeature to configure on the
261 * endpoint. Supported features not in the {@code features
262 * } parameter will have their default values.
263 * @return The newly created endpoint.
264 *
265 * @throws java.lang.SecurityException
266 * If a {@code java.lang.SecurityManger}
267 * is being used and the application doesn't have the
268 * {@code WebServicePermission("publishEndpoint")} permission.
269 * @since 1.7, JAX-WS 2.2
270 */
271 public static Endpoint publish(String address, Object implementor, WebServiceFeature ... features) {
272 return Provider.provider().createAndPublishEndpoint(address, implementor, features);
273 }
274
275
276 /**
277 * Publishes this endpoint at the provided server context.
278 * A server context encapsulates the server infrastructure
279 * and addressing information for a particular transport.
280 * For a call to this method to succeed, the server context
281 * passed as an argument to it MUST be compatible with the
282 * endpoint's binding.
283 *
284 * @param serverContext An object representing a server
285 * context to be used for publishing the endpoint.
286 *
287 * @throws java.lang.IllegalArgumentException
288 * If the provided server context is not
289 * supported by the implementation or turns
290 * out to be unusable in conjunction with the
291 * endpoint's binding.
292 *
293 * @throws java.lang.IllegalStateException
294 * If the endpoint has been published already or it has been stopped.
295 *
389 *
390 * The executor is used to dispatch an incoming request to
391 * the implementor object.
392 *
393 * If this {@code Endpoint} is published using the
394 * {@code publish(Object)} method and the specified server
395 * context defines its own threading behavior, the executor
396 * may be ignored.
397 *
398 * @param executor The {@code java.util.concurrent.Executor}
399 * to be used to dispatch a request.
400 *
401 * @throws SecurityException If the instance does not support
402 * setting an executor for security reasons (e.g. the
403 * necessary permissions are missing).
404 *
405 * @see java.util.concurrent.Executor
406 **/
407 public abstract void setExecutor(java.util.concurrent.Executor executor);
408
409
410 /**
411 * Returns the property bag for this {@code Endpoint} instance.
412 *
413 * @return Map<String,Object> The property bag
414 * associated with this instance.
415 **/
416 public abstract Map<String,Object> getProperties();
417
418 /**
419 * Sets the property bag for this {@code Endpoint} instance.
420 *
421 * @param properties The property bag associated with
422 * this instance.
423 **/
424 public abstract void setProperties(Map<String,Object> properties);
425
426 /**
427 * Returns the {@code EndpointReference} associated with
428 * this {@code Endpoint} instance.
429 * <p>
433 *
434 * @param referenceParameters Reference parameters to be associated with the
435 * returned {@code EndpointReference} instance.
436 * @return EndpointReference of this {@code Endpoint} instance.
437 * If the returned {@code EndpointReference} is of type
438 * {@code W3CEndpointReference} then it MUST contain the
439 * the specified {@code referenceParameters}.
440
441 * @throws WebServiceException If any error in the creation of
442 * the {@code EndpointReference} or if the {@code Endpoint} is
443 * not in the published state.
444 * @throws UnsupportedOperationException If this {@code BindingProvider}
445 * uses the XML/HTTP binding.
446 *
447 * @see W3CEndpointReference
448 *
449 * @since 1.6, JAX-WS 2.1
450 **/
451 public abstract EndpointReference getEndpointReference(Element... referenceParameters);
452
453
454 /**
455 * Returns the {@code EndpointReference} associated with
456 * this {@code Endpoint} instance.
457 *
458 * @param clazz Specifies the type of EndpointReference that MUST be returned.
459 * @param referenceParameters Reference parameters to be associated with the
460 * returned {@code EndpointReference} instance.
461 * @return EndpointReference of type {@code clazz} of this
462 * {@code Endpoint} instance.
463 * If the returned {@code EndpointReference} is of type
464 * {@code W3CEndpointReference} then it MUST contain the
465 * the specified {@code referenceParameters}.
466
467 * @throws WebServiceException If any error in the creation of
468 * the {@code EndpointReference} or if the {@code Endpoint} is
469 * not in the published state or if the {@code clazz} is not a supported
470 * {@code EndpointReference} type.
471 * @throws UnsupportedOperationException If this {@code BindingProvider}
472 * uses the XML/HTTP binding.
473 *
474 *
475 * @since 1.6, JAX-WS 2.1
476 **/
477 public abstract <T extends EndpointReference> T getEndpointReference(Class<T> clazz,
478 Element... referenceParameters);
479
480 /**
481 * By settng a {@code EndpointContext}, JAX-WS runtime knows about
482 * addresses of other endpoints in an application. If multiple endpoints
483 * share different ports of a WSDL, then the multiple port addresses
484 * are patched when the WSDL is accessed.
485 *
486 * <p>
487 * This needs to be set before publishing the endpoints.
488 *
489 * @param ctxt that is shared for multiple endpoints
490 * @throws java.lang.IllegalStateException
491 * If the endpoint has been published already or it has been stopped.
492 *
493 * @since 1.7, JAX-WS 2.2
494 */
495 public void setEndpointContext(EndpointContext ctxt) {
496 throw new UnsupportedOperationException("JAX-WS 2.2 implementation must override this default behaviour.");
497 }
498 }
|
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
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 /**
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 *
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>
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 }
|