001: /*
002: * Copyright 2007 Sun Microsystems, Inc. All rights reserved.
003: * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
004: */
005:
006: package javax.xml.ws;
007:
008: import java.util.List;
009: import java.util.Map;
010: import javax.xml.ws.spi.Provider;
011: import javax.xml.ws.wsaddressing.W3CEndpointReference;
012: import org.w3c.dom.Element;
013:
014: /**
015: * A Web service endpoint.
016: *
017: * <p>Endpoints are created using the static methods defined in this
018: * class. An endpoint is always tied to one <code>Binding</code>
019: * and one implementor, both set at endpoint creation time.
020: *
021: * <p>An endpoint is either in a published or an unpublished state.
022: * The <code>publish</code> methods can be used to start publishing
023: * an endpoint, at which point it starts accepting incoming requests.
024: * Conversely, the <code>stop</code> method can be used to stop
025: * accepting incoming requests and take the endpoint down.
026: * Once stopped, an endpoint cannot be published again.
027: *
028: * <p>An <code>Executor</code> may be set on the endpoint in order
029: * to gain better control over the threads used to dispatch incoming
030: * requests. For instance, thread pooling with certain parameters
031: * can be enabled by creating a <code>ThreadPoolExecutor</code> and
032: * registering it with the endpoint.
033: *
034: * <p>Handler chains can be set using the contained <code>Binding</code>.
035: *
036: * <p>An endpoint may have a list of metadata documents, such as WSDL
037: * and XMLSchema documents, bound to it. At publishing time, the
038: * JAX-WS implementation will try to reuse as much of that metadata
039: * as possible instead of generating new ones based on the annotations
040: * present on the implementor.
041: *
042: * @since JAX-WS 2.0
043: *
044: * @see javax.xml.ws.Binding
045: * @see javax.xml.ws.BindingType
046: * @see javax.xml.ws.soap.SOAPBinding
047: * @see java.util.concurrent.Executor
048: *
049: **/
050: public abstract class Endpoint {
051:
052: /** Standard property: name of WSDL service.
053: * <p>Type: javax.xml.namespace.QName
054: **/
055: public static final String WSDL_SERVICE = "javax.xml.ws.wsdl.service";
056:
057: /** Standard property: name of WSDL port.
058: * <p>Type: javax.xml.namespace.QName
059: **/
060: public static final String WSDL_PORT = "javax.xml.ws.wsdl.port";
061:
062: /**
063: * Creates an endpoint with the specified implementor object. If there is
064: * a binding specified via a BindingType annotation then it MUST be used else
065: * a default of SOAP 1.1 / HTTP binding MUST be used.
066: * <p>
067: * The newly created endpoint may be published by calling
068: * one of the {@link javax.xml.ws.Endpoint#publish(String)} and
069: * {@link javax.xml.ws.Endpoint#publish(Object)} methods.
070: *
071: *
072: * @param implementor The endpoint implementor.
073: *
074: * @return The newly created endpoint.
075: *
076: **/
077: public static Endpoint create(Object implementor) {
078: return create(null, implementor);
079: }
080:
081: /**
082: * Creates an endpoint with the specified binding type and
083: * implementor object.
084: * <p>
085: * The newly created endpoint may be published by calling
086: * one of the {@link javax.xml.ws.Endpoint#publish(String)} and
087: * {@link javax.xml.ws.Endpoint#publish(Object)} methods.
088: *
089: * @param bindingId A URI specifying the binding to use. If the bindingID is
090: * <code>null</code> and no binding is specified via a BindingType
091: * annotation then a default SOAP 1.1 / HTTP binding MUST be used.
092: *
093: * @param implementor The endpoint implementor.
094: *
095: * @return The newly created endpoint.
096: *
097: **/
098: public static Endpoint create(String bindingId, Object implementor) {
099: return Provider.provider().createEndpoint(bindingId,
100: implementor);
101: }
102:
103: /**
104: * Returns the binding for this endpoint.
105: *
106: * @return The binding for this endpoint
107: **/
108: public abstract Binding getBinding();
109:
110: /**
111: * Returns the implementation object for this endpoint.
112: *
113: * @return The implementor for this endpoint
114: **/
115: public abstract Object getImplementor();
116:
117: /**
118: * Publishes this endpoint at the given address.
119: * The necessary server infrastructure will be created and
120: * configured by the JAX-WS implementation using some default configuration.
121: * In order to get more control over the server configuration, please
122: * use the {@link javax.xml.ws.Endpoint#publish(Object)} method instead.
123: *
124: * @param address A URI specifying the address to use. The address
125: * MUST be compatible with the binding specified at the
126: * time the endpoint was created.
127: *
128: * @throws java.lang.IllegalArgumentException
129: * If the provided address URI is not usable
130: * in conjunction with the endpoint's binding.
131: *
132: * @throws java.lang.IllegalStateException
133: * If the endpoint has been published already or it has been stopped.
134: *
135: * @throws java.lang.SecurityException
136: * If a <code>java.lang.SecurityManger</code>
137: * is being used and the application doesn't have the
138: * <code>WebServicePermission("publishEndpoint")</code> permission.
139: **/
140: public abstract void publish(String address);
141:
142: /**
143: * Creates and publishes an endpoint for the specified implementor
144: * object at the given address.
145: * <p>
146: * The necessary server infrastructure will be created and
147: * configured by the JAX-WS implementation using some default configuration.
148: *
149: * In order to get more control over the server configuration, please
150: * use the {@link javax.xml.ws.Endpoint#create(String,Object)} and
151: * {@link javax.xml.ws.Endpoint#publish(Object)} methods instead.
152: *
153: * @param address A URI specifying the address and transport/protocol
154: * to use. A http: URI MUST result in the SOAP 1.1/HTTP
155: * binding being used. Implementations may support other
156: * URI schemes.
157: * @param implementor The endpoint implementor.
158: *
159: * @return The newly created endpoint.
160: *
161: * @throws java.lang.SecurityException
162: * If a <code>java.lang.SecurityManger</code>
163: * is being used and the application doesn't have the
164: * <code>WebServicePermission("publishEndpoint")</code> permission.
165: *
166: **/
167: public static Endpoint publish(String address, Object implementor) {
168: return Provider.provider().createAndPublishEndpoint(address,
169: implementor);
170: }
171:
172: /**
173: * Publishes this endpoint at the provided server context.
174: * A server context encapsulates the server infrastructure
175: * and addressing information for a particular transport.
176: * For a call to this method to succeed, the server context
177: * passed as an argument to it MUST be compatible with the
178: * endpoint's binding.
179: *
180: * @param serverContext An object representing a server
181: * context to be used for publishing the endpoint.
182: *
183: * @throws java.lang.IllegalArgumentException
184: * If the provided server context is not
185: * supported by the implementation or turns
186: * out to be unusable in conjunction with the
187: * endpoint's binding.
188: *
189: * @throws java.lang.IllegalStateException
190: * If the endpoint has been published already or it has been stopped.
191: *
192: * @throws java.lang.SecurityException
193: * If a <code>java.lang.SecurityManger</code>
194: * is being used and the application doesn't have the
195: * <code>WebServicePermission("publishEndpoint")</code> permission.
196: **/
197: public abstract void publish(Object serverContext);
198:
199: /**
200: * Stops publishing this endpoint.
201: *
202: * If the endpoint is not in a published state, this method
203: * has no effect.
204: *
205: **/
206: public abstract void stop();
207:
208: /**
209: * Returns true if the endpoint is in the published state.
210: *
211: * @return <code>true</code> if the endpoint is in the published state.
212: **/
213: public abstract boolean isPublished();
214:
215: /**
216: * Returns a list of metadata documents for the service.
217: *
218: * @return <code>List<javax.xml.transform.Source></code> A list of metadata documents for the service
219: **/
220: public abstract List<javax.xml.transform.Source> getMetadata();
221:
222: /**
223: * Sets the metadata for this endpoint.
224: *
225: * @param metadata A list of XML document sources containing
226: * metadata information for the endpoint (e.g.
227: * WSDL or XML Schema documents)
228: *
229: * @throws java.lang.IllegalStateException If the endpoint
230: * has already been published.
231: **/
232: public abstract void setMetadata(
233: List<javax.xml.transform.Source> metadata);
234:
235: /**
236: * Returns the executor for this <code>Endpoint</code>instance.
237: *
238: * The executor is used to dispatch an incoming request to
239: * the implementor object.
240: *
241: * @return The <code>java.util.concurrent.Executor</code> to be
242: * used to dispatch a request.
243: *
244: * @see java.util.concurrent.Executor
245: **/
246: public abstract java.util.concurrent.Executor getExecutor();
247:
248: /**
249: * Sets the executor for this <code>Endpoint</code> instance.
250: *
251: * The executor is used to dispatch an incoming request to
252: * the implementor object.
253: *
254: * If this <code>Endpoint</code> is published using the
255: * <code>publish(Object)</code> method and the specified server
256: * context defines its own threading behavior, the executor
257: * may be ignored.
258: *
259: * @param executor The <code>java.util.concurrent.Executor</code>
260: * to be used to dispatch a request.
261: *
262: * @throws SecurityException If the instance does not support
263: * setting an executor for security reasons (e.g. the
264: * necessary permissions are missing).
265: *
266: * @see java.util.concurrent.Executor
267: **/
268: public abstract void setExecutor(
269: java.util.concurrent.Executor executor);
270:
271: /**
272: * Returns the property bag for this <code>Endpoint</code> instance.
273: *
274: * @return Map<String,Object> The property bag
275: * associated with this instance.
276: **/
277: public abstract Map<String, Object> getProperties();
278:
279: /**
280: * Sets the property bag for this <code>Endpoint</code> instance.
281: *
282: * @param properties The property bag associated with
283: * this instance.
284: **/
285: public abstract void setProperties(Map<String, Object> properties);
286:
287: /**
288: * Returns the <code>EndpointReference</code> associated with
289: * this <code>Endpoint</code> instance.
290: * <p>
291: * If the Binding for this <code>bindingProvider</code> is
292: * either SOAP1.1/HTTP or SOAP1.2/HTTP, then a
293: * <code>W3CEndpointReference</code> MUST be returned.
294: *
295: * @param referenceParameters Reference parameters to be associated with the
296: * returned <code>EndpointReference</code> instance.
297: * @return EndpointReference of this <code>Endpoint</code> instance.
298: * If the returned <code>EndpointReference</code> is of type
299: * <code>W3CEndpointReference</code> then it MUST contain the
300: * the specified <code>referenceParameters</code>.
301:
302: * @throws WebServiceException If any error in the creation of
303: * the <code>EndpointReference</code> or if the <code>Endpoint</code> is
304: * not in the published state.
305: * @throws UnsupportedOperationException If this <code>BindingProvider</code>
306: * uses the XML/HTTP binding.
307: *
308: * @see W3CEndpointReference
309: *
310: * @since JAX-WS 2.1
311: **/
312: public abstract EndpointReference getEndpointReference(
313: Element... referenceParameters);
314:
315: /**
316: * Returns the <code>EndpointReference</code> associated with
317: * this <code>Endpoint</code> instance.
318: *
319: * @param clazz Specifies the type of EndpointReference that MUST be returned.
320: * @param referenceParameters Reference parameters to be associated with the
321: * returned <code>EndpointReference</code> instance.
322: * @return EndpointReference of type <code>clazz</code> of this
323: * <code>Endpoint<code> instance.
324: * If the returned <code>EndpointReference</code> is of type
325: * <code>W3CEndpointReference</code> then it MUST contain the
326: * the specified <code>referenceParameters</code>.
327:
328: * @throws WebServiceException If any error in the creation of
329: * the <code>EndpointReference</code> or if the <code>Endpoint</code> is
330: * not in the published state or if the <code>clazz</code> is not a supported
331: * <code>EndpointReference</code> type.
332: * @throws UnsupportedOperationException If this <code>BindingProvider</code>
333: * uses the XML/HTTP binding.
334: *
335: *
336: * @since JAX-WS 2.1
337: **/
338: public abstract <T extends EndpointReference> T getEndpointReference(
339: Class<T> clazz, Element... referenceParameters);
340: }
|