jakarta.xml.ws.spi.ServiceDelegate Maven / Gradle / Ivy
/*
* Copyright (c) 2005, 2020 Oracle and/or its affiliates. All rights reserved.
*
* This program and the accompanying materials are made available under the
* terms of the Eclipse Distribution License v. 1.0, which is available at
* http://www.eclipse.org/org/documents/edl-v10.php.
*
* SPDX-License-Identifier: BSD-3-Clause
*/
package jakarta.xml.ws.spi;
import java.util.Iterator;
import javax.xml.namespace.QName;
import jakarta.xml.ws.Dispatch;
import jakarta.xml.ws.Service;
import jakarta.xml.ws.handler.HandlerResolver;
import jakarta.xml.ws.WebServiceFeature;
import jakarta.xml.bind.JAXBContext;
import jakarta.xml.ws.EndpointReference;
import jakarta.xml.ws.WebServiceException;
/**
* Service delegates are used internally by {@code Service} objects
* to allow pluggability of Jakarta XML Web Services implementations.
*
* Every {@code Service} object has its own delegate, created using
* the {@link jakarta.xml.ws.spi.Provider#createServiceDelegate} method. A {@code Service}
* object delegates all of its instance methods to its delegate.
*
* @see jakarta.xml.ws.Service
* @see jakarta.xml.ws.spi.Provider
*
* @since 1.6, JAX-WS 2.0
*/
public abstract class ServiceDelegate {
/**
* Default constructor.
*/
protected ServiceDelegate() {
}
/**
* The {@code getPort} method returns a proxy. A service client
* uses this proxy to invoke operations on the target
* service endpoint. The {@code serviceEndpointInterface}
* specifies the service endpoint interface that is supported by
* the created dynamic proxy instance.
*
* @param Service endpoint interface
* @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
* {@code serviceEndpointInterface}
* or {@code portName} is specified
*
* @see java.lang.reflect.Proxy
* @see java.lang.reflect.InvocationHandler
**/
public abstract T getPort(QName portName,
Class serviceEndpointInterface);
/**
* The {@code getPort} method returns a proxy. A service client
* uses this proxy to invoke operations on the target
* service endpoint. The {@code serviceEndpointInterface}
* specifies the service endpoint interface that is supported by
* the created dynamic proxy instance.
*
* @param Service endpoint interface
* @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 {@code 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
* {@code serviceEndpointInterface}
* or {@code 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 1.6, JAX-WS 2.1
**/
public abstract T getPort(QName portName,
Class serviceEndpointInterface, WebServiceFeature... features);
/**
* The {@code getPort} method returns a proxy.
* The parameter {@code endpointReference} specifies the
* endpoint that will be invoked by the returned proxy. If there
* are any reference parameters in the
* {@code endpointReference}, then those reference
* parameters MUST appear as SOAP headers, indicating them to be
* reference parameters, on all messages sent to the endpoint.
* The {@code endpointReference's} address MUST be used
* for invocations on the endpoint.
* The parameter {@code serviceEndpointInterface} specifies
* the service endpoint interface that is supported by the
* returned proxy.
* In the implementation of this method, the Jakarta XML Web Services
* runtime system takes the responsibility of selecting a protocol
* binding (and a port) and configuring the proxy accordingly from
* the WSDL associated with this {@code Service} instance or
* from the metadata from the {@code endpointReference}.
* If this {@code Service} instance has a WSDL and
* the {@code endpointReference} metadata
* also has a WSDL, then the WSDL from this instance MUST be used.
* If this {@code Service} instance does not have a WSDL and
* the {@code endpointReference} does have a WSDL, then the
* WSDL from the {@code endpointReference} MAY be used.
* The returned proxy should not be reconfigured by the client.
* If this {@code 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
*
* {@code port = service.getPort(portName, serviceEndpointInterface);}
*
* where the {@code portName} is retrieved from the
* metadata of the {@code endpointReference} or from the
* {@code serviceEndpointInterface} and the WSDL
* associated with this {@code Service} instance.
*
* @param Service endpoint interface.
* @param endpointReference The {@code EndpointReference}
* for the target service endpoint that will be invoked by the
* returned proxy.
* @param serviceEndpointInterface Service endpoint interface.
* @param features A list of {@code WebServiceFeatures} to configure on the
* proxy. Supported features not in the {@code 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 {@code endpointReference} metadata does
* not match the {@code serviceName} of this
* {@code Service} instance.
*
- If a {@code portName} cannot be extracted
* from the WSDL or {@code endpointReference} metadata.
*
- If an invalid
* {@code endpointReference}
* is specified.
*
- If an invalid
* {@code serviceEndpointInterface}
* is specified.
*
- If a feature is enabled that is not compatible
* with this port or is unsupported.
*
*
* @since 1.6, JAX-WS 2.1
**/
public abstract T getPort(EndpointReference endpointReference,
Class serviceEndpointInterface, WebServiceFeature... features);
/**
* The {@code getPort} method returns a proxy. The parameter
* {@code serviceEndpointInterface} specifies the service
* endpoint interface that is supported by the returned proxy.
* In the implementation of this method, the Jakarta XML Web Services
* 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 Service endpoint interface
* @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
* {@code serviceEndpointInterface}
* is specified
*
**/
public abstract T getPort(Class serviceEndpointInterface);
/**
* The {@code getPort} method returns a proxy. The parameter
* {@code serviceEndpointInterface} specifies the service
* endpoint interface that is supported by the returned proxy.
* In the implementation of this method, the Jakarta XML Web Services
* 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 Service endpoint interface
* @param serviceEndpointInterface Service endpoint interface
* @param features An array of {@code WebServiceFeatures} to configure on the
* proxy. Supported features not in the {@code 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
* {@code serviceEndpointInterface}
* is specified
*
- If a feature is enabled that is not compatible
* with this port or is unsupported.
*
*
* @see WebServiceFeature
*
* @since 1.6, 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
* {@code Dispatch}instances.
*
* @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 jakarta.xml.ws.soap.SOAPBinding#SOAP11HTTP_BINDING
* @see jakarta.xml.ws.soap.SOAPBinding#SOAP12HTTP_BINDING
* @see jakarta.xml.ws.http.HTTPBinding#HTTP_BINDING
**/
public abstract void addPort(QName portName, String bindingId,
String endpointAddress);
/**
* Creates a {@code Dispatch} instance for use with objects of
* the user's choosing.
*
* @param type used for messages or message payloads. Implementations are required to
* support {@code javax.xml.transform.Source} and {@code jakarta.xml.soap.SOAPMessage}.
* @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
* {@code javax.xml.transform.Source} and {@code jakarta.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 {@code MESSAGE}
* when type is {@code SOAPMessage}.
*
* @return Dispatch instance
* @throws WebServiceException If any error in the creation of
* the {@code Dispatch} object
* @see javax.xml.transform.Source
* @see jakarta.xml.soap.SOAPMessage
**/
public abstract Dispatch createDispatch(QName portName, Class type,
Service.Mode mode);
/**
* Creates a {@code Dispatch} instance for use with objects of
* the user's choosing.
*
* @param type used for messages or message payloads. Implementations are required to
* support {@code javax.xml.transform.Source} and {@code jakarta.xml.soap.SOAPMessage}.
* @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
* {@code javax.xml.transform.Source} and {@code jakarta.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 {@code MESSAGE}
* when type is {@code SOAPMessage}.
* @param features A list of {@code WebServiceFeatures} to configure on the
* proxy. Supported features not in the {@code features
* } parameter will have their default values.
*
* @return Dispatch instance
* @throws WebServiceException If any error in the creation of
* the {@code Dispatch} object or if a
* feature is enabled that is not compatible with
* this port or is unsupported.
*
* @see javax.xml.transform.Source
* @see jakarta.xml.soap.SOAPMessage
* @see WebServiceFeature
*
* @since 1.6, JAX-WS 2.1
**/
public abstract Dispatch createDispatch(QName portName, Class type,
Service.Mode mode, WebServiceFeature... features);
/**
* Creates a {@code Dispatch} instance for use with objects of
* the user's choosing. If there
* are any reference parameters in the
* {@code endpointReference}, then those reference
* parameters MUST appear as SOAP headers, indicating them to be
* reference parameters, on all messages sent to the endpoint.
* The {@code endpointReference's} address MUST be used
* for invocations on the endpoint.
* In the implementation of this method, the Jakarta XML Web Services
* runtime system takes the responsibility of selecting a protocol
* binding (and a port) and configuring the dispatch accordingly from
* the WSDL associated with this {@code Service} instance or
* from the metadata from the {@code endpointReference}.
* If this {@code Service} instance has a WSDL and
* the {@code endpointReference}
* also has a WSDL in its metadata, then the WSDL from this instance MUST be used.
* If this {@code Service} instance does not have a WSDL and
* the {@code endpointReference} does have a WSDL, then the
* WSDL from the {@code endpointReference} MAY be used.
* An implementation MUST be able to retrieve the {@code portName} from the
* {@code endpointReference} metadata.
*
* This method behaves the same as calling
*
* {@code dispatch = service.createDispatch(portName, type, mode, features);}
*
* where the {@code portName} is retrieved from the
* WSDL or {@code EndpointReference} metadata.
*
* @param type of object used to messages or message
* payloads. Implementations are required to support
* {@code javax.xml.transform.Source} and {@code jakarta.xml.soap.SOAPMessage}.
* @param endpointReference The {@code EndpointReference}
* for the target service endpoint that will be invoked by the
* returned {@code Dispatch} object.
* @param type The class of object used to messages or message
* payloads. Implementations are required to support
* {@code javax.xml.transform.Source} and {@code jakarta.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 {@code MESSAGE}
* when type is {@code SOAPMessage}.
* @param features An array of {@code WebServiceFeatures} to configure on the
* proxy. Supported features not in the {@code 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 {@code endpointReference} metadata does
* not match the {@code serviceName} or {@code portName}
* of a WSDL associated
* with this {@code Service} instance.
*
- If the {@code portName} cannot be determined
* from the {@code EndpointReference} metadata.
*
- If any error in the creation of
* the {@code Dispatch} object.
*
- If a feature is enabled that is not
* compatible with this port or is unsupported.
*
*
* @see javax.xml.transform.Source
* @see jakarta.xml.soap.SOAPMessage
* @see WebServiceFeature
*
* @since 1.6, JAX-WS 2.1
**/
public abstract Dispatch createDispatch(EndpointReference endpointReference,
Class type, Service.Mode mode,
WebServiceFeature... features);
/**
* Creates a {@code Dispatch} instance for use with Jakarta XML Binding
* generated objects.
*
* @param portName Qualified name for the target service endpoint
* @param context The JAXBContext 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 {@code Dispatch} object
*
* @see jakarta.xml.bind.JAXBContext
**/
public abstract Dispatch