001: /*
002: * Copyright 2007 Sun Microsystems, Inc. All rights reserved.
003: * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
004: *$Id: Provider.java,v 1.8.2.7 2007/03/15 00:32:45 kohlert Exp $
005: */
006:
007: package javax.xml.ws.spi;
008:
009: import java.net.URL;
010: import java.util.List;
011: import javax.xml.ws.Endpoint;
012: import javax.xml.ws.WebServiceException;
013: import javax.xml.ws.WebServiceFeature;
014: import javax.xml.namespace.QName;
015: import javax.xml.ws.EndpointReference;
016: import javax.xml.ws.wsaddressing.W3CEndpointReference;
017:
018: import org.w3c.dom.Element;
019:
020: /**
021: * Service provider for <code>ServiceDelegate</code> and
022: * <code>Endpoint</code> objects.
023: * <p>
024: *
025: * @since JAX-WS 2.0
026: */
027: public abstract class Provider {
028:
029: /**
030: * A constant representing the property used to lookup the
031: * name of a <code>Provider</code> implementation
032: * class.
033: */
034: static public final String JAXWSPROVIDER_PROPERTY = "javax.xml.ws.spi.Provider";
035:
036: /**
037: * A constant representing the name of the default
038: * <code>Provider</code> implementation class.
039: **/
040: static private final String DEFAULT_JAXWSPROVIDER = "com.sun.xml.ws.spi.ProviderImpl";
041:
042: /**
043: * Creates a new instance of Provider
044: */
045: protected Provider() {
046: }
047:
048: /**
049: *
050: * Creates a new provider object.
051: * <p>
052: * The algorithm used to locate the provider subclass to use consists
053: * of the following steps:
054: * <p>
055: * <ul>
056: * <li>
057: * If a resource with the name of
058: * <code>META-INF/services/javax.xml.ws.spi.Provider</code>
059: * exists, then its first line, if present, is used as the UTF-8 encoded
060: * name of the implementation class.
061: * </li>
062: * <li>
063: * If the $java.home/lib/jaxws.properties file exists and it is readable by
064: * the <code>java.util.Properties.load(InputStream)</code> method and it contains
065: * an entry whose key is <code>javax.xml.ws.spi.Provider</code>, then the value of
066: * that entry is used as the name of the implementation class.
067: * </li>
068: * <li>
069: * If a system property with the name <code>javax.xml.ws.spi.Provider</code>
070: * is defined, then its value is used as the name of the implementation class.
071: * </li>
072: * <li>
073: * Finally, a default implementation class name is used.
074: * </li>
075: * </ul>
076: *
077: */
078: public static Provider provider() {
079: try {
080: Object provider = FactoryFinder.find(
081: JAXWSPROVIDER_PROPERTY, DEFAULT_JAXWSPROVIDER);
082: if (!(provider instanceof Provider)) {
083: Class pClass = Provider.class;
084: String classnameAsResource = pClass.getName().replace(
085: '.', '/')
086: + ".class";
087: ClassLoader loader = pClass.getClassLoader();
088: if (loader == null) {
089: loader = ClassLoader.getSystemClassLoader();
090: }
091: URL targetTypeURL = loader
092: .getResource(classnameAsResource);
093: throw new LinkageError(
094: "ClassCastException: attempting to cast"
095: + provider.getClass().getClassLoader()
096: .getResource(
097: classnameAsResource)
098: + "to" + targetTypeURL.toString());
099: }
100: return (Provider) provider;
101: } catch (WebServiceException ex) {
102: throw ex;
103: } catch (Exception ex) {
104: throw new WebServiceException(
105: "Unable to createEndpointReference Provider", ex);
106: }
107: }
108:
109: /**
110: * Creates a service delegate object.
111: * <p>
112: * @param wsdlDocumentLocation A URL pointing to the WSDL document
113: * for the service, or <code>null</code> if there isn't one.
114: * @param serviceName The qualified name of the service.
115: * @param serviceClass The service class, which MUST be either
116: * <code>javax.xml.ws.Service</code> or a subclass thereof.
117: * @return The newly created service delegate.
118: */
119: public abstract ServiceDelegate createServiceDelegate(
120: java.net.URL wsdlDocumentLocation, QName serviceName,
121: Class serviceClass);
122:
123: /**
124: *
125: * Creates an endpoint object with the provided binding and implementation
126: * object.
127: *
128: * @param bindingId A URI specifying the desired binding (e.g. SOAP/HTTP)
129: * @param implementor A service implementation object to which
130: * incoming requests will be dispatched. The corresponding
131: * class MUST be annotated with all the necessary Web service
132: * annotations.
133: * @return The newly created endpoint.
134: */
135: public abstract Endpoint createEndpoint(String bindingId,
136: Object implementor);
137:
138: /**
139: * Creates and publishes an endpoint object with the specified
140: * address and implementation object.
141: *
142: * @param address A URI specifying the address and transport/protocol
143: * to use. A http: URI MUST result in the SOAP 1.1/HTTP
144: * binding being used. Implementations may support other
145: * URI schemes.
146: * @param implementor A service implementation object to which
147: * incoming requests will be dispatched. The corresponding
148: * class MUST be annotated with all the necessary Web service
149: * annotations.
150: * @return The newly created endpoint.
151: */
152: public abstract Endpoint createAndPublishEndpoint(String address,
153: Object implementor);
154:
155: /**
156: * read an EndpointReference from the infoset contained in
157: * <code>eprInfoset</code>.
158: *
159: * @return the <code>EndpointReference</code> unmarshalled from
160: * <code>eprInfoset</code>. This method never returns <code>null</code>.
161: *
162: * @throws WebServiceException If there is an error creating the
163: * <code>EndpointReference</code> from the specified <code>eprInfoset</code>.
164: *
165: * @throws NullPointerException If the <code>null</code>
166: * <code>eprInfoset</code> value is given.
167: *
168: * @since JAX-WS 2.1
169: **/
170: public abstract EndpointReference readEndpointReference(
171: javax.xml.transform.Source eprInfoset);
172:
173: /**
174: * The getPort method returns a proxy. If there
175: * are any reference parameters in the
176: * <code>endpointReference</code>, then those reference
177: * parameters MUST appear as SOAP headers, indicating them to be
178: * reference parameters, on all messages sent to the endpoint.
179: * The parameter <code>serviceEndpointInterface</code> specifies
180: * the service endpoint interface that is supported by the
181: * returned proxy.
182: * The parameter <code>endpointReference</code> specifies the
183: * endpoint that will be invoked by the returned proxy.
184: * In the implementation of this method, the JAX-WS
185: * runtime system takes the responsibility of selecting a protocol
186: * binding (and a port) and configuring the proxy accordingly from
187: * the WSDL metadata of the
188: * <code>serviceEndpointInterface</code> and the <code>EndpointReference</code>.
189: * For this method
190: * to successfully return a proxy, WSDL metadata MUST be available and the
191: * <code>endpointReference</code> MUST contain an implementation understood
192: * <code>serviceName</code> metadata.
193: *
194: *
195: * @param endpointReference the EndpointReference that will
196: * be invoked by the returned proxy.
197: * @param serviceEndpointInterface Service endpoint interface
198: * @param features A list of WebServiceFeatures to configure on the
199: * proxy. Supported features not in the <code>features
200: * </code> parameter will have their default values.
201: * @return Object Proxy instance that supports the
202: * specified service endpoint interface
203: * @throws WebServiceException
204: * <UL>
205: * <LI>If there is an error during creation
206: * of the proxy
207: * <LI>If there is any missing WSDL metadata
208: * as required by this method}
209: * <LI>If this
210: * <code>endpointReference</code>
211: * is illegal
212: * <LI>If an illegal
213: * <code>serviceEndpointInterface</code>
214: * is specified
215: * <LI>If a feature is enabled that is not compatible with
216: * this port or is unsupported.
217: * </UL>
218: *
219: * @see WebServiceFeature
220: *
221: * @since JAX-WS 2.1
222: **/
223: public abstract <T> T getPort(EndpointReference endpointReference,
224: Class<T> serviceEndpointInterface,
225: WebServiceFeature... features);
226:
227: /**
228: * Factory method to create a <code>W3CEndpointReference</code>.
229: *
230: * <p>
231: * This method can be used to create a <code>W3CEndpointReference</code>
232: * for any endpoint by specifying the <code>address</code> property along
233: * with any other desired properties. This method
234: * can also be used to create a <code>W3CEndpointReference</code> for
235: * an endpoint that is published by the same Java EE application.
236: * To do so the <code>address</code> property can be provided or this
237: * method can automatically determine the <code>address</code> of
238: * an endpoint that is published by the same Java EE application and is
239: * identified by the <code>serviceName</code> and
240: * <code>portName</code> propeties. If the <code>address</code> is
241: * <code>null</code> and the <code>serviceName</code> and
242: * <code>portName</code> do not identify an endpoint published by the
243: * same Java EE application, a
244: * <code>javax.lang.IllegalStateException</code> MUST be thrown.
245: *
246: * @param address Specifies the address of the target endpoint
247: * @param serviceName Qualified name of the service in the WSDL.
248: * @param portName Qualified name of the endpoint in the WSDL.
249: * @param metadata A list of elements that should be added to the
250: * <code>W3CEndpointReference</code> instances <code>wsa:metadata</code>
251: * element.
252: * @param wsdlDocumentLocation URL for the WSDL document location for
253: * the service.
254: * @param referenceParameters Reference parameters to be associated
255: * with the returned <code>EndpointReference</code> instance.
256: *
257: * @return the <code>W3CEndpointReference<code> created from
258: * <code>serviceName</code>, <code>portName</code>,
259: * <code>metadata</code>, <code>wsdlDocumentLocation</code>
260: * and <code>referenceParameters</code>. This method
261: * never returns <code>null</code>.
262: *
263: * @throws java.lang.IllegalStateException
264: * <ul>
265: * <li>If the <code>address</code>, <code>serviceName</code> and
266: * <code>portName</code> are all <code>null</code>.
267: * <li>If the <code>serviceName</code> service is <code>null</code> and the
268: * <code>portName> is NOT <code>null</code>.
269: * <li>If the <code>address</code> property is <code>null</code> and
270: * the <code>serviceName</code> and <code>portName</code> do not
271: * specify a valid endpoint published by the same Java EE
272: * application.
273: * <li>If the <code>serviceName</code>is NOT <code>null</code>
274: * and is not present in the specified WSDL.
275: * <li>If the <code>portName</code> port is not <code>null<code> and it
276: * is not present in <code>serviceName</code> service in the WSDL.
277: * <li>If the <code>wsdlDocumentLocation</code> is NOT <code>null</code>
278: * and does not represent a valid WSDL.
279: * </ul>
280: * @throws WebServiceException If an error occurs while creating the
281: * <code>W3CEndpointReference</code>.
282: *
283: * @since JAX-WS 2.1
284: */
285: public abstract W3CEndpointReference createW3CEndpointReference(
286: String address, QName serviceName, QName portName,
287: List<Element> metadata, String wsdlDocumentLocation,
288: List<Element> referenceParameters);
289: }
|