Endpoint


1   /*
2    * Copyright 2007 Sun Microsystems, Inc. All rights reserved.
3    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
4    */
5   
6   package javax.xml.ws;
7   
8   import java.util.List  ;
9   import java.util.Map  ;
10  import javax.xml.ws.spi.Provider;
11  import javax.xml.ws.wsaddressing.W3CEndpointReference;
12  import org.w3c.dom.Element  ;
13  
14  
15  /**
16   * A Web service endpoint.
17   *
18   * <p>Endpoints are created using the static methods defined in this
19   * class. An endpoint is always tied to one <code>Binding</code>
20   * and one implementor, both set at endpoint creation time.
21   *
22   * <p>An endpoint is either in a published or an unpublished state.
23   * The <code>publish</code> methods can be used to start publishing
24   * an endpoint, at which point it starts accepting incoming requests.
25   * Conversely, the <code>stop</code> method can be used to stop
26   * accepting incoming requests and take the endpoint down.
27   * Once stopped, an endpoint cannot be published again.
28   *
29   * <p>An <code>Executor</code> may be set on the endpoint in order
30   * to gain better control over the threads used to dispatch incoming
31   * requests. For instance, thread pooling with certain parameters
32   * can be enabled by creating a <code>ThreadPoolExecutor</code> and
33   * registering it with the endpoint.
34   *
35   * <p>Handler chains can be set using the contained <code>Binding</code>.
36   *
37   * <p>An endpoint may have a list of metadata documents, such as WSDL
38   * and XMLSchema documents, bound to it. At publishing time, the
39   * JAX-WS implementation will try to reuse as much of that metadata
40   * as possible instead of generating new ones based on the annotations
41   * present on the implementor.
42   *
43   * @since JAX-WS 2.0
44   *
45   * @see javax.xml.ws.Binding
46   * @see javax.xml.ws.BindingType
47   * @see javax.xml.ws.soap.SOAPBinding
48   * @see java.util.concurrent.Executor
49   *
50   **/
51  public abstract class Endpoint {
52      
53      /** Standard property: name of WSDL service.
54       *  <p>Type: javax.xml.namespace.QName
55       **/
56      public static final String   WSDL_SERVICE = "javax.xml.ws.wsdl.service";
57      
58      /** Standard property: name of WSDL port.
59       *  <p>Type: javax.xml.namespace.QName
60       **/
61      public static final String   WSDL_PORT = "javax.xml.ws.wsdl.port";
62      
63      
64      /**
65       * Creates an endpoint with the specified implementor object. If there is
66       * a binding specified via a BindingType annotation then it MUST be used else
67       * a default of SOAP 1.1 / HTTP binding MUST be used.
68       * <p>
69       * The newly created endpoint may be published by calling
70       * one of the {@link javax.xml.ws.Endpoint#publish(String)} and
71       * {@link javax.xml.ws.Endpoint#publish(Object)} methods.
72       *
73       *
74       * @param implementor The endpoint implementor.
75       *
76       * @return The newly created endpoint.
77       *
78       **/
79      public static Endpoint create(Object   implementor) {
80          return create(null, implementor);
81      }
82      
83      /**
84       * Creates an endpoint with the specified binding type and
85       * implementor object.
86       * <p>
87       * The newly created endpoint may be published by calling
88       * one of the {@link javax.xml.ws.Endpoint#publish(String)} and
89       * {@link javax.xml.ws.Endpoint#publish(Object)} methods.
90       *
91       * @param bindingId A URI specifying the binding to use. If the bindingID is
92       * <code>null</code> and no binding is specified via a BindingType
93       * annotation then a default SOAP 1.1 / HTTP binding MUST be used.
94       *
95       * @param implementor The endpoint implementor.
96       *
97       * @return The newly created endpoint.
98       *
99       **/
100     public static Endpoint create(String   bindingId, Object   implementor) {
101         return Provider.provider().createEndpoint(bindingId, implementor);
102     }
103     
104     
105     /**
106      * Returns the binding for this endpoint.
107      *
108      * @return The binding for this endpoint
109      **/
110     public abstract Binding getBinding();
111     
112     /**
113      * Returns the implementation object for this endpoint.
114      *
115      * @return The implementor for this endpoint
116      **/
117     public abstract Object   getImplementor();
118     
119     /**
120      * Publishes this endpoint at the given address.
121      * The necessary server infrastructure will be created and
122      * configured by the JAX-WS implementation using some default configuration.
123      * In order to get more control over the server configuration, please
124      * use the {@link javax.xml.ws.Endpoint#publish(Object)} method instead.
125      *
126      * @param address A URI specifying the address to use. The address
127      *        MUST be compatible with the binding specified at the
128      *        time the endpoint was created.
129      *
130      * @throws java.lang.IllegalArgumentException 
131      *          If the provided address URI is not usable
132      *          in conjunction with the endpoint's binding.
133      *
134      * @throws java.lang.IllegalStateException 
135      *          If the endpoint has been published already or it has been stopped.
136      *
137      * @throws java.lang.SecurityException 
138      *          If a <code>java.lang.SecurityManger</code>
139      *          is being used and the application doesn't have the
140      *          <code>WebServicePermission("publishEndpoint")</code> permission.
141      **/
142     public abstract void publish(String   address);
143     
144     /**
145      * Creates and publishes an endpoint for the specified implementor
146      * object at the given address.
147      * <p>
148      * The necessary server infrastructure will be created and
149      * configured by the JAX-WS implementation using some default configuration.
150      *
151      * In order to get more control over the server configuration, please
152      * use the {@link javax.xml.ws.Endpoint#create(String,Object)} and
153      * {@link javax.xml.ws.Endpoint#publish(Object)} methods instead.
154      *
155      * @param address A URI specifying the address and transport/protocol
156      *        to use. A http: URI MUST result in the SOAP 1.1/HTTP
157      *        binding being used. Implementations may support other
158      *        URI schemes.
159      * @param implementor The endpoint implementor.
160      *
161      * @return The newly created endpoint.
162      *
163      * @throws java.lang.SecurityException 
164      *          If a <code>java.lang.SecurityManger</code>
165      *          is being used and the application doesn't have the
166      *          <code>WebServicePermission("publishEndpoint")</code> permission.
167      *
168      **/
169     public static Endpoint publish(String   address, Object   implementor) {
170         return Provider.provider().createAndPublishEndpoint(address, implementor);
171     }
172     
173     /**
174      * Publishes this endpoint at the provided server context.
175      * A server context encapsulates the server infrastructure
176      * and addressing information for a particular transport.
177      * For a call to this method to succeed, the server context
178      * passed as an argument to it MUST be compatible with the
179      * endpoint's binding.
180      *
181      * @param serverContext An object representing a server
182      *           context to be used for publishing the endpoint.
183      *
184      * @throws java.lang.IllegalArgumentException 
185      *              If the provided server context is not
186      *              supported by the implementation or turns
187      *              out to be unusable in conjunction with the
188      *              endpoint's binding.
189      *
190      * @throws java.lang.IllegalStateException 
191      *         If the endpoint has been published already or it has been stopped.
192      *
193      * @throws java.lang.SecurityException 
194      *          If a <code>java.lang.SecurityManger</code>
195      *          is being used and the application doesn't have the
196      *          <code>WebServicePermission("publishEndpoint")</code> permission.
197      **/
198     public abstract void publish(Object   serverContext);
199     
200     /**
201      * Stops publishing this endpoint.
202      *
203      * If the endpoint is not in a published state, this method
204      * has no effect.
205      *
206      **/
207     public abstract void stop();
208     
209     /**
210      * Returns true if the endpoint is in the published state.
211      *
212      * @return <code>true</code> if the endpoint is in the published state.
213      **/
214     public abstract boolean isPublished();
215     
216     /**
217      * Returns a list of metadata documents for the service.
218      *
219      * @return <code>List&lt;javax.xml.transform.Source&gt;</code> A list of metadata documents for the service
220      **/
221     public abstract List  <javax.xml.transform.Source  > getMetadata();
222     
223     /**
224      * Sets the metadata for this endpoint.
225      *
226      * @param metadata A list of XML document sources containing
227      *           metadata information for the endpoint (e.g.
228      *           WSDL or XML Schema documents)
229      *
230      * @throws java.lang.IllegalStateException  If the endpoint
231      *         has already been published.
232      **/
233     public abstract void setMetadata(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(java.util.concurrent.Executor   executor);
269     
270     
271     /**
272      * Returns the property bag for this <code>Endpoint</code> instance.
273      *
274      * @return Map&lt;String,Object&gt; 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(Element  ... referenceParameters);
313     
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(Class  <T> clazz,
339             Element  ... referenceParameters);
340 }
341
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags