javax.xml.ws.spi.Provider Maven / Gradle / Ivy
/*
* Copyright 2007 Sun Microsystems, Inc. All rights reserved.
* SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
*$Id: Provider.java,v 1.8.2.7 2007/03/15 00:32:45 kohlert Exp $
*/
package javax.xml.ws.spi;
import java.net.URL;
import java.util.List;
import javax.xml.ws.Endpoint;
import javax.xml.ws.WebServiceException;
import javax.xml.ws.WebServiceFeature;
import javax.xml.namespace.QName;
import javax.xml.ws.EndpointReference;
import javax.xml.ws.wsaddressing.W3CEndpointReference;
import org.w3c.dom.Element;
/**
* Service provider for ServiceDelegate and
* Endpoint objects.
*
*
* @since JAX-WS 2.0
*/
public abstract class Provider {
/**
* A constant representing the property used to lookup the
* name of a Provider implementation
* class.
*/
static public final String JAXWSPROVIDER_PROPERTY
= "javax.xml.ws.spi.Provider";
/**
* A constant representing the name of the default
* Provider implementation class.
**/
static private final String DEFAULT_JAXWSPROVIDER
= "com.sun.xml.ws.spi.ProviderImpl";
/**
* Creates a new instance of Provider
*/
protected Provider() {
}
/**
*
* Creates a new provider object.
*
* The algorithm used to locate the provider subclass to use consists
* of the following steps:
*
*
* -
* If a resource with the name of
*
META-INF/services/javax.xml.ws.spi.Provider
* exists, then its first line, if present, is used as the UTF-8 encoded
* name of the implementation class.
*
* -
* If the $java.home/lib/jaxws.properties file exists and it is readable by
* the
java.util.Properties.load(InputStream) method and it contains
* an entry whose key is javax.xml.ws.spi.Provider, then the value of
* that entry is used as the name of the implementation class.
*
* -
* If a system property with the name
javax.xml.ws.spi.Provider
* is defined, then its value is used as the name of the implementation class.
*
* -
* Finally, a default implementation class name is used.
*
*
*
*/
public static Provider provider() {
try {
Object provider =
FactoryFinder.find(JAXWSPROVIDER_PROPERTY,
DEFAULT_JAXWSPROVIDER);
if (!(provider instanceof Provider)) {
Class pClass = Provider.class;
String classnameAsResource = pClass.getName().replace('.', '/') + ".class";
ClassLoader loader = pClass.getClassLoader();
if(loader == null) {
loader = ClassLoader.getSystemClassLoader();
}
URL targetTypeURL = loader.getResource(classnameAsResource);
throw new LinkageError("ClassCastException: attempting to cast" +
provider.getClass().getClassLoader().getResource(classnameAsResource) +
"to" + targetTypeURL.toString() );
}
return (Provider) provider;
} catch (WebServiceException ex) {
throw ex;
} catch (Exception ex) {
throw new WebServiceException("Unable to createEndpointReference Provider", ex);
}
}
/**
* Creates a service delegate object.
*
* @param wsdlDocumentLocation A URL pointing to the WSDL document
* for the service, or null if there isn't one.
* @param serviceName The qualified name of the service.
* @param serviceClass The service class, which MUST be either
* javax.xml.ws.Service or a subclass thereof.
* @return The newly created service delegate.
*/
public abstract ServiceDelegate createServiceDelegate(
java.net.URL wsdlDocumentLocation,
QName serviceName, Class serviceClass);
/**
*
* Creates an endpoint object with the provided binding and implementation
* object.
*
* @param bindingId A URI specifying the desired binding (e.g. SOAP/HTTP)
* @param implementor A service implementation object to which
* incoming requests will be dispatched. The corresponding
* class MUST be annotated with all the necessary Web service
* annotations.
* @return The newly created endpoint.
*/
public abstract Endpoint createEndpoint(String bindingId,
Object implementor);
/**
* Creates and publishes an endpoint object with the specified
* address and implementation object.
*
* @param address A URI specifying the address and transport/protocol
* to use. A http: URI MUST result in the SOAP 1.1/HTTP
* binding being used. Implementations may support other
* URI schemes.
* @param implementor A service implementation object to which
* incoming requests will be dispatched. The corresponding
* class MUST be annotated with all the necessary Web service
* annotations.
* @return The newly created endpoint.
*/
public abstract Endpoint createAndPublishEndpoint(String address,
Object implementor);
/**
* read an EndpointReference from the infoset contained in
* eprInfoset.
*
* @return the EndpointReference unmarshalled from
* eprInfoset. This method never returns null.
*
* @throws WebServiceException If there is an error creating the
* EndpointReference from the specified eprInfoset.
*
* @throws NullPointerException If the null
* eprInfoset value is given.
*
* @since JAX-WS 2.1
**/
public abstract EndpointReference readEndpointReference(javax.xml.transform.Source eprInfoset);
/**
* The getPort method returns a proxy. If there
* are any reference parameters in the
* endpointReference, then those reference
* parameters MUST appear as SOAP headers, indicating them to be
* reference parameters, on all messages sent to the endpoint.
* The parameter serviceEndpointInterface specifies
* the service endpoint interface that is supported by the
* returned proxy.
* The parameter endpointReference specifies the
* endpoint that will be invoked by the returned proxy.
* In the implementation of this method, the JAX-WS
* runtime system takes the responsibility of selecting a protocol
* binding (and a port) and configuring the proxy accordingly from
* the WSDL metadata of the
* serviceEndpointInterface and the EndpointReference.
* For this method
* to successfully return a proxy, WSDL metadata MUST be available and the
* endpointReference MUST contain an implementation understood
* serviceName metadata.
*
*
* @param endpointReference the EndpointReference that will
* be invoked by the returned proxy.
* @param serviceEndpointInterface Service endpoint interface
* @param features A list of WebServiceFeatures to configure on the
* proxy. Supported features not in the features
* parameter will have their default values.
* @return Object Proxy instance that supports the
* specified service endpoint interface
* @throws WebServiceException
*
* - If there is an error during creation
* of the proxy
*
- If there is any missing WSDL metadata
* as required by this method}
*
- If this
*
endpointReference
* is illegal
* - If an illegal
*
serviceEndpointInterface
* is specified
* - If a feature is enabled that is not compatible with
* this port or is unsupported.
*
*
* @see WebServiceFeature
*
* @since JAX-WS 2.1
**/
public abstract T getPort(EndpointReference endpointReference,
Class serviceEndpointInterface,
WebServiceFeature... features);
/**
* Factory method to create a W3CEndpointReference.
*
*
* This method can be used to create a W3CEndpointReference
* for any endpoint by specifying the address property along
* with any other desired properties. This method
* can also be used to create a W3CEndpointReference for
* an endpoint that is published by the same Java EE application.
* To do so the address property can be provided or this
* method can automatically determine the address of
* an endpoint that is published by the same Java EE application and is
* identified by the serviceName and
* portName propeties. If the address is
* null and the serviceName and
* portName do not identify an endpoint published by the
* same Java EE application, a
* javax.lang.IllegalStateException MUST be thrown.
*
* @param address Specifies the address of the target endpoint
* @param serviceName Qualified name of the service in the WSDL.
* @param portName Qualified name of the endpoint in the WSDL.
* @param metadata A list of elements that should be added to the
* W3CEndpointReference instances wsa:metadata
* element.
* @param wsdlDocumentLocation URL for the WSDL document location for
* the service.
* @param referenceParameters Reference parameters to be associated
* with the returned EndpointReference instance.
*
* @return the W3CEndpointReference created from
* serviceName, portName,
* metadata, wsdlDocumentLocation
* and referenceParameters. This method
* never returns null.
*
* @throws java.lang.IllegalStateException
*
* - If the
address, serviceName and
* portName are all null.
* - If the
serviceName service is null and the
* portName> is NOT null.
* - If the
address property is null and
* the serviceName and portName do not
* specify a valid endpoint published by the same Java EE
* application.
* - If the
serviceNameis NOT null
* and is not present in the specified WSDL.
* - If the
portName port is not null and it
* is not present in serviceName service in the WSDL.
* - If the
wsdlDocumentLocation is NOT null
* and does not represent a valid WSDL.
*
* @throws WebServiceException If an error occurs while creating the
* W3CEndpointReference.
*
* @since JAX-WS 2.1
*/
public abstract W3CEndpointReference createW3CEndpointReference(String address, QName serviceName, QName portName,
List metadata, String wsdlDocumentLocation, List referenceParameters);
}