public class Service
extends java.lang.Object
Service objects provide the client view of a Web service.
Service acts as a factory of the following:
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.
Provider,
HandlerResolver,
Executor| Modifier and Type | Class and Description |
|---|---|
static class |
Service.Mode
The orientation of a dynamic client or service.
|
| Modifier | Constructor and Description |
|---|---|
protected |
Service(java.net.URL wsdlDocumentLocation,
javax.xml.namespace.QName serviceName)
Creates a
Service. |
protected |
Service(java.net.URL wsdlDocumentLocation,
javax.xml.namespace.QName serviceName,
WebServiceFeature... features)
Creates a
Service. |
| Modifier and Type | Method and Description |
|---|---|
void |
addPort(javax.xml.namespace.QName portName,
java.lang.String bindingId,
java.lang.String endpointAddress)
Creates a new port for the service.
|
static Service |
create(javax.xml.namespace.QName serviceName)
Creates a
Service instance. |
static Service |
create(javax.xml.namespace.QName serviceName,
WebServiceFeature... features)
Creates a
Service instance. |
static Service |
create(java.net.URL wsdlDocumentLocation,
javax.xml.namespace.QName serviceName)
Creates a
Service instance. |
static Service |
create(java.net.URL wsdlDocumentLocation,
javax.xml.namespace.QName serviceName,
WebServiceFeature... features)
Creates a
Service instance. |
<T> Dispatch<T> |
createDispatch(EndpointReference endpointReference,
java.lang.Class<T> type,
Service.Mode mode,
WebServiceFeature... features)
Creates a
Dispatch instance for use with objects of
the client's choosing. |
Dispatch<java.lang.Object> |
createDispatch(EndpointReference endpointReference,
JAXBContext context,
Service.Mode mode,
WebServiceFeature... features)
Creates a
Dispatch instance for use with Jakarta XML Binding
generated objects. |
<T> Dispatch<T> |
createDispatch(javax.xml.namespace.QName portName,
java.lang.Class<T> type,
Service.Mode mode)
Creates a
Dispatch instance for use with objects of
the client's choosing. |
<T> Dispatch<T> |
createDispatch(javax.xml.namespace.QName portName,
java.lang.Class<T> type,
Service.Mode mode,
WebServiceFeature... features)
Creates a
Dispatch instance for use with objects of
the client's choosing. |
Dispatch<java.lang.Object> |
createDispatch(javax.xml.namespace.QName portName,
JAXBContext context,
Service.Mode mode)
Creates a
Dispatch instance for use with Jakarta XML Binding
generated objects. |
Dispatch<java.lang.Object> |
createDispatch(javax.xml.namespace.QName portName,
JAXBContext context,
Service.Mode mode,
WebServiceFeature... features)
Creates a
Dispatch instance for use with Jakarta XML Binding
generated objects. |
java.util.concurrent.Executor |
getExecutor()
Returns the executor for this
Serviceinstance. |
HandlerResolver |
getHandlerResolver()
Returns the configured handler resolver.
|
<T> T |
getPort(java.lang.Class<T> serviceEndpointInterface)
The
getPort method returns a proxy. |
<T> T |
getPort(java.lang.Class<T> serviceEndpointInterface,
WebServiceFeature... features)
The
getPort method returns a proxy. |
<T> T |
getPort(EndpointReference endpointReference,
java.lang.Class<T> serviceEndpointInterface,
WebServiceFeature... features)
The
getPort method returns a proxy. |
<T> T |
getPort(javax.xml.namespace.QName portName,
java.lang.Class<T> serviceEndpointInterface)
The
getPort method returns a proxy. |
<T> T |
getPort(javax.xml.namespace.QName portName,
java.lang.Class<T> serviceEndpointInterface,
WebServiceFeature... features)
The
getPort method returns a proxy. |
java.util.Iterator<javax.xml.namespace.QName> |
getPorts()
Returns an
Iterator for the list of
QNames of service endpoints grouped by this
service |
javax.xml.namespace.QName |
getServiceName()
Gets the name of this service.
|
java.net.URL |
getWSDLDocumentLocation()
Gets the location of the WSDL document for this Service.
|
void |
setExecutor(java.util.concurrent.Executor executor)
Sets the executor for this
Service instance. |
void |
setHandlerResolver(HandlerResolver handlerResolver)
Sets the
HandlerResolver for this Service
instance. |
protected Service(java.net.URL wsdlDocumentLocation,
javax.xml.namespace.QName serviceName)
Service.
The specified WSDL document location and service qualified name MUST
uniquely identify a wsdl:service element.wsdlDocumentLocation - URL for the WSDL document location
for the serviceserviceName - QName for the serviceprotected Service(java.net.URL wsdlDocumentLocation,
javax.xml.namespace.QName serviceName,
WebServiceFeature... features)
Service. 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.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.public <T> T getPort(javax.xml.namespace.QName portName,
java.lang.Class<T> serviceEndpointInterface)
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.T - Service endpoint interface.portName - Qualified name of the service endpoint in
the WSDL service description.serviceEndpointInterface - Service endpoint interface
supported by the dynamic proxy instance.WebServiceException - This exception is thrown in the
following cases:
serviceEndpointInterface
or portName is specified.
Proxy,
InvocationHandlerpublic <T> T getPort(javax.xml.namespace.QName portName,
java.lang.Class<T> serviceEndpointInterface,
WebServiceFeature... features)
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.T - Service endpoint interface.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 the features
parameter will have their default values.WebServiceException - This exception is thrown in the
following cases:
serviceEndpointInterface
or portName is specified.
Proxy,
InvocationHandler,
WebServiceFeaturepublic <T> T getPort(java.lang.Class<T> serviceEndpointInterface)
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 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.T - Service endpoint interface.serviceEndpointInterface - Service endpoint interface.WebServiceException - serviceEndpointInterface
is specified.
public <T> T getPort(java.lang.Class<T> serviceEndpointInterface,
WebServiceFeature... features)
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 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.T - Service endpoint interface.serviceEndpointInterface - Service endpoint interface.features - A list of WebServiceFeatures to configure on the
proxy. Supported features not in the features
parameter will have their default values.WebServiceException - serviceEndpointInterface
is specified.
WebServiceFeaturepublic <T> T getPort(EndpointReference endpointReference, java.lang.Class<T> serviceEndpointInterface, WebServiceFeature... features)
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 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 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.T - Service endpoint interface.endpointReference - The EndpointReference
for the target service endpoint that will be invoked by the
returned proxy.serviceEndpointInterface - Service endpoint interface.features - A list of WebServiceFeatures to configure on the
proxy. Supported features not in the features
parameter will have their default values.WebServiceException - endpointReference metadata does
not match the serviceName of this
Service instance.
portName cannot be extracted
from the WSDL or endpointReference metadata.
endpointReference
is specified.
serviceEndpointInterface
is specified.
public void addPort(javax.xml.namespace.QName portName,
java.lang.String bindingId,
java.lang.String endpointAddress)
Dispatchinstances.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.WebServiceException - If any error in the creation of
the port.SOAPBinding.SOAP11HTTP_BINDING,
SOAPBinding.SOAP12HTTP_BINDING,
HTTPBinding.HTTP_BINDINGpublic <T> Dispatch<T> createDispatch(javax.xml.namespace.QName portName, java.lang.Class<T> type, Service.Mode mode)
Dispatch instance for use with objects of
the client's choosing.T - The type of the message or payloadportName - Qualified name for the target service endpointtype - The class of object used for messages or message
payloads. Implementations are required to support
javax.xml.transform.Source, jakarta.xml.soap.SOAPMessage
and jakarta.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.WebServiceException - If any error in the creation of
the Dispatch object.Source,
SOAPMessagepublic <T> Dispatch<T> createDispatch(javax.xml.namespace.QName portName, java.lang.Class<T> type, Service.Mode mode, WebServiceFeature... features)
Dispatch instance for use with objects of
the client's choosing.T - The type of the message or payloadportName - Qualified name for the target service endpointtype - The class of object used for messages or message
payloads. Implementations are required to support
javax.xml.transform.Source and jakarta.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 be MESSAGE
when type is SOAPMessage.features - A list of WebServiceFeatures to configure on the
proxy. Supported features not in the features
parameter will have their default values.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.Source,
SOAPMessage,
WebServiceFeaturepublic <T> Dispatch<T> createDispatch(EndpointReference endpointReference, java.lang.Class<T> type, Service.Mode mode, WebServiceFeature... features)
Dispatch instance for use with objects of
the client'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 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 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.T - The type of the message or payloadendpointReference - The EndpointReference
for the target service endpoint that will be invoked by the
returned Dispatch object.type - The class of object used to messages or message
payloads. Implementations are required to support
javax.xml.transform.Source and jakarta.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 be MESSAGE
when type is SOAPMessage.features - An array of WebServiceFeatures to configure on the
proxy. Supported features not in the features
parameter will have their default values.WebServiceException - endpointReference metadata does
not match the serviceName or portName
of a WSDL associated
with this Service instance.
portName cannot be determined
from the EndpointReference metadata.
Dispatch object.
Source,
SOAPMessage,
WebServiceFeaturepublic Dispatch<java.lang.Object> createDispatch(javax.xml.namespace.QName portName, JAXBContext context, Service.Mode mode)
Dispatch instance for use with Jakarta XML Binding
generated objects.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.WebServiceException - If any error in the creation of
the Dispatch object.JAXBContextpublic Dispatch<java.lang.Object> createDispatch(javax.xml.namespace.QName portName, JAXBContext context, Service.Mode mode, WebServiceFeature... features)
Dispatch instance for use with Jakarta XML Binding
generated objects.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 of WebServiceFeatures to configure on the
proxy. Supported features not in the features
parameter will have their default values.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.JAXBContext,
WebServiceFeaturepublic Dispatch<java.lang.Object> createDispatch(EndpointReference endpointReference, JAXBContext context, Service.Mode mode, WebServiceFeature... features)
Dispatch instance for use with Jakarta XML Binding
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 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 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.endpointReference - The EndpointReference
for the target service endpoint that will be invoked by the
returned Dispatch 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 of WebServiceFeatures to configure on the
proxy. Supported features not in the features
parameter will have their default values.WebServiceException - endpointReference metadata does
not match the serviceName or portName
of a WSDL associated
with this Service instance.
portName cannot be determined
from the EndpointReference metadata.
Dispatch object.
JAXBContext,
WebServiceFeaturepublic javax.xml.namespace.QName getServiceName()
public java.util.Iterator<javax.xml.namespace.QName> getPorts()
Iterator for the list of
QNames of service endpoints grouped by this
servicejava.util.Iterator with elements
of type javax.xml.namespace.QName.WebServiceException - If this Service class does not
have access to the required WSDL metadata.public java.net.URL getWSDLDocumentLocation()
public HandlerResolver getHandlerResolver()
HandlerResolver being
used by this Service instance, or null
if there isn't one.public void setHandlerResolver(HandlerResolver handlerResolver)
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.
handlerResolver - The HandlerResolver to use
for all subsequently created proxy/dispatch objects.HandlerResolverpublic java.util.concurrent.Executor getExecutor()
Serviceinstance.
The executor is used for all asynchronous invocations that
require callbacks.java.util.concurrent.Executor to be
used to invoke a callback.Executorpublic void setExecutor(java.util.concurrent.Executor executor)
Service instance.
The executor is used for all asynchronous invocations that
require callbacks.executor - The java.util.concurrent.Executor
to be used to invoke a callback.java.lang.SecurityException - If the instance does not support
setting an executor for security reasons (e.g. the
necessary permissions are missing).Executorpublic static Service create(java.net.URL wsdlDocumentLocation, javax.xml.namespace.QName serviceName)
Service instance.
The specified WSDL document location and service qualified name MUST
uniquely identify a wsdl:service element.wsdlDocumentLocation - URL for the WSDL document location
for the serviceserviceName - QName for the serviceWebServiceException - If any error in creation of the
specified service.public static Service create(java.net.URL wsdlDocumentLocation, javax.xml.namespace.QName serviceName, WebServiceFeature... features)
Service 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.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.WebServiceException - If any error in creation of the
specified service.public static Service create(javax.xml.namespace.QName serviceName)
Service instance.serviceName - QName for the serviceWebServiceException - If any error in creation of the
specified servicepublic static Service create(javax.xml.namespace.QName serviceName, WebServiceFeature... features)
Service instance. The created instance is
configured with the web service features.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.WebServiceException - If any error in creation of the
specified service