All Downloads are FREE. Search and download functionalities are using the official Maven repository.

javax.xml.ws.spi.Provider Maven / Gradle / Ivy

There is a newer version: 2.3.1
Show newest version
/*
 * 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."); } }




© 2015 - 2024 Weber Informatics LLC | Privacy Policy