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

javax.xml.ws.spi.ServiceDelegate 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-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); }