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