Service
objects
to allow pluggability of Jakarta XML Web Services implementations.
Every Service
object has its own delegate, created using
the Provider.createServiceDelegate(java.net.URL, javax.xml.namespace.QName, java.lang.Class<? extends jakarta.xml.ws.Service>)
method. A Service
object delegates all of its instance methods to its delegate.
- See Also:
-
Constructor Summary
-
Method Summary
Modifier and TypeMethodDescriptionabstract void
Creates a new port for the service.createDispatch
(EndpointReference endpointReference, jakarta.xml.bind.JAXBContext context, Service.Mode mode, WebServiceFeature... features) Creates aDispatch
instance for use with Jakarta XML Binding generated objects.abstract <T> Dispatch
<T> createDispatch
(EndpointReference endpointReference, Class<T> type, Service.Mode mode, WebServiceFeature... features) Creates aDispatch
instance for use with objects of the user's choosing.createDispatch
(QName portName, jakarta.xml.bind.JAXBContext context, Service.Mode mode) Creates aDispatch
instance for use with Jakarta XML Binding generated objects.createDispatch
(QName portName, jakarta.xml.bind.JAXBContext context, Service.Mode mode, WebServiceFeature... features) Creates aDispatch
instance for use with Jakarta XML Binding generated objects.abstract <T> Dispatch
<T> createDispatch
(QName portName, Class<T> type, Service.Mode mode) Creates aDispatch
instance for use with objects of the user's choosing.abstract <T> Dispatch
<T> createDispatch
(QName portName, Class<T> type, Service.Mode mode, WebServiceFeature... features) Creates aDispatch
instance for use with objects of the user's choosing.abstract Executor
Returns the executor for thisService
instance.abstract HandlerResolver
Returns the configured handler resolver.abstract <T> T
getPort
(EndpointReference endpointReference, Class<T> serviceEndpointInterface, WebServiceFeature... features) ThegetPort
method returns a proxy.abstract <T> T
ThegetPort
method returns a proxy.abstract <T> T
getPort
(Class<T> serviceEndpointInterface, WebServiceFeature... features) ThegetPort
method returns a proxy.abstract <T> T
ThegetPort
method returns a proxy.abstract <T> T
getPort
(QName portName, Class<T> serviceEndpointInterface, WebServiceFeature... features) ThegetPort
method returns a proxy.getPorts()
Returns anIterator
for the list ofQName
s of service endpoints grouped by this serviceabstract QName
Gets the name of this service.abstract URL
Gets the location of the WSDL document for this Service.abstract void
setExecutor
(Executor executor) Sets the executor for thisService
instance.abstract void
setHandlerResolver
(HandlerResolver handlerResolver) Sets theHandlerResolver
for thisService
instance.
-
Constructor Details
-
ServiceDelegate
protected ServiceDelegate()Default constructor.
-
-
Method Details
-
getPort
ThegetPort
method returns a proxy. A service client uses this proxy to invoke operations on the target service endpoint. TheserviceEndpointInterface
specifies the service endpoint interface that is supported by the created dynamic proxy instance.- Type Parameters:
T
- Service endpoint interface- Parameters:
portName
- Qualified name of the service endpoint in the WSDL service descriptionserviceEndpointInterface
- Service endpoint interface supported by the dynamic proxy- Returns:
- 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
orportName
is specified
- See Also:
-
getPort
public abstract <T> T getPort(QName portName, Class<T> serviceEndpointInterface, WebServiceFeature... features) ThegetPort
method returns a proxy. A service client uses this proxy to invoke operations on the target service endpoint. TheserviceEndpointInterface
specifies the service endpoint interface that is supported by the created dynamic proxy instance.- Type Parameters:
T
- Service endpoint interface- Parameters:
portName
- Qualified name of the service endpoint in the WSDL service descriptionserviceEndpointInterface
- Service endpoint interface supported by the dynamic proxy or instancefeatures
- A list of WebServiceFeatures to configure on the proxy. Supported features not in thefeatures
parameter will have their default values.- Returns:
- 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
orportName
is specified - If a feature is enabled that is not compatible with this port or is unsupported.
- See Also:
-
getPort
public abstract <T> T getPort(EndpointReference endpointReference, Class<T> serviceEndpointInterface, WebServiceFeature... features) ThegetPort
method returns a proxy. The parameterendpointReference
specifies the endpoint that will be invoked by the returned proxy. If there are any reference parameters in theendpointReference
, then those reference parameters MUST appear as SOAP headers, indicating them to be reference parameters, on all messages sent to the endpoint. TheendpointReference's
address MUST be used for invocations on the endpoint. The parameterserviceEndpointInterface
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 thisService
instance or from the metadata from theendpointReference
. If thisService
instance has a WSDL and theendpointReference
metadata also has a WSDL, then the WSDL from this instance MUST be used. If thisService
instance does not have a WSDL and theendpointReference
does have a WSDL, then the WSDL from theendpointReference
MAY be used. The returned proxy should not be reconfigured by the client. If thisService
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);
portName
is retrieved from the metadata of theendpointReference
or from theserviceEndpointInterface
and the WSDL associated with thisService
instance.- Type Parameters:
T
- Service endpoint interface.- Parameters:
endpointReference
- TheEndpointReference
for the target service endpoint that will be invoked by the returned proxy.serviceEndpointInterface
- Service endpoint interface.features
- A list ofWebServiceFeatures
to configure on the proxy. Supported features not in thefeatures
parameter will have their default values.- Returns:
- 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 theserviceName
of thisService
instance. - If a
portName
cannot be extracted from the WSDL orendpointReference
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.
-
getPort
ThegetPort
method returns a proxy. The parameterserviceEndpointInterface
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.- Type Parameters:
T
- Service endpoint interface- Parameters:
serviceEndpointInterface
- Service endpoint interface- Returns:
- 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
-
getPort
ThegetPort
method returns a proxy. The parameterserviceEndpointInterface
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.- Type Parameters:
T
- Service endpoint interface- Parameters:
serviceEndpointInterface
- Service endpoint interfacefeatures
- An array ofWebServiceFeatures
to configure on the proxy. Supported features not in thefeatures
parameter will have their default values.- Returns:
- 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 Also:
-
addPort
Creates a new port for the service. Ports created in this way contain no WSDL port type information and can only be used for creatingDispatch
instances.- Parameters:
portName
- Qualified name for the target service endpointbindingId
- A URI identifier of a binding.endpointAddress
- Address of the target service endpoint as a URI- Throws:
WebServiceException
- If any error in the creation of the port- See Also:
-
createDispatch
Creates aDispatch
instance for use with objects of the user's choosing.- Type Parameters:
T
- type used for messages or message payloads. Implementations are required to supportjavax.xml.transform.Source
andjakarta.xml.soap.SOAPMessage
.- Parameters:
portName
- Qualified name for the target service endpointtype
- The class of object used for messages or message payloads. Implementations are required to supportjavax.xml.transform.Source
andjakarta.xml.soap.SOAPMessage
.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 beMESSAGE
when type isSOAPMessage
.- Returns:
- Dispatch instance
- Throws:
WebServiceException
- If any error in the creation of theDispatch
object- See Also:
-
createDispatch
public abstract <T> Dispatch<T> createDispatch(QName portName, Class<T> type, Service.Mode mode, WebServiceFeature... features) Creates aDispatch
instance for use with objects of the user's choosing.- Type Parameters:
T
- type used for messages or message payloads. Implementations are required to supportjavax.xml.transform.Source
andjakarta.xml.soap.SOAPMessage
.- Parameters:
portName
- Qualified name for the target service endpointtype
- The class of object used for messages or message payloads. Implementations are required to supportjavax.xml.transform.Source
andjakarta.xml.soap.SOAPMessage
.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 beMESSAGE
when type isSOAPMessage
.features
- A list ofWebServiceFeatures
to configure on the proxy. Supported features not in thefeatures
parameter will have their default values.- Returns:
- Dispatch instance
- Throws:
WebServiceException
- If any error in the creation of theDispatch
object or if a feature is enabled that is not compatible with this port or is unsupported.- See Also:
-
createDispatch
public abstract <T> Dispatch<T> createDispatch(EndpointReference endpointReference, Class<T> type, Service.Mode mode, WebServiceFeature... features) Creates aDispatch
instance for use with objects of the user's choosing. If there are any reference parameters in theendpointReference
, then those reference parameters MUST appear as SOAP headers, indicating them to be reference parameters, on all messages sent to the endpoint. TheendpointReference'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 thisService
instance or from the metadata from theendpointReference
. If thisService
instance has a WSDL and theendpointReference
also has a WSDL in its metadata, then the WSDL from this instance MUST be used. If thisService
instance does not have a WSDL and theendpointReference
does have a WSDL, then the WSDL from theendpointReference
MAY be used. An implementation MUST be able to retrieve theportName
from theendpointReference
metadata.This method behaves the same as calling
dispatch = service.createDispatch(portName, type, mode, features);
portName
is retrieved from the WSDL orEndpointReference
metadata.- Type Parameters:
T
- type of object used to messages or message payloads. Implementations are required to supportjavax.xml.transform.Source
andjakarta.xml.soap.SOAPMessage
.- Parameters:
endpointReference
- TheEndpointReference
for the target service endpoint that will be invoked by the returnedDispatch
object.type
- The class of object used to messages or message payloads. Implementations are required to supportjavax.xml.transform.Source
andjakarta.xml.soap.SOAPMessage
.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 beMESSAGE
when type isSOAPMessage
.features
- An array ofWebServiceFeatures
to configure on the proxy. Supported features not in thefeatures
parameter will have their default values.- Returns:
- Dispatch instance
- Throws:
WebServiceException
-- If there is any missing WSDL metadata as required by this method.
- If the
endpointReference
metadata does not match theserviceName
orportName
of a WSDL associated with thisService
instance. - If the
portName
cannot be determined from theEndpointReference
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 Also:
-
createDispatch
public abstract Dispatch<Object> createDispatch(QName portName, jakarta.xml.bind.JAXBContext context, Service.Mode mode) Creates aDispatch
instance for use with Jakarta XML Binding generated objects.- Parameters:
portName
- Qualified name for the target service endpointcontext
- The JAXBContext used to marshall and unmarshall messages or message payloads.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.- Returns:
- Dispatch instance
- Throws:
WebServiceException
- If any error in the creation of theDispatch
object- See Also:
-
createDispatch
public abstract Dispatch<Object> createDispatch(QName portName, jakarta.xml.bind.JAXBContext context, Service.Mode mode, WebServiceFeature... features) Creates aDispatch
instance for use with Jakarta XML Binding generated objects.- Parameters:
portName
- Qualified name for the target service endpointcontext
- The JAXBContext used to marshall and unmarshall messages or message payloads.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.features
- A list ofWebServiceFeatures
to configure on the proxy. Supported features not in thefeatures
parameter will have their default values.- Returns:
- Dispatch instance
- Throws:
WebServiceException
- If any error in the creation of theDispatch
object or if a feature is enabled that is not compatible with this port or is unsupported.- See Also:
-
createDispatch
public abstract Dispatch<Object> createDispatch(EndpointReference endpointReference, jakarta.xml.bind.JAXBContext context, Service.Mode mode, WebServiceFeature... features) Creates aDispatch
instance for use with Jakarta XML Binding generated objects. If there are any reference parameters in theendpointReference
, then those reference parameters MUST appear as SOAP headers, indicating them to be reference parameters, on all messages sent to the endpoint. TheendpointReference'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 thisService
instance or from the metadata from theendpointReference
. If thisService
instance has a WSDL and theendpointReference
also has a WSDL in its metadata, then the WSDL from this instance MUST be used. If thisService
instance does not have a WSDL and theendpointReference
does have a WSDL, then the WSDL from theendpointReference
MAY be used. An implementation MUST be able to retrieve theportName
from theendpointReference
metadata.This method behaves the same as calling
dispatch = service.createDispatch(portName, context, mode, features);
portName
is retrieved from the WSDL orendpointReference
metadata.- Parameters:
endpointReference
- TheEndpointReference
for the target service endpoint that will be invoked by the returnedDispatch
object.context
- The JAXBContext used to marshall and unmarshall messages or message payloads.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.features
- An array ofWebServiceFeatures
to configure on the proxy. Supported features not in thefeatures
parameter will have their default values.- Returns:
- Dispatch instance
- Throws:
WebServiceException
-- If there is any missing WSDL metadata as required by this method.
- If the
endpointReference
metadata does not match theserviceName
orportName
of a WSDL associated with thisService
instance. - If the
portName
cannot be determined from theEndpointReference
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 Also:
-
getServiceName
Gets the name of this service.- Returns:
- Qualified name of this service
-
getPorts
Returns anIterator
for the list ofQName
s of service endpoints grouped by this service- Returns:
- Returns
java.util.Iterator
with elements of typejavax.xml.namespace.QName
- Throws:
WebServiceException
- If this Service class does not have access to the required WSDL metadata
-
getWSDLDocumentLocation
Gets the location of the WSDL document for this Service.- Returns:
- URL for the location of the WSDL document for this service
-
getHandlerResolver
Returns the configured handler resolver.- Returns:
- HandlerResolver The
HandlerResolver
being used by thisService
instance, ornull
if there isn't one.
-
setHandlerResolver
Sets theHandlerResolver
for thisService
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.
- Parameters:
handlerResolver
- TheHandlerResolver
to use for all subsequently created proxy/dispatch objects.- See Also:
-
getExecutor
Returns the executor for thisService
instance.The executor is used for all asynchronous invocations that require callbacks.
- Returns:
- The
java.util.concurrent.Executor
to be used to invoke a callback. - See Also:
-
setExecutor
Sets the executor for thisService
instance.The executor is used for all asynchronous invocations that require callbacks.
- Parameters:
executor
- Thejava.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 Also:
-