- java.lang.Object
-
- javax.xml.ws.Service
-
public class Service extends Object
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 unarygetPort
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 aHandlerResolver
.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 aThreadPoolExecutor
and registering it with the service.- Since:
- JAX-WS 2.0
- See Also:
Provider
,HandlerResolver
,Executor
-
-
Nested Class Summary
Nested Classes Modifier and Type Class and Description static class
Service.Mode
The orientation of a dynamic client or service.
-
Constructor Summary
Constructors Modifier Constructor and Description protected
Service(URL wsdlDocumentLocation, QName serviceName)
protected
Service(URL wsdlDocumentLocation, QName serviceName, WebServiceFeature... features)
-
Method Summary
Methods Modifier and Type Method and Description void
addPort(QName portName, String bindingId, String endpointAddress)
Creates a new port for the service.static Service
create(QName serviceName)
Creates aService
instance.static Service
create(QName serviceName, WebServiceFeature... features)
Creates aService
instance.static Service
create(URL wsdlDocumentLocation, QName serviceName)
Creates aService
instance.static Service
create(URL wsdlDocumentLocation, QName serviceName, WebServiceFeature... features)
Creates aService
instance.<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.Dispatch<Object>
createDispatch(EndpointReference endpointReference, JAXBContext context, Service.Mode mode, WebServiceFeature... features)
Creates aDispatch
instance for use with JAXB 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.Dispatch<Object>
createDispatch(QName portName, JAXBContext context, Service.Mode mode)
Creates aDispatch
instance for use with JAXB generated objects.Dispatch<Object>
createDispatch(QName portName, JAXBContext context, Service.Mode mode, WebServiceFeature... features)
Creates aDispatch
instance for use with JAXB generated objects.Executor
getExecutor()
Returns the executor for thisService
instance.HandlerResolver
getHandlerResolver()
Returns the configured handler resolver.<T> T
getPort(Class<T> serviceEndpointInterface)
ThegetPort
method returns a proxy.<T> T
getPort(Class<T> serviceEndpointInterface, WebServiceFeature... features)
ThegetPort
method returns a proxy.<T> T
getPort(EndpointReference endpointReference, Class<T> serviceEndpointInterface, WebServiceFeature... features)
ThegetPort
method returns a proxy.<T> T
getPort(QName portName, Class<T> serviceEndpointInterface)
ThegetPort
method returns a proxy.<T> T
getPort(QName portName, Class<T> serviceEndpointInterface, WebServiceFeature... features)
ThegetPort
method returns a proxy.Iterator<QName>
getPorts()
Returns anIterator
for the list ofQName
s of service endpoints grouped by this serviceQName
getServiceName()
Gets the name of this service.URL
getWSDLDocumentLocation()
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 Detail
-
Service
protected Service(URL wsdlDocumentLocation, QName serviceName, WebServiceFeature... features)
-
-
Method Detail
-
getPort
public <T> T getPort(QName portName, Class<T> serviceEndpointInterface)
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.- 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:
Proxy
,InvocationHandler
-
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.- 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.
- Since:
- JAX-WS 2.1
- See Also:
Proxy
,InvocationHandler
,WebServiceFeature
-
getPort
public <T> T getPort(Class<T> serviceEndpointInterface)
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 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.- 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
public <T> T getPort(Class<T> serviceEndpointInterface, WebServiceFeature... features)
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 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.- 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.
- Since:
- JAX-WS 2.1
- See Also:
WebServiceFeature
-
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 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 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.- 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.
- Since:
- JAX-WS 2.1
-
addPort
public void addPort(QName portName, String bindingId, String endpointAddress)
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:
SOAPBinding.SOAP11HTTP_BINDING
,SOAPBinding.SOAP12HTTP_BINDING
,HTTPBinding.HTTP_BINDING
-
createDispatch
public <T> Dispatch<T> createDispatch(QName portName, Class<T> type, Service.Mode mode)
Creates aDispatch
instance for use with objects of the client's choosing.- 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
,javax.xml.soap.SOAPMessage
andjavax.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:
Source
,SOAPMessage
-
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.- 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
andjavax.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.- Since:
- JAX-WS 2.1
- See Also:
Source
,SOAPMessage
,WebServiceFeature
-
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 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 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.- 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
andjavax.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.
- Since:
- JAX-WS 2.1
- See Also:
Source
,SOAPMessage
,WebServiceFeature
-
createDispatch
public Dispatch<Object> createDispatch(QName portName, JAXBContext context, Service.Mode mode)
Creates aDispatch
instance for use with JAXB generated objects.- Parameters:
portName
- Qualified name for the target service endpointcontext
- The JAXB 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.- Returns:
- Dispatch instance.
- Throws:
WebServiceException
- If any error in the creation of theDispatch
object.- See Also:
JAXBContext
-
createDispatch
public Dispatch<Object> createDispatch(QName portName, JAXBContext context, Service.Mode mode, WebServiceFeature... features)
Creates aDispatch
instance for use with JAXB generated objects.- Parameters:
portName
- Qualified name for the target service endpointcontext
- The JAXB 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
- 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.- Since:
- JAX-WS 2.1
- See Also:
JAXBContext
,WebServiceFeature
-
createDispatch
public Dispatch<Object> createDispatch(EndpointReference endpointReference, JAXBContext context, Service.Mode mode, WebServiceFeature... features)
Creates aDispatch
instance for use with JAXB 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 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 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 behavies 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 JAXB 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.
- Since:
- JAX-WS 2.1
- See Also:
JAXBContext
,WebServiceFeature
-
getServiceName
public QName getServiceName()
Gets the name of this service.- Returns:
- Qualified name of this service
-
getPorts
public Iterator<QName> 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
public URL getWSDLDocumentLocation()
Gets the location of the WSDL document for this Service.- Returns:
- URL for the location of the WSDL document for this service.
-
getHandlerResolver
public HandlerResolver getHandlerResolver()
Returns the configured handler resolver.- Returns:
- HandlerResolver The
HandlerResolver
being used by thisService
instance, ornull
if there isn't one.
-
setHandlerResolver
public void setHandlerResolver(HandlerResolver handlerResolver)
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:
HandlerResolver
-
getExecutor
public Executor 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:
Executor
-
setExecutor
public void setExecutor(Executor executor)
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:
Executor
-
create
public static Service create(URL wsdlDocumentLocation, QName serviceName)
Creates aService
instance. The specified WSDL document location and service qualified name MUST uniquely identify awsdl:service
element.- Parameters:
wsdlDocumentLocation
-URL
for the WSDL document location for the serviceserviceName
-QName
for the service- 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 awsdl: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.- Throws:
WebServiceException
- If any error in creation of the specified service.- Since:
- JAX-WS 2.2
-
create
public static Service create(QName serviceName)
Creates aService
instance.- Parameters:
serviceName
-QName
for the service- Throws:
WebServiceException
- If any error in creation of the specified service
-
create
public static Service create(QName serviceName, WebServiceFeature... features)
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.- Throws:
WebServiceException
- If any error in creation of the specified service- Since:
- JAX-WS 2.2
-
-
Nederlandse vertaling
U hebt gevraagd om deze site in het Nederlands te bezoeken. Voor nu wordt alleen de interface vertaald, maar nog niet alle inhoud.Als je me wilt helpen met vertalingen, is je bijdrage welkom. Het enige dat u hoeft te doen, is u op de site registreren en mij een bericht sturen waarin u wordt gevraagd om u toe te voegen aan de groep vertalers, zodat u de gewenste pagina's kunt vertalen. Een link onderaan elke vertaalde pagina geeft aan dat u de vertaler bent en heeft een link naar uw profiel.
Bij voorbaat dank.
Document heeft de 11/06/2005 gemaakt, de laatste keer de 04/03/2020 gewijzigd
Bron van het afgedrukte document:https://www.gaudry.be/nl/java-api-rf-javax/xml/ws/service.html
De infobrol is een persoonlijke site waarvan de inhoud uitsluitend mijn verantwoordelijkheid is. De tekst is beschikbaar onder CreativeCommons-licentie (BY-NC-SA). Meer info op de gebruiksvoorwaarden en de auteur.
Referenties
Deze verwijzingen en links verwijzen naar documenten die geraadpleegd zijn tijdens het schrijven van deze pagina, of die aanvullende informatie kunnen geven, maar de auteurs van deze bronnen kunnen niet verantwoordelijk worden gehouden voor de inhoud van deze pagina.
De auteur Deze site is als enige verantwoordelijk voor de manier waarop de verschillende concepten, en de vrijheden die met de referentiewerken worden genomen, hier worden gepresenteerd. Vergeet niet dat u meerdere broninformatie moet doorgeven om het risico op fouten te verkleinen.