/*

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the LICENSE file that accompanied this code.

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

 * or visit www.oracle.com if you need additional information or have any

 * questions.

 */

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 <code>ServiceDelegate</code> and

 * <code>Endpoint</code> objects.

 * <p>

 *

 * @since JAX-WS 2.0

 */

public abstract class Provider {

    /**

     * A constant representing the property used to lookup the

     * name of a <code>Provider</code> implementation

     * class.

     */

    static public final String JAXWSPROVIDER_PROPERTY

            = "javax.xml.ws.spi.Provider";

    /**

     * A constant representing the name of the default

     * <code>Provider</code> 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.

     * <p>

     * The algorithm used to locate the provider subclass to use consists

     * of the following steps:

     * <p>

     * <ul>

     * <li>

     *   If a resource with the name of

     *   <code>META-INF/services/javax.xml.ws.spi.Provider</code>

     *   exists, then its first line, if present, is used as the UTF-8 encoded

     *   name of the implementation class.

     * </li>

     * <li>

     *   If the $java.home/lib/jaxws.properties file exists and it is readable by

     *   the <code>java.util.Properties.load(InputStream)</code> method and it contains

     *   an entry whose key is <code>javax.xml.ws.spi.Provider</code>, then the value of

     *   that entry is used as the name of the implementation class.

     * </li>

     * <li>

     *   If a system property with the name <code>javax.xml.ws.spi.Provider</code>

     *   is defined, then its value is used as the name of the implementation class.

     * </li>

     * <li>

     *   Finally, a default implementation class name is used.

     * </li>

     * </ul>

     *

     */

    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<Provider> it;

            try {

                it = (Iterator<Provider>)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.

     * <p>

     * @param wsdlDocumentLocation A URL pointing to the WSDL document

     *        for the service, or <code>null</code> if there isn't one.

     * @param serviceName The qualified name of the service.

     * @param serviceClass The service class, which MUST be either

     *        <code>javax.xml.ws.Service</code> or a subclass thereof.

     * @return The newly created service delegate.

     */

    public abstract ServiceDelegate createServiceDelegate(

            java.net.URL wsdlDocumentLocation,

            QName serviceName, Class<? extends Service> serviceClass);

    /**

     * Creates a service delegate object.

     * <p>

     * @param wsdlDocumentLocation A URL pointing to the WSDL document

     *        for the service, or <code>null</code> if there isn't one.

     * @param serviceName The qualified name of the service.

     * @param serviceClass The service class, which MUST be either

     *        <code>javax.xml.ws.Service</code> 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<? extends Service> 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

     * <code>eprInfoset</code>.

     *

     * @param eprInfoset infoset for EndpointReference

     *

     * @return the <code>EndpointReference</code> unmarshalled from

     * <code>eprInfoset</code>.  This method never returns <code>null</code>.

     *

     * @throws WebServiceException If there is an error creating the

     * <code>EndpointReference</code> from the specified <code>eprInfoset</code>.

     *

     * @throws NullPointerException If the <code>null</code>

     * <code>eprInfoset</code> 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

     * <code>endpointReference</code>, then those reference

     * parameters MUST appear as SOAP headers, indicating them to be

     * reference parameters, on all messages sent to the endpoint.

     * The parameter  <code>serviceEndpointInterface</code> specifies

     * the service endpoint interface that is supported by the

     * returned proxy.

     * The parameter <code>endpointReference</code> 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

     * <code>serviceEndpointInterface</code> and the <code>EndpointReference</code>.

     * For this method

     * to successfully return a proxy, WSDL metadata MUST be available and the

     * <code>endpointReference</code> MUST contain an implementation understood

     * <code>serviceName</code> 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 <code>features

     *                </code> parameter will have their default values.

     * @return Object Proxy instance that supports the

     *                  specified service endpoint interface

     * @throws WebServiceException

     *                  <UL>

     *                  <LI>If there is an error during creation

     *                      of the proxy

     *                  <LI>If there is any missing WSDL metadata

     *                      as required by this method}

     *                  <LI>If this

     *                      <code>endpointReference</code>

     *                      is illegal

     *                  <LI>If an illegal

     *                      <code>serviceEndpointInterface</code>

     *                      is specified

     *                  <LI>If a feature is enabled that is not compatible with

     *                      this port or is unsupported.

     *                   </UL>

     *

     * @see WebServiceFeature

     *

     * @since JAX-WS 2.1

     **/

    public abstract <T> T getPort(EndpointReference endpointReference,

            Class<T> serviceEndpointInterface,

            WebServiceFeature... features);

    /**

     * Factory method to create a <code>W3CEndpointReference</code>.

     *

     * <p>

     * This method can be used to create a <code>W3CEndpointReference</code>

     * for any endpoint by specifying the <code>address</code> property along

     * with any other desired properties.  This method

     * can also be used to create a <code>W3CEndpointReference</code> for

     * an endpoint that is published by the same Java EE application.

     * To do so the <code>address</code> property can be provided or this

     * method can automatically determine the <code>address</code> of

     * an endpoint that is published by the same Java EE application and is

     * identified by the <code>serviceName</code> and

     * <code>portName</code> propeties.  If the <code>address</code> is

     * <code>null</code> and the <code>serviceName</code> and

     * <code>portName</code> do not identify an endpoint published by the

     * same Java EE application, a

     * <code>javax.lang.IllegalStateException</code> 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

     * <code>W3CEndpointReference</code> instances <code>wsa:metadata</code>

     * element.

     * @param wsdlDocumentLocation URL for the WSDL document location for

     * the service.

     * @param referenceParameters Reference parameters to be associated

     * with the returned <code>EndpointReference</code> instance.

     *

     * @return the <code>W3CEndpointReference</code> created from

     *          <code>serviceName</code>, <code>portName</code>,

     *          <code>metadata</code>, <code>wsdlDocumentLocation</code>

     *          and <code>referenceParameters</code>. This method

     *          never returns <code>null</code>.

     *

     * @throws java.lang.IllegalStateException

     *     <ul>

     *        <li>If the <code>address</code>, <code>serviceName</code> and

     *            <code>portName</code> are all <code>null</code>.

     *        <li>If the <code>serviceName</code> service is <code>null</code> and the

     *            <code>portName</code> is NOT <code>null</code>.

     *        <li>If the <code>address</code> property is <code>null</code> and

     *            the <code>serviceName</code> and <code>portName</code> do not

     *            specify a valid endpoint published by the same Java EE

     *            application.

     *        <li>If the <code>serviceName</code>is NOT <code>null</code>

     *             and is not present in the specified WSDL.

     *        <li>If the <code>portName</code> port is not <code>null</code> and it

     *             is not present in <code>serviceName</code> service in the WSDL.

     *        <li>If the <code>wsdlDocumentLocation</code> is NOT <code>null</code>

     *            and does not represent a valid WSDL.

     *     </ul>

     * @throws WebServiceException If an error occurs while creating the

     *                             <code>W3CEndpointReference</code>.

     *

     * @since JAX-WS 2.1

     */

    public abstract W3CEndpointReference createW3CEndpointReference(String address, QName serviceName, QName portName,

            List<Element> metadata, String wsdlDocumentLocation, List<Element> referenceParameters);

    /**

     * Factory method to create a <code>W3CEndpointReference</code>.

     * Using this method, a <code>W3CEndpointReference</code> instance

     * can be created with extension elements, and attributes.

     * <code>Provider</code> implementations must override the default

     * implementation.

     *

     * <p>

     * This method can be used to create a <code>W3CEndpointReference</code>

     * for any endpoint by specifying the <code>address</code> property along

     * with any other desired properties.  This method

     * can also be used to create a <code>W3CEndpointReference</code> for

     * an endpoint that is published by the same Java EE application.

     * To do so the <code>address</code> property can be provided or this

     * method can automatically determine the <code>address</code> of

     * an endpoint that is published by the same Java EE application and is

     * identified by the <code>serviceName</code> and

     * <code>portName</code> propeties.  If the <code>address</code> is

     * <code>null</code> and the <code>serviceName</code> and

     * <code>portName</code> do not identify an endpoint published by the

     * same Java EE application, a

     * <code>javax.lang.IllegalStateException</code> MUST be thrown.

     *

     * @param address Specifies the address of the target endpoint

     * @param interfaceName the <code>wsam:InterfaceName</code> element in the

     * <code>wsa:Metadata</code> 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

     * <code>W3CEndpointReference</code> instances <code>wsa:metadata</code>

     * element.

     * @param wsdlDocumentLocation URL for the WSDL document location for

     * the service.

     * @param referenceParameters Reference parameters to be associated

     * with the returned <code>EndpointReference</code> instance.

     * @param elements extension elements to be associated

     * with the returned <code>EndpointReference</code> instance.

     * @param attributes extension attributes to be associated

     * with the returned <code>EndpointReference</code> instance.

     *

     * @return the <code>W3CEndpointReference</code> created from

     *          <code>serviceName</code>, <code>portName</code>,

     *          <code>metadata</code>, <code>wsdlDocumentLocation</code>

     *          and <code>referenceParameters</code>. This method

     *          never returns <code>null</code>.

     *

     * @throws java.lang.IllegalStateException

     *     <ul>

     *        <li>If the <code>address</code>, <code>serviceName</code> and

     *            <code>portName</code> are all <code>null</code>.

     *        <li>If the <code>serviceName</code> service is <code>null</code> and the

     *            <code>portName</code> is NOT <code>null</code>.

     *        <li>If the <code>address</code> property is <code>null</code> and

     *            the <code>serviceName</code> and <code>portName</code> do not

     *            specify a valid endpoint published by the same Java EE

     *            application.

     *        <li>If the <code>serviceName</code>is NOT <code>null</code>

     *             and is not present in the specified WSDL.

     *        <li>If the <code>portName</code> port is not <code>null</code> and it

     *             is not present in <code>serviceName</code> service in the WSDL.

     *        <li>If the <code>wsdlDocumentLocation</code> is NOT <code>null</code>

     *            and does not represent a valid WSDL.

     *        <li>If the <code>wsdlDocumentLocation</code> is NOT <code>null</code> but

     *            wsdli:wsdlLocation's namespace name cannot be got from the available

     *            metadata.

     *     </ul>

     * @throws WebServiceException If an error occurs while creating the

     *                             <code>W3CEndpointReference</code>.

     * @since JAX-WS 2.2

     */

    public W3CEndpointReference createW3CEndpointReference(String address,

            QName interfaceName, QName serviceName, QName portName,

            List<Element> metadata, String wsdlDocumentLocation, List<Element> referenceParameters,

            List<Element> elements, Map<QName, String> 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.

     * <code>Provider</code> 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 <code>features

     *        </code> 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. <code>Provider</code> 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 <code>features

     *        </code> 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. <code>Provider</code>

     * 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 <code>features

     *        </code> 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.");

    }

}