KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > xml > ws > spi > Provider


1 /*
2  * Copyright 2007 Sun Microsystems, Inc. All rights reserved.
3  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
4  *$Id: Provider.java,v 1.8.2.6 2007/03/09 23:51:10 kohlert Exp $
5  */
6
7 package javax.xml.ws.spi;
8
9 import java.net.URL JavaDoc;
10 import java.util.List JavaDoc;
11 import javax.xml.ws.Endpoint;
12 import javax.xml.ws.WebServiceException;
13 import javax.xml.ws.WebServiceFeature;
14 import javax.xml.namespace.QName JavaDoc;
15 import javax.xml.ws.EndpointReference;
16 import javax.xml.ws.wsaddressing.W3CEndpointReference;
17
18 import org.w3c.dom.Element JavaDoc;
19
20 /**
21  * Service provider for <code>ServiceDelegate</code> and
22  * <code>Endpoint</code> objects.
23  * <p>
24  *
25  * @since JAX-WS 2.0
26  */
27 public abstract class Provider {
28     
29     /**
30      * A constant representing the property used to lookup the
31      * name of a <code>Provider</code> implementation
32      * class.
33      */
34     static public final String JavaDoc JAXWSPROVIDER_PROPERTY
35             = "javax.xml.ws.spi.Provider";
36     
37     /**
38      * A constant representing the name of the default
39      * <code>Provider</code> implementation class.
40      **/
41     static private final String JavaDoc DEFAULT_JAXWSPROVIDER
42             = "com.sun.xml.internal.ws.spi.ProviderImpl";
43     
44     
45     /**
46      * Creates a new instance of Provider
47      */
48     protected Provider() {
49     }
50     
51     /**
52      *
53      * Creates a new provider object.
54      * <p>
55      * The algorithm used to locate the provider subclass to use consists
56      * of the following steps:
57      * <p>
58      * <ul>
59      * <li>
60      * If a resource with the name of
61      * <code>META-INF/services/javax.xml.ws.spi.Provider</code>
62      * exists, then its first line, if present, is used as the UTF-8 encoded
63      * name of the implementation class.
64      * </li>
65      * <li>
66      * If the $java.home/lib/jaxws.properties file exists and it is readable by
67      * the <code>java.util.Properties.load(InputStream)</code> method and it contains
68      * an entry whose key is <code>javax.xml.ws.spi.Provider</code>, then the value of
69      * that entry is used as the name of the implementation class.
70      * </li>
71      * <li>
72      * If a system property with the name <code>javax.xml.ws.spi.Provider</code>
73      * is defined, then its value is used as the name of the implementation class.
74      * </li>
75      * <li>
76      * Finally, a default implementation class name is used.
77      * </li>
78      * </ul>
79      *
80      */
81     public static Provider provider() {
82         try {
83             Object JavaDoc provider =
84                     FactoryFinder.find(JAXWSPROVIDER_PROPERTY,
85                     DEFAULT_JAXWSPROVIDER);
86             if (!(provider instanceof Provider)) {
87                 Class JavaDoc pClass = Provider.class;
88                 String JavaDoc classnameAsResource = pClass.getName().replace('.', '/') + ".class";
89                 ClassLoader JavaDoc loader = pClass.getClassLoader();
90                 if(loader == null) {
91                     loader = ClassLoader.getSystemClassLoader();
92                 }
93                 URL JavaDoc targetTypeURL = loader.getResource(classnameAsResource);
94                 throw new LinkageError JavaDoc("ClassCastException: attempting to cast" +
95                        provider.getClass().getClassLoader().getResource(classnameAsResource) +
96                        "to" + targetTypeURL.toString() );
97             }
98             return (Provider) provider;
99         } catch (WebServiceException ex) {
100             throw ex;
101         } catch (Exception JavaDoc ex) {
102             throw new WebServiceException("Unable to createEndpointReference Provider", ex);
103         }
104     }
105     
106     /**
107      * Creates a service delegate object.
108      * <p>
109      * @param wsdlDocumentLocation A URL pointing to the WSDL document
110      * for the service, or <code>null</code> if there isn't one.
111      * @param serviceName The qualified name of the service.
112      * @param serviceClass The service class, which MUST be either
113      * <code>javax.xml.ws.Service</code> or a subclass thereof.
114      * @return The newly created service delegate.
115      */
116     public abstract ServiceDelegate createServiceDelegate(
117             java.net.URL JavaDoc wsdlDocumentLocation,
118             QName JavaDoc serviceName, Class JavaDoc serviceClass);
119     
120     
121     /**
122      *
123      * Creates an endpoint object with the provided binding and implementation
124      * object.
125      *
126      * @param bindingId A URI specifying the desired binding (e.g. SOAP/HTTP)
127      * @param implementor A service implementation object to which
128      * incoming requests will be dispatched. The corresponding
129      * class MUST be annotated with all the necessary Web service
130      * annotations.
131      * @return The newly created endpoint.
132      */
133     public abstract Endpoint createEndpoint(String JavaDoc bindingId,
134             Object JavaDoc implementor);
135     
136     
137     /**
138      * Creates and publishes an endpoint object with the specified
139      * address and implementation object.
140      *
141      * @param address A URI specifying the address and transport/protocol
142      * to use. A http: URI MUST result in the SOAP 1.1/HTTP
143      * binding being used. Implementations may support other
144      * URI schemes.
145      * @param implementor A service implementation object to which
146      * incoming requests will be dispatched. The corresponding
147      * class MUST be annotated with all the necessary Web service
148      * annotations.
149      * @return The newly created endpoint.
150      */
151     public abstract Endpoint createAndPublishEndpoint(String JavaDoc address,
152             Object JavaDoc implementor);
153     /**
154      * read an EndpointReference from the infoset contained in
155      * <code>eprInfoset</code>.
156      *
157      * @return the <code>EndpointReference</code> unmarshalled from
158      * <code>eprInfoset</code>. This method never returns <code>null</code>.
159      *
160      * @throws WebServiceException If there is an error creating the
161      * <code>EndpointReference</code> from the specified <code>eprInfoset</code>.
162      *
163      * @throws NullPointerException If the <code>null</code>
164      * <code>eprInfoset</code> value is given.
165      *
166      * @since JAX-WS 2.1
167      **/
168     public abstract EndpointReference readEndpointReference(javax.xml.transform.Source JavaDoc eprInfoset);
169      
170     
171     /**
172      * The getPort method returns a proxy. If there
173      * are any reference parameters in the
174      * <code>endpointReference</code>, then those reference
175      * parameters MUST appear as SOAP headers, indicating them to be
176      * reference parameters, on all messages sent to the endpoint.
177      * The parameter <code>serviceEndpointInterface</code> specifies
178      * the service endpoint interface that is supported by the
179      * returned proxy.
180      * The parameter <code>endpointReference</code> specifies the
181      * endpoint that will be invoked by the returned proxy.
182      * In the implementation of this method, the JAX-WS
183      * runtime system takes the responsibility of selecting a protocol
184      * binding (and a port) and configuring the proxy accordingly from
185      * the WSDL metadata of the
186      * <code>serviceEndpointInterface</code> and the <code>EndpointReference</code>.
187      * For this method
188      * to successfully return a proxy, WSDL metadata MUST be available and the
189      * <code>endpointReference</code> MUST contain an implementation understood
190      * <code>serviceName</code> metadata.
191      *
192      *
193      * @param endpointReference the EndpointReference that will
194      * be invoked by the returned proxy.
195      * @param serviceEndpointInterface Service endpoint interface
196      * @param features A list of WebServiceFeatures to configure on the
197      * proxy. Supported features not in the <code>features
198      * </code> parameter will have their default values.
199      * @return Object Proxy instance that supports the
200      * specified service endpoint interface
201      * @throws WebServiceException
202      * <UL>
203      * <LI>If there is an error during creation
204      * of the proxy
205      * <LI>If there is any missing WSDL metadata
206      * as required by this method}
207      * <LI>If this
208      * <code>endpointReference</code>
209      * is illegal
210      * <LI>If an illegal
211      * <code>serviceEndpointInterface</code>
212      * is specified
213      * <LI>If a feature is enabled that is not compatible with
214      * this port or is unsupported.
215      * </UL>
216      *
217      * @see WebServiceFeature
218      *
219      * @since JAX-WS 2.1
220      **/
221     public abstract <T> T getPort(EndpointReference endpointReference,
222             Class JavaDoc<T> serviceEndpointInterface,
223             WebServiceFeature... features);
224     
225     /**
226      * Factory method to create a <code>W3CEndpointReference</code>.
227      *
228      * <p>
229      * This method can be used to create a <code>W3CEndpointReference</code>
230      * for any endpoint by specifying the <code>address</code> property along
231      * with any other desired properties. This method
232      * can also be used to create a <code>W3CEndpointReference</code> for
233      * an endpoint that is published by the same Java EE application.
234      * To do so the <code>address</code> property can be provided or this
235      * method can automatically determine the <code>address</code> of
236      * an endpoint that is published by the same Java EE application and is
237      * identified by the <code>serviceName</code> and
238      * <code>portName</code> propeties. If the <code>address</code> is
239      * <code>null</code> and the <code>serviceName</code> and
240      * <code>portName</code> do not identify an endpoint published by the
241      * same Java EE application, a
242      * <code>javax.lang.IllegalStateException</code> MUST be thrown.
243      *
244      * @param address Specifies the address of the target endpoint
245      * @param serviceName Qualified name of the service in the WSDL.
246      * @param portName Qualified name of the endpoint in the WSDL.
247      * @param metadata A list of elements that should be added to the
248      * <code>W3CEndpointReference</code> instances <code>wsa:metadata</code>
249      * element.
250      * @param wsdlDocumentLocation URL for the WSDL document location for
251      * the service.
252      * @param referenceParameters Reference parameters to be associated
253      * with the returned <code>EndpointReference</code> instance.
254      *
255      * @return the <code>W3CEndpointReference<code> created from
256      * <code>serviceName</code>, <code>portName</code>,
257      * <code>metadata</code>, <code>wsdlDocumentLocation</code>
258      * and <code>referenceParameters</code>. This method
259      * never returns <code>null</code>.
260      *
261      * @throws java.lang.IllegalStateException
262      * <ul>
263      * <li>If the <code>address</code>, <code>serviceName</code> and
264      * <code>portName</code> are all <code>null</code>.
265      * <li>If the <code>serviceName</code> service is <code>null</code> and the
266      * <code>portName> is NOT <code>null</code>.
267      * <li>If the <code>address</code> property is <code>null</code> and
268      * the <code>serviceName</code> and <code>portName</code> do not
269      * specify a valid endpoint published by the same Java EE
270      * application.
271      * <li>If the <code>serviceName</code>is NOT <code>null</code>
272      * and is not present in the specified WSDL.
273      * <li>If the <code>portName</code> port is not <code>null<code> and it
274      * is not present in <code>serviceName</code> service in the WSDL.
275      * <li>If the <code>wsdlDocumentLocation</code> is NOT <code>null</code>
276      * and does not represent a valid WSDL.
277      * </ul>
278      * @throws WebServiceException If an error occurs while creating the
279      * <code>W3CEndpointReference</code>.
280      *
281      * @since JAX-WS 2.1
282      */
283     public abstract W3CEndpointReference createW3CEndpointReference(String JavaDoc address, QName JavaDoc serviceName, QName JavaDoc portName,
284             List JavaDoc<Element JavaDoc> metadata, String JavaDoc wsdlDocumentLocation, List JavaDoc<Element JavaDoc> referenceParameters);
285 }
286
Popular Tags