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

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

Go to download

Java(TM) EE 7 Endorsed APIs

The newest version!
/*
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
 *
 * Copyright (c) 2005-2010 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.util.Iterator;
import javax.xml.namespace.QName;
import javax.xml.ws.Dispatch;
import javax.xml.ws.Service;
import javax.xml.ws.handler.HandlerResolver;
import javax.xml.ws.WebServiceFeature;
import javax.xml.bind.JAXBContext;
import javax.xml.ws.EndpointReference;
import javax.xml.ws.WebServiceException;


/**
 * Service delegates are used internally by Service objects
 * to allow pluggability of JAX-WS implementations.
 * 

 * Every Service object has its own delegate, created using
 * the {@link javax.xml.ws.spi.Provider#createServiceDelegate} method. A Service
 * object delegates all of its instance methods to its delegate.
 *
 * @see javax.xml.ws.Service
 * @see javax.xml.ws.spi.Provider
 *
 * @since JAX-WS 2.0
 */
public abstract class ServiceDelegate {
    
    protected ServiceDelegate() {
    }
    
    /** 
     * The getPort method returns a proxy. A service client
     * uses this proxy to invoke operations on the target
     * service endpoint. The serviceEndpointInterface
     * specifies the service endpoint interface that is supported by
     * the created dynamic proxy instance.
     *
     * @param portName  Qualified name of the service endpoint in
     *                  the WSDL service description
     * @param serviceEndpointInterface Service endpoint interface
     *                  supported by the dynamic proxy
     * @return Object Proxy instance that
     *                supports the specified service endpoint
     *                interface
     * @throws WebServiceException This exception is thrown in the
     *                  following cases:
     *                  
    
     *                  
  • If there is an error in creation of
     *                      the proxy
     *                  
  • If there is any missing WSDL metadata
     *                      as required by this method
     *                  
  • If an illegal
     *                      serviceEndpointInterface
     *                      or portName is specified
     *                  

     * @see java.lang.reflect.Proxy
     * @see java.lang.reflect.InvocationHandler
     **/
    public abstract  T getPort(QName portName,
            Class serviceEndpointInterface);
    
    /** 
     * The getPort method returns a proxy. A service client
     * uses this proxy to invoke operations on the target
     * service endpoint. The serviceEndpointInterface
     * specifies the service endpoint interface that is supported by
     * the created dynamic proxy instance.
     *
     * @param portName  Qualified name of the service endpoint in
     *                  the WSDL service description
     * @param serviceEndpointInterface Service endpoint interface
     *                  supported by the dynamic proxy or instance
     * @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 This exception is thrown in the
     *                  following cases:
     *                  
    
     *                  
  • If there is an error in creation of
     *                      the proxy
     *                  
  • If there is any missing WSDL metadata
     *                      as required by this method
     *                  
  • If an illegal
     *                      serviceEndpointInterface
     *                      or portName is specified
     *                  
  • If a feature is enabled that is not compatible
     *                      with this port or is unsupported.
     *                  

     * @see java.lang.reflect.Proxy
     * @see java.lang.reflect.InvocationHandler
     * @see WebServiceFeature
     * 
     * @since JAX-WS 2.1
     **/
    public abstract  T getPort(QName portName,
            Class serviceEndpointInterface, WebServiceFeature... features);    
    
    /** 
     * The getPort method returns a proxy.
     * The parameter endpointReference specifies the
     * endpoint that will be invoked by the returned 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 endpointReference's address MUST be used
     * for invocations on the endpoint.
     * The parameter serviceEndpointInterface specifies
     * the service endpoint interface that is supported 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 associated with this Service instance or
     * from the metadata from the endpointReference.
     * If this Service instance has a WSDL and 
     * the endpointReference metadata 
     * also has a WSDL, then the WSDL from this instance MUST be used.
     * If this Service instance does not have a WSDL and
     * the endpointReference does have a WSDL, then the 
     * WSDL from the endpointReference MAY be used.
     * The returned proxy should not be reconfigured by the client.
     * If this Service instance has a known proxy 
     * port that matches the information contained in 
     * the WSDL,
     * then that proxy is returned, otherwise a WebServiceException
     * is thrown.
     * 

     * Calling this method has the same behavior as the following
     * 
     * port = service.getPort(portName, serviceEndpointInterface);
     * 

     * where the portName is retrieved from the  
     * metadata of the endpointReference or from the 
     * serviceEndpointInterface and the WSDL
     * associated with this Service instance.
     *
     * @param endpointReference  The EndpointReference
     * for the target service endpoint 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 the endpointReference metadata does
     *                      not match the serviceName of this
     *                      Service instance.
     *                  
  • If a portName cannot be extracted
     *                      from the WSDL or endpointReference metadata.
     *                  
  • If an invalid
     *                      endpointReference
     *                      is specified.
     *                  
  • If an invalid
     *                      serviceEndpointInterface
     *                      is specified.
     *                  
  • If a feature is enabled that is not compatible
     *                      with this port or is unsupported.
     *                  

     *
     * @since JAX-WS 2.1
     **/
    public abstract  T getPort(EndpointReference endpointReference,
           Class serviceEndpointInterface, WebServiceFeature... features);

    
    /** 
     * The getPort method returns a proxy. The parameter
     * serviceEndpointInterface specifies the service
     * endpoint interface that is supported 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.
     * The returned proxy should not be reconfigured by the client.
     *
     * @param serviceEndpointInterface Service endpoint interface
     * @return Object 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 an illegal
     *                      serviceEndpointInterface
     *                      is specified
     *                  

     **/
    public abstract  T getPort(Class serviceEndpointInterface);

    
    /**
     * The getPort method returns a proxy. The parameter
     * serviceEndpointInterface specifies the service
     * endpoint interface that is supported 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.
     * The returned proxy should not be reconfigured by the client.
     *
     * @param serviceEndpointInterface Service endpoint interface
     * @param features  An array of WebServiceFeatures to configure on the 
     *                proxy.  Supported features not in the features
     *                 parameter will have their default values.
     * @return Object 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 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(Class serviceEndpointInterface, 
            WebServiceFeature... features);
    
    
    /** 
     * Creates a new port for the service. Ports created in this way contain
     * no WSDL port type information and can only be used for creating
     * Dispatchinstances.
     *
     * @param portName  Qualified name for the target service endpoint
     * @param bindingId A URI identifier of a binding.
     * @param endpointAddress Address of the target service endpoint as a URI
     * @throws WebServiceException If any error in the creation of
     * the port
     *
     * @see javax.xml.ws.soap.SOAPBinding#SOAP11HTTP_BINDING
     * @see javax.xml.ws.soap.SOAPBinding#SOAP12HTTP_BINDING
     * @see javax.xml.ws.http.HTTPBinding#HTTP_BINDING
     **/
    public abstract void addPort(QName portName, String bindingId,
            String endpointAddress);
    
   
    
    /** 
     * Creates a Dispatch instance for use with objects of
     * the user's choosing.
     *
     * @param portName  Qualified name for the target service endpoint
     * @param type The class of object used for messages or message
     * payloads. Implementations are required to support
     * javax.xml.transform.Source and javax.xml.soap.SOAPMessage.
     * @param mode Controls whether the created dispatch instance is message
     * or payload oriented, i.e. whether the user will work with complete
     * protocol messages or message payloads. E.g. when using the SOAP
     * protocol, this parameter controls whether the user will work with
     * SOAP messages or the contents of a SOAP body. Mode MUST be MESSAGE
     * when type is SOAPMessage.
     *
     * @return Dispatch instance
     * @throws WebServiceException If any error in the creation of
     *                  the Dispatch object
     * @see javax.xml.transform.Source
     * @see javax.xml.soap.SOAPMessage
     **/
    public abstract  Dispatch createDispatch(QName portName, Class type, 
            Service.Mode mode);
    
    /** 
     * Creates a Dispatch instance for use with objects of
     * the user's choosing.
     *
     * @param portName  Qualified name for the target service endpoint
     * @param type The class of object used for messages or message
     * payloads. Implementations are required to support
     * javax.xml.transform.Source and javax.xml.soap.SOAPMessage.
     * @param mode Controls whether the created dispatch instance is message
     * or payload oriented, i.e. whether the user will work with complete
     * protocol messages or message payloads. E.g. when using the SOAP
     * protocol, this parameter controls whether the user will work with
     * SOAP messages or the contents of a SOAP body. Mode MUST be MESSAGE
     * when type is SOAPMessage.
     * @param features  A list of WebServiceFeatures to configure on the 
     *                proxy.  Supported features not in the features
     *                 parameter will have their default values.
     *
     * @return Dispatch instance
     * @throws WebServiceException If any error in the creation of
     *                  the Dispatch object or if a 
     *                  feature is enabled that is not compatible with 
     *                  this port or is unsupported.
     *
     * @see javax.xml.transform.Source
     * @see javax.xml.soap.SOAPMessage
     * @see WebServiceFeature
     *
     * @since JAX-WS 2.1
     **/
    public abstract  Dispatch createDispatch(QName portName, Class type, 
            Service.Mode mode, WebServiceFeature... features);
    
    /** 
     * Creates a Dispatch instance for use with objects of
     * the user's choosing. 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 endpointReference's address MUST be used
     * for invocations on the endpoint.
     * 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 dispatch accordingly from
     * the WSDL associated with this Service instance or
     * from the metadata from the endpointReference.
     * If this Service instance has a WSDL and 
     * the endpointReference
     * also has a WSDL in its metadata, then the WSDL from this instance MUST be used.
     * If this Service instance does not have a WSDL and
     * the endpointReference does have a WSDL, then the 
     * WSDL from the endpointReference MAY be used. 
     * An implementation MUST be able to retrieve the portName from the
     * endpointReference metadata.  
     * 

     * This method behaves the same as calling
     * 
     * dispatch = service.createDispatch(portName, type, mode, features);
     * 

     * where the portName is retrieved from the 
     * WSDL or EndpointReference metadata.
     *
     * @param endpointReference  The EndpointReference
     * for the target service endpoint that will be invoked by the
     * returned Dispatch object.
     * @param type The class of object used to messages or message
     * payloads. Implementations are required to support
     * javax.xml.transform.Source and javax.xml.soap.SOAPMessage.
     * @param mode Controls whether the created dispatch instance is message
     * or payload oriented, i.e. whether the user will work with complete
     * protocol messages or message payloads. E.g. when using the SOAP
     * protocol, this parameter controls whether the user will work with
     * SOAP messages or the contents of a SOAP body. Mode MUST be MESSAGE
     * when type is SOAPMessage.
     * @param features  An array of WebServiceFeatures to configure on the 
     *                proxy.  Supported features not in the features
     *                 parameter will have their default values.
     *
     * @return Dispatch instance
     * @throws WebServiceException 
     *                  
    
     *                    
  • If there is any missing WSDL metadata
     *                      as required by this method.
     *                    
  • If the endpointReference metadata does
     *                      not match the serviceName or portName
     *                      of a WSDL associated
     *                      with this Service instance.
     *                    
  • If the portName cannot be determined
     *                    from the EndpointReference metadata.
     *                    
  • If any error in the creation of
     *                     the Dispatch object.
     *                    
  • If a feature is enabled that is not 
     *                    compatible with this port or is unsupported.
     *                  

     *
     * @see javax.xml.transform.Source
     * @see javax.xml.soap.SOAPMessage
     * @see WebServiceFeature
     *
     * @since JAX-WS 2.1
     **/
    public abstract  Dispatch createDispatch(EndpointReference endpointReference,
            Class type, Service.Mode mode, 
            WebServiceFeature... features);


    
    /** 
     * Creates a Dispatch instance for use with JAXB
     * generated objects.
     *
     * @param portName  Qualified name for the target service endpoint
     * @param context The JAXB context used to marshall and unmarshall
     * messages or message payloads.
     * @param mode Controls whether the created dispatch instance is message
     * or payload oriented, i.e. whether the user will work with complete
     * protocol messages or message payloads. E.g. when using the SOAP
     * protocol, this parameter controls whether the user will work with
     * SOAP messages or the contents of a SOAP body.
     *
     * @return Dispatch instance
     * @throws WebServiceException If any error in the creation of
     *                  the Dispatch object
     *
     * @see javax.xml.bind.JAXBContext
     **/
    public abstract Dispatch createDispatch(QName portName,
            JAXBContext context, Service.Mode mode);
    

    /** 
     * Creates a Dispatch instance for use with JAXB
     * generated objects.
     *
     * @param portName  Qualified name for the target service endpoint
     * @param context The JAXB context used to marshall and unmarshall
     * messages or message payloads.
     * @param mode Controls whether the created dispatch instance is message
     * or payload oriented, i.e. whether the user will work with complete
     * protocol messages or message payloads. E.g. when using the SOAP
     * protocol, this parameter controls whether the user will work with
     * SOAP messages or the contents of a SOAP body.
     * @param features  A list of WebServiceFeatures to configure on the 
     *                proxy.  Supported features not in the features
     *                 parameter will have their default values.
     *
     * @return Dispatch instance
     * @throws WebServiceException If any error in the creation of
     *                  the Dispatch object or if a 
     *                  feature is enabled that is not compatible with 
     *                  this port or is unsupported.
     *
     * @see javax.xml.bind.JAXBContext
     * @see WebServiceFeature
     *
     * @since JAX-WS 2.1
     **/
    public abstract Dispatch createDispatch(QName portName,
            JAXBContext context, Service.Mode mode, WebServiceFeature... features);
   
    /** 
     * Creates a Dispatch instance for use with JAXB
     * generated objects. 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 endpointReference's address MUST be used
     * for invocations on the endpoint.
     * 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 dispatch accordingly from
     * the WSDL associated with this Service instance or
     * from the metadata from the endpointReference.
     * If this Service instance has a WSDL and 
     * the endpointReference
     * also has a WSDL in its metadata, then the WSDL from this instance
     * MUST be used.
     * If this Service instance does not have a WSDL and
     * the endpointReference does have a WSDL, then the 
     * WSDL from the endpointReference MAY be used.      
     * An implementation MUST be able to retrieve the portName from the
     * endpointReference metadata.  
     * 

     * This method behavies the same as calling
     * 
     * dispatch = service.createDispatch(portName, context, mode, features);
     * 

     * where the portName is retrieved from the 
     * WSDL or endpointReference metadata.
     *
     * @param endpointReference  The EndpointReference
     * for the target service endpoint that will be invoked by the
     * returned Dispatch object.
     * @param context The JAXB context used to marshall and unmarshall
     * messages or message payloads.
     * @param mode Controls whether the created dispatch instance is message
     * or payload oriented, i.e. whether the user will work with complete
     * protocol messages or message payloads. E.g. when using the SOAP
     * protocol, this parameter controls whether the user will work with
     * SOAP messages or the contents of a SOAP body.
     * @param features  An array of WebServiceFeatures to configure on the 
     *                proxy.  Supported features not in the features
     *                 parameter will have their default values.
     *
     * @return Dispatch instance
     * @throws WebServiceException 
     *                  
    
     *                    
  • If there is any missing WSDL metadata
     *                      as required by this method.
     *                    
  • If the endpointReference metadata does
     *                    not match the serviceName or portName
     *                    of a WSDL associated
     *                    with this Service instance.
     *                    
  • If the portName cannot be determined
     *                    from the EndpointReference metadata.
     *                    
  • If any error in the creation of
     *                    the Dispatch object.
     *                    
  • if a feature is enabled that is not 
     *                    compatible with this port or is unsupported.
     *                  

     *
     * @see javax.xml.bind.JAXBContext
     * @see WebServiceFeature
     *
     * @since JAX-WS 2.1
    **/
    public abstract Dispatch createDispatch(EndpointReference endpointReference,
            JAXBContext context, Service.Mode mode,
            WebServiceFeature... features);
        
    
    /** 
     * Gets the name of this service.
     * @return Qualified name of this service
     **/
    public abstract QName getServiceName();
    
    /** 
     * Returns an Iterator for the list of
     * QNames of service endpoints grouped by this
     * service
     *
     * @return Returns java.util.Iterator with elements
     *         of type javax.xml.namespace.QName
     * @throws WebServiceException If this Service class does not
     *         have access to the required WSDL metadata
     **/
    public abstract Iterator getPorts();
    
    /** 
     * Gets the location of the WSDL document for this Service.
     *
     * @return URL for the location of the WSDL document for
     *         this service
     **/
    public abstract java.net.URL getWSDLDocumentLocation();
    
    /**
     * Returns the configured handler resolver.
     *
     * @return HandlerResolver The HandlerResolver being
     *         used by this Service instance, or null
     *         if there isn't one.
     **/
    public abstract HandlerResolver getHandlerResolver();
    
    /**
     * Sets the HandlerResolver for this Service
     * instance.
     * 

     * The handler resolver, if present, will be called once for each
     * proxy or dispatch instance that is created, and the handler chain
     * returned by the resolver will be set on the instance.
     *
     * @param handlerResolver The HandlerResolver to use
     *        for all subsequently created proxy/dispatch objects.
     *
     * @see javax.xml.ws.handler.HandlerResolver
     **/
    public abstract void setHandlerResolver(HandlerResolver handlerResolver);
    
    /**
     * Returns the executor for this Serviceinstance.
     *
     * The executor is used for all asynchronous invocations that
     * require callbacks.
     *
     * @return The java.util.concurrent.Executor to be
     *         used to invoke a callback.
     *
     * @see java.util.concurrent.Executor
     **/
    public abstract java.util.concurrent.Executor getExecutor();
    
    /**
     * Sets the executor for this Service instance.
     *
     * The executor is used for all asynchronous invocations that
     * require callbacks.
     *
     * @param executor The java.util.concurrent.Executor
     *        to be used to invoke a callback.
     *
     * @throws SecurityException If the instance does not support
     *         setting an executor for security reasons (e.g. the
     *         necessary permissions are missing).
     *
     * @see java.util.concurrent.Executor
     **/
    public abstract void setExecutor(java.util.concurrent.Executor executor);
    
}
    

    

    

            

    

            



    
    






    
© 2015 - 2024 Weber Informatics LLC | Privacy Policy