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 26package javax.xml.ws; 27 28import java.util.List; 29import java.util.Map; 30import javax.xml.ws.spi.Provider; 31import javax.xml.ws.spi.http.HttpContext; 32import javax.xml.ws.wsaddressing.W3CEndpointReference; 33import 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 **/ 72public 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} 496