Mercurial > jdk8-mips64-public > jaxws / file revision
src/share/jaxws_classes/javax/xml/ws/Endpoint.java@f453f4eaf8b4
src/share/jaxws_classes/javax/xml/ws/Endpoint.java
Tue, 07 Nov 2017 18:54:04 -0800
- author
- asaha
- date
- Tue, 07 Nov 2017 18:54:04 -0800
- changeset 1528
- f453f4eaf8b4
- parent 0
- 373ffda63c9a
- permissions
- -rw-r--r--
Added tag jdk8u162-b06 for changeset 6095742f8034
1 /*
2 * Copyright (c) 2005, 2011, 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 */
26 package javax.xml.ws;
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;
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</code>
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</code> methods can be used to start publishing
45 * an endpoint, at which point it starts accepting incoming requests.
46 * Conversely, the <code>stop</code> 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</code> 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</code> and
54 * registering it with the endpoint.
55 *
56 * <p>Handler chains can be set using the contained <code>Binding</code>.
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 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 {
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";
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";
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 }
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 * </code> parameter will have their default values.
119 *
120 *
121 * @return The newly created endpoint.
122 * @since JAX-WS 2.2
123 *
124 */
125 public static Endpoint create(Object implementor, WebServiceFeature ... features) {
126 return create(null, implementor, features);
127 }
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</code> 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 }
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</code> 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 * </code> parameter will have their default values.
167 *
168 * @return The newly created endpoint.
169 * @since 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 }
175 /**
176 * Returns the binding for this endpoint.
177 *
178 * @return The binding for this endpoint
179 **/
180 public abstract Binding getBinding();
182 /**
183 * Returns the implementation object for this endpoint.
184 *
185 * @return The implementor for this endpoint
186 **/
187 public abstract Object getImplementor();
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</code>
209 * is being used and the application doesn't have the
210 * <code>WebServicePermission("publishEndpoint")</code> permission.
211 **/
212 public abstract void publish(String address);
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</code>
235 * is being used and the application doesn't have the
236 * <code>WebServicePermission("publishEndpoint")</code> permission.
237 *
238 **/
239 public static Endpoint publish(String address, Object implementor) {
240 return Provider.provider().createAndPublishEndpoint(address, implementor);
241 }
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 * </code> 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</code>
267 * is being used and the application doesn't have the
268 * <code>WebServicePermission("publishEndpoint")</code> permission.
269 * @since 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 }
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</code>
298 * is being used and the application doesn't have the
299 * <code>WebServicePermission("publishEndpoint")</code> permission.
300 **/
301 public abstract void publish(Object serverContext);
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</code>
331 * is being used and the application doesn't have the
332 * <code>WebServicePermission("publishEndpoint")</code> permission.
333 * @since 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 }
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();
348 /**
349 * Returns true if the endpoint is in the published state.
350 *
351 * @return <code>true</code> if the endpoint is in the published state.
352 **/
353 public abstract boolean isPublished();
355 /**
356 * Returns a list of metadata documents for the service.
357 *
358 * @return <code>List<javax.xml.transform.Source></code> A list of metadata documents for the service
359 **/
360 public abstract List<javax.xml.transform.Source> getMetadata();
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);
374 /**
375 * Returns the executor for this <code>Endpoint</code>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</code> to be
381 * used to dispatch a request.
382 *
383 * @see java.util.concurrent.Executor
384 **/
385 public abstract java.util.concurrent.Executor getExecutor();
387 /**
388 * Sets the executor for this <code>Endpoint</code> instance.
389 *
390 * The executor is used to dispatch an incoming request to
391 * the implementor object.
392 *
393 * If this <code>Endpoint</code> is published using the
394 * <code>publish(Object)</code> 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</code>
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);
410 /**
411 * Returns the property bag for this <code>Endpoint</code> instance.
412 *
413 * @return Map<String,Object> The property bag
414 * associated with this instance.
415 **/
416 public abstract Map<String,Object> getProperties();
418 /**
419 * Sets the property bag for this <code>Endpoint</code> instance.
420 *
421 * @param properties The property bag associated with
422 * this instance.
423 **/
424 public abstract void setProperties(Map<String,Object> properties);
426 /**
427 * Returns the <code>EndpointReference</code> associated with
428 * this <code>Endpoint</code> instance.
429 * <p>
430 * If the Binding for this <code>bindingProvider</code> is
431 * either SOAP1.1/HTTP or SOAP1.2/HTTP, then a
432 * <code>W3CEndpointReference</code> MUST be returned.
433 *
434 * @param referenceParameters Reference parameters to be associated with the
435 * returned <code>EndpointReference</code> instance.
436 * @return EndpointReference of this <code>Endpoint</code> instance.
437 * If the returned <code>EndpointReference</code> is of type
438 * <code>W3CEndpointReference</code> then it MUST contain the
439 * the specified <code>referenceParameters</code>.
441 * @throws WebServiceException If any error in the creation of
442 * the <code>EndpointReference</code> or if the <code>Endpoint</code> is
443 * not in the published state.
444 * @throws UnsupportedOperationException If this <code>BindingProvider</code>
445 * uses the XML/HTTP binding.
446 *
447 * @see W3CEndpointReference
448 *
449 * @since JAX-WS 2.1
450 **/
451 public abstract EndpointReference getEndpointReference(Element... referenceParameters);
454 /**
455 * Returns the <code>EndpointReference</code> associated with
456 * this <code>Endpoint</code> 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</code> instance.
461 * @return EndpointReference of type <code>clazz</code> of this
462 * <code>Endpoint</code> instance.
463 * If the returned <code>EndpointReference</code> is of type
464 * <code>W3CEndpointReference</code> then it MUST contain the
465 * the specified <code>referenceParameters</code>.
467 * @throws WebServiceException If any error in the creation of
468 * the <code>EndpointReference</code> or if the <code>Endpoint</code> is
469 * not in the published state or if the <code>clazz</code> is not a supported
470 * <code>EndpointReference</code> type.
471 * @throws UnsupportedOperationException If this <code>BindingProvider</code>
472 * uses the XML/HTTP binding.
473 *
474 *
475 * @since JAX-WS 2.1
476 **/
477 public abstract <T extends EndpointReference> T getEndpointReference(Class<T> clazz,
478 Element... referenceParameters);
480 /**
481 * By settng a <code>EndpointContext</code>, 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 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 }
