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 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 /** 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 /** 105 * Creates an endpoint with the specified implementor object and web 106 * service features. If there is a binding specified via a BindingType 107 * annotation then it MUST be used else a default of SOAP 1.1 / HTTP 108 * binding MUST be used. 109 * <p> 110 * The newly created endpoint may be published by calling 111 * one of the {@link javax.xml.ws.Endpoint#publish(String)} and 112 * {@link javax.xml.ws.Endpoint#publish(Object)} methods. 113 * 114 * 115 * @param implementor The endpoint implementor. 116 * @param features A list of WebServiceFeature to configure on the 117 * endpoint. Supported features not in the {@code features 118 * } parameter will have their default values. 119 * 120 * 121 * @return The newly created endpoint. 122 * @since 1.7, JAX-WS 2.2 123 * 124 */ 125 public static Endpoint create(Object implementor, WebServiceFeature ... features) { 126 return create(null, implementor, features); 127 } 128 129 /** 130 * Creates an endpoint with the specified binding type and 131 * implementor object. 132 * <p> 133 * The newly created endpoint may be published by calling 134 * one of the {@link javax.xml.ws.Endpoint#publish(String)} and 135 * {@link javax.xml.ws.Endpoint#publish(Object)} methods. 136 * 137 * @param bindingId A URI specifying the binding to use. If the bindingID is 138 * {@code null} and no binding is specified via a BindingType 139 * annotation then a default SOAP 1.1 / HTTP binding MUST be used. 140 * 141 * @param implementor The endpoint implementor. 142 * 143 * @return The newly created endpoint. 144 * 145 **/ 146 public static Endpoint create(String bindingId, Object implementor) { 147 return Provider.provider().createEndpoint(bindingId, implementor); 148 } 149 150 /** 151 * Creates an endpoint with the specified binding type, 152 * implementor object, and web service features. 153 * <p> 154 * The newly created endpoint may be published by calling 155 * one of the {@link javax.xml.ws.Endpoint#publish(String)} and 156 * {@link javax.xml.ws.Endpoint#publish(Object)} methods. 157 * 158 * @param bindingId A URI specifying the binding to use. If the bindingID is 159 * {@code null} and no binding is specified via a BindingType 160 * annotation then a default SOAP 1.1 / HTTP binding MUST be used. 161 * 162 * @param implementor The endpoint implementor. 163 * 164 * @param features A list of WebServiceFeature to configure on the 165 * endpoint. Supported features not in the {@code features 166 * } parameter will have their default values. 167 * 168 * @return The newly created endpoint. 169 * @since 1.7, JAX-WS 2.2 170 */ 171 public static Endpoint create(String bindingId, Object implementor, WebServiceFeature ... features) { 172 return Provider.provider().createEndpoint(bindingId, implementor, features); 173 } 174 175 /** 176 * Returns the binding for this endpoint. 177 * 178 * @return The binding for this endpoint 179 **/ 180 public abstract Binding getBinding(); 181 182 /** 183 * Returns the implementation object for this endpoint. 184 * 185 * @return The implementor for this endpoint 186 **/ 187 public abstract Object getImplementor(); 188 189 /** 190 * Publishes this endpoint at the given address. 191 * The necessary server infrastructure will be created and 192 * configured by the JAX-WS implementation using some default configuration. 193 * In order to get more control over the server configuration, please 194 * use the {@link javax.xml.ws.Endpoint#publish(Object)} method instead. 195 * 196 * @param address A URI specifying the address to use. The address 197 * MUST be compatible with the binding specified at the 198 * time the endpoint was created. 199 * 200 * @throws java.lang.IllegalArgumentException 201 * If the provided address URI is not usable 202 * in conjunction with the endpoint's binding. 203 * 204 * @throws java.lang.IllegalStateException 205 * If the endpoint has been published already or it has been stopped. 206 * 207 * @throws java.lang.SecurityException 208 * If a {@code java.lang.SecurityManger} 209 * is being used and the application doesn't have the 210 * {@code WebServicePermission("publishEndpoint")} permission. 211 **/ 212 public abstract void publish(String address); 213 214 /** 215 * Creates and publishes an endpoint for the specified implementor 216 * object at the given address. 217 * <p> 218 * The necessary server infrastructure will be created and 219 * configured by the JAX-WS implementation using some default configuration. 220 * 221 * In order to get more control over the server configuration, please 222 * use the {@link javax.xml.ws.Endpoint#create(String,Object)} and 223 * {@link javax.xml.ws.Endpoint#publish(Object)} methods instead. 224 * 225 * @param address A URI specifying the address and transport/protocol 226 * to use. A http: URI MUST result in the SOAP 1.1/HTTP 227 * binding being used. Implementations may support other 228 * URI schemes. 229 * @param implementor The endpoint implementor. 230 * 231 * @return The newly created endpoint. 232 * 233 * @throws java.lang.SecurityException 234 * If a {@code java.lang.SecurityManger} 235 * is being used and the application doesn't have the 236 * {@code WebServicePermission("publishEndpoint")} permission. 237 * 238 **/ 239 public static Endpoint publish(String address, Object implementor) { 240 return Provider.provider().createAndPublishEndpoint(address, implementor); 241 } 242 243 /** 244 * Creates and publishes an endpoint for the specified implementor 245 * object at the given address. The created endpoint is configured 246 * with the web service features. 247 * <p> 248 * The necessary server infrastructure will be created and 249 * configured by the JAX-WS implementation using some default configuration. 250 * 251 * In order to get more control over the server configuration, please 252 * use the {@link javax.xml.ws.Endpoint#create(String,Object)} and 253 * {@link javax.xml.ws.Endpoint#publish(Object)} methods instead. 254 * 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 * 296 * @throws java.lang.SecurityException 297 * If a {@code java.lang.SecurityManger} 298 * is being used and the application doesn't have the 299 * {@code WebServicePermission("publishEndpoint")} permission. 300 **/ 301 public abstract void publish(Object serverContext); 302 303 /** 304 * Publishes this endpoint at the provided server context. 305 * A server context encapsulates the server infrastructure 306 * and addressing information for a particular transport. 307 * For a call to this method to succeed, the server context 308 * passed as an argument to it MUST be compatible with the 309 * endpoint's binding. 310 * 311 * <p> 312 * This is meant for container developers to publish the 313 * the endpoints portably and not intended for the end 314 * developers. 315 * 316 * 317 * @param serverContext An object representing a server 318 * context to be used for publishing the endpoint. 319 * 320 * @throws java.lang.IllegalArgumentException 321 * If the provided server context is not 322 * supported by the implementation or turns 323 * out to be unusable in conjunction with the 324 * endpoint's binding. 325 * 326 * @throws java.lang.IllegalStateException 327 * If the endpoint has been published already or it has been stopped. 328 * 329 * @throws java.lang.SecurityException 330 * If a {@code java.lang.SecurityManger} 331 * is being used and the application doesn't have the 332 * {@code WebServicePermission("publishEndpoint")} permission. 333 * @since 1.7, JAX-WS 2.2 334 */ 335 public void publish(HttpContext serverContext) { 336 throw new UnsupportedOperationException("JAX-WS 2.2 implementation must override this default behaviour."); 337 } 338 339 /** 340 * Stops publishing this endpoint. 341 * 342 * If the endpoint is not in a published state, this method 343 * has no effect. 344 * 345 **/ 346 public abstract void stop(); 347 348 /** 349 * Returns true if the endpoint is in the published state. 350 * 351 * @return {@code true} if the endpoint is in the published state. 352 **/ 353 public abstract boolean isPublished(); 354 355 /** 356 * Returns a list of metadata documents for the service. 357 * 358 * @return {@code List<javax.xml.transform.Source>} A list of metadata documents for the service 359 **/ 360 public abstract List<javax.xml.transform.Source> getMetadata(); 361 362 /** 363 * Sets the metadata for this endpoint. 364 * 365 * @param metadata A list of XML document sources containing 366 * metadata information for the endpoint (e.g. 367 * WSDL or XML Schema documents) 368 * 369 * @throws java.lang.IllegalStateException If the endpoint 370 * has already been published. 371 **/ 372 public abstract void setMetadata(List<javax.xml.transform.Source> metadata); 373 374 /** 375 * Returns the executor for this {@code Endpoint}instance. 376 * 377 * The executor is used to dispatch an incoming request to 378 * the implementor object. 379 * 380 * @return The {@code java.util.concurrent.Executor} to be 381 * used to dispatch a request. 382 * 383 * @see java.util.concurrent.Executor 384 **/ 385 public abstract java.util.concurrent.Executor getExecutor(); 386 387 /** 388 * Sets the executor for this {@code Endpoint} instance. 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> 430 * If the Binding for this {@code bindingProvider} is 431 * either SOAP1.1/HTTP or SOAP1.2/HTTP, then a 432 * {@code W3CEndpointReference} MUST be returned. 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 }