javax.xml.ws.spi.Provider Maven / Gradle / Ivy
Show all versions of webservices-api Show documentation
/*
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
*
* Copyright (c) 2005-2011 Oracle and/or its affiliates. All rights reserved.
*
* The contents of this file are subject to the terms of either the GNU
* General Public License Version 2 only ("GPL") or the Common Development
* and Distribution License("CDDL") (collectively, the "License"). You
* may not use this file except in compliance with the License. You can
* obtain a copy of the License at
* https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html
* or packager/legal/LICENSE.txt. See the License for the specific
* language governing permissions and limitations under the License.
*
* When distributing the software, include this License Header Notice in each
* file and include the License file at packager/legal/LICENSE.txt.
*
* GPL Classpath Exception:
* Oracle designates this particular file as subject to the "Classpath"
* exception as provided by Oracle in the GPL Version 2 section of the License
* file that accompanied this code.
*
* Modifications:
* If applicable, add the following below the License Header, with the fields
* enclosed by brackets [] replaced by your own identifying information:
* "Portions Copyright [year] [name of copyright owner]"
*
* Contributor(s):
* If you wish your version of this file to be governed by only the CDDL or
* only the GPL Version 2, indicate your decision by adding "[Contributor]
* elects to include this software in this distribution under the [CDDL or GPL
* Version 2] license." If you don't indicate a single choice of license, a
* recipient has the option to distribute your version of this file under
* either the CDDL, the GPL Version 2 or to extend the choice of license to
* its licensees as provided above. However, if you add GPL Version 2 code
* and therefore, elected the GPL Version 2 license, then the option applies
* only if the new code is made subject to such option by the copyright
* holder.
*/
package javax.xml.ws.spi;
import java.net.URL;
import java.util.List;
import java.util.Iterator;
import java.util.Map;
import java.lang.reflect.Method;
import javax.xml.namespace.QName;
import javax.xml.ws.*;
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.
**/
// Using two strings so that package renaming doesn't change it
static final String DEFAULT_JAXWSPROVIDER
= "com.sun"+".xml.internal.ws.spi.ProviderImpl";
/**
* Take advantage of Java SE 6's java.util.ServiceLoader API.
* Using reflection so that there is no compile-time dependency on SE 6.
*/
static private final Method loadMethod;
static private final Method iteratorMethod;
static {
Method tLoadMethod = null;
Method tIteratorMethod = null;
try {
Class clazz = Class.forName("java.util.ServiceLoader");
tLoadMethod = clazz.getMethod("load", Class.class);
tIteratorMethod = clazz.getMethod("iterator");
} catch(ClassNotFoundException ce) {
// Running on Java SE 5
} catch(NoSuchMethodException ne) {
// Shouldn't happen
}
loadMethod = tLoadMethod;
iteratorMethod = tIteratorMethod;
}
/**
* 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 = getProviderUsingServiceLoader();
if (provider == null) {
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);
}
}
private static Provider getProviderUsingServiceLoader() {
if (loadMethod != null) {
Object loader;
try {
loader = loadMethod.invoke(null, Provider.class);
} catch (Exception e) {
throw new WebServiceException("Cannot invoke java.util.ServiceLoader#load()", e);
}
Iterator it;
try {
it = (Iterator)iteratorMethod.invoke(loader);
} catch(Exception e) {
throw new WebServiceException("Cannot invoke java.util.ServiceLoader#iterator()", e);
}
return it.hasNext() ? it.next() : null;
}
return null;
}
/**
* 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 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.
* @param features Web Service features that must be configured on
* the service. If the provider doesn't understand a feature,
* it must throw a WebServiceException.
* @return The newly created service delegate.
*
* @since JAX-WS 2.2
*/
public ServiceDelegate createServiceDelegate(
java.net.URL wsdlDocumentLocation,
QName serviceName, Class serviceClass, WebServiceFeature ... features) {
throw new UnsupportedOperationException("JAX-WS 2.2 implementation must override this default behaviour.");
}
/**
*
* 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.
*
* @param eprInfoset infoset for EndpointReference
*
* @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);
/**
* Factory method to create a W3CEndpointReference.
* Using this method, a W3CEndpointReference instance
* can be created with extension elements, and attributes.
* Provider implementations must override the default
* implementation.
*
*
* 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 interfaceName the wsam:InterfaceName element in the
* wsa:Metadata element.
* @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.
* @param elements extension elements to be associated
* with the returned EndpointReference instance.
* @param attributes extension attributes 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.
* - If the
wsdlDocumentLocation is NOT null but
* wsdli:wsdlLocation's namespace name cannot be got from the available
* metadata.
*
* @throws WebServiceException If an error occurs while creating the
* W3CEndpointReference.
* @since JAX-WS 2.2
*/
public W3CEndpointReference createW3CEndpointReference(String address,
QName interfaceName, QName serviceName, QName portName,
List metadata, String wsdlDocumentLocation, List referenceParameters,
List elements, Map attributes) {
throw new UnsupportedOperationException("JAX-WS 2.2 implementation must override this default behaviour.");
}
/**
* Creates and publishes an endpoint object with the specified
* address, implementation object and web service features.
* Provider implementations must override the
* default implementation.
*
* @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.
* @param features A list of WebServiceFeatures to configure on the
* endpoint. Supported features not in the features
* parameter will have their default values.
* @return The newly created endpoint.
* @since JAX-WS 2.2
*/
public Endpoint createAndPublishEndpoint(String address,
Object implementor, WebServiceFeature ... features) {
throw new UnsupportedOperationException("JAX-WS 2.2 implementation must override this default behaviour.");
}
/**
* Creates an endpoint object with the provided binding, implementation
* object and web service features. Provider implementations
* must override the default implementation.
*
* @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.
* @param features A list of WebServiceFeatures to configure on the
* endpoint. Supported features not in the features
* parameter will have their default values.
* @return The newly created endpoint.
* @since JAX-WS 2.2
*/
public Endpoint createEndpoint(String bindingId, Object implementor,
WebServiceFeature ... features) {
throw new UnsupportedOperationException("JAX-WS 2.2 implementation must override this default behaviour.");
}
/**
* Creates an endpoint object with the provided binding, implementation
* class, invoker and web service features. Containers typically use
* this to create Endpoint objects. Provider
* implementations must override the default implementation.
*
* @param bindingId A URI specifying the desired binding (e.g. SOAP/HTTP).
* Can be null.
* @param implementorClass A service implementation class that
* MUST be annotated with all the necessary Web service
* annotations.
* @param invoker that does the actual invocation on the service instance.
* @param features A list of WebServiceFeatures to configure on the
* endpoint. Supported features not in the features
* parameter will have their default values.
* @return The newly created endpoint.
* @since JAX-WS 2.2
*/
public Endpoint createEndpoint(String bindingId, Class implementorClass,
Invoker invoker, WebServiceFeature ... features) {
throw new UnsupportedOperationException("JAX-WS 2.2 implementation must override this default behaviour.");
}
}