Service
objects provide the client view of a Web service.
Service
acts as a factory of the following:
- Proxies for a target service endpoint.
- Instances of
Dispatch
for dynamic message-oriented invocation of a remote operation.
The ports available on a service can be enumerated using the
getPorts
method. Alternatively, you can pass a
service endpoint interface to the unary getPort
method
and let the runtime select a compatible port.
Handler chains for all the objects created by a Service
can be set by means of a HandlerResolver
.
An Executor
may be set on the service in order
to gain better control over the threads used to dispatch asynchronous
callbacks. For instance, thread pooling with certain parameters
can be enabled by creating a ThreadPoolExecutor
and
registering it with the service.
- See Also:
-
Nested Class Summary
Modifier and TypeClassDescriptionstatic enum
The orientation of a dynamic client or service. -
Constructor Summary
-
Method Summary
Modifier and TypeMethodDescriptionvoid
Creates a new port for the service.static Service
Creates aService
instance.static Service
create
(URL wsdlDocumentLocation, QName serviceName, WebServiceFeature... features) Creates aService
instance.static Service
Creates aService
instance.static Service
create
(QName serviceName, WebServiceFeature... features) Creates aService
instance.createDispatch
(EndpointReference endpointReference, jakarta.xml.bind.JAXBContext context, Service.Mode mode, WebServiceFeature... features) Creates aDispatch
instance for use with Jakarta XML Binding generated objects.<T> Dispatch
<T> createDispatch
(EndpointReference endpointReference, Class<T> type, Service.Mode mode, WebServiceFeature... features) Creates aDispatch
instance for use with objects of the client'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.<T> Dispatch
<T> createDispatch
(QName portName, Class<T> type, Service.Mode mode) Creates aDispatch
instance for use with objects of the client's choosing.<T> Dispatch
<T> createDispatch
(QName portName, Class<T> type, Service.Mode mode, WebServiceFeature... features) Creates aDispatch
instance for use with objects of the client's choosing.Returns the executor for thisService
instance.Returns the configured handler resolver.<T> T
getPort
(EndpointReference endpointReference, Class<T> serviceEndpointInterface, WebServiceFeature... features) ThegetPort
method returns a proxy.<T> T
ThegetPort
method returns a proxy.<T> T
getPort
(Class<T> serviceEndpointInterface, WebServiceFeature... features) ThegetPort
method returns a proxy.<T> T
ThegetPort
method returns a proxy.<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 serviceGets the name of this service.Gets the location of the WSDL document for this Service.void
setExecutor
(Executor executor) Sets the executor for thisService
instance.void
setHandlerResolver
(HandlerResolver handlerResolver) Sets theHandlerResolver
for thisService
instance.
-
Constructor Details
-
Service
Creates aService
.The specified WSDL document location and service qualified name MUST uniquely identify a
wsdl:service
element.- Parameters:
wsdlDocumentLocation
-URL
for the WSDL document location for the serviceserviceName
-QName
for the service
-
Service
Creates aService
. The created instance is configured with the web service features.The specified WSDL document location and service qualified name MUST uniquely identify a
wsdl:service
element.- Parameters:
wsdlDocumentLocation
-URL
for the WSDL document location for the serviceserviceName
-QName
for the servicefeatures
- Web Service features that must be configured on the service. If the provider doesn't understand a feature, it must throw a WebServiceException.
-
-
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 description.serviceEndpointInterface
- Service endpoint interface supported by the dynamic proxy instance.- 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 <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 description.serviceEndpointInterface
- Service endpoint interface supported by the dynamic proxy instance.features
- 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
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 interface.features
- A list of WebServiceFeatures 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:
-
getPort
public <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.
-
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 endpoint.bindingId
- A String 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 client's choosing.- Type Parameters:
T
- The type of the message or payload- 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
,jakarta.xml.soap.SOAPMessage
andjakarta.activation.DataSource
, depending on the binding in use.mode
- Controls whether the created dispatch instance is message or payload oriented, i.e. whether the client will work with complete protocol messages or message payloads. E.g. when using the SOAP protocol, this parameter controls whether the client will work with SOAP messages or the contents of a SOAP body. Mode MUST be MESSAGE when type is SOAPMessage.- Returns:
- Dispatch instance.
- Throws:
WebServiceException
- If any error in the creation of theDispatch
object.- See Also:
-
createDispatch
public <T> Dispatch<T> createDispatch(QName portName, Class<T> type, Service.Mode mode, WebServiceFeature... features) Creates aDispatch
instance for use with objects of the client's choosing.- Type Parameters:
T
- The type of the message or payload- 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 client will work with complete protocol messages or message payloads. E.g. when using the SOAP protocol, this parameter controls whether the client 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 <T> Dispatch<T> createDispatch(EndpointReference endpointReference, Class<T> type, Service.Mode mode, WebServiceFeature... features) Creates aDispatch
instance for use with objects of the client'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
- The type of the message or payload- 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 client will work with complete protocol messages or message payloads. E.g. when using the SOAP protocol, this parameter controls whether the client 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 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 client will work with complete protocol messages or message payloads. E.g. when using the SOAP protocol, this parameter controls whether the client 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 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 client will work with complete protocol messages or message payloads. E.g. when using the SOAP protocol, this parameter controls whether the client 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 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 Jakarta XML Binding context 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 client will work with complete protocol messages or message payloads. E.g. when using the SOAP protocol, this parameter controls whether the client 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:
-
create
Creates aService
instance.The specified WSDL document location and service qualified name MUST uniquely identify a
wsdl:service
element.- Parameters:
wsdlDocumentLocation
-URL
for the WSDL document location for the serviceserviceName
-QName
for the service- Returns:
- Service instance
- Throws:
WebServiceException
- If any error in creation of the specified service.
-
create
public static Service create(URL wsdlDocumentLocation, QName serviceName, WebServiceFeature... features) Creates aService
instance. The created instance is configured with the web service features.The specified WSDL document location and service qualified name MUST uniquely identify a
wsdl:service
element.- Parameters:
wsdlDocumentLocation
-URL
for the WSDL document location for the serviceserviceName
-QName
for the servicefeatures
- Web Service features that must be configured on the service. If the provider doesn't understand a feature, it must throw a WebServiceException.- Returns:
- Service instance configured with requested web service features
- Throws:
WebServiceException
- If any error in creation of the specified service.
-
create
Creates aService
instance.- Parameters:
serviceName
-QName
for the service- Returns:
- Service instance
- Throws:
WebServiceException
- If any error in creation of the specified service
-
create
Creates aService
instance. The created instance is configured with the web service features.- Parameters:
serviceName
-QName
for the servicefeatures
- Web Service features that must be configured on the service. If the provider doesn't understand a feature, it must throw a WebServiceException.- Returns:
- Service instance configured with requested web service features
- Throws:
WebServiceException
- If any error in creation of the specified service
-