Module  java.xml.ws
软件包  javax.xml.ws

Class Service


  • public class Service
extends Object
    Service对象提供Web服务的客户端视图。

    Service作为以下工厂：

    • 用于目标服务端点的代理。
    • 用于动态面向消息的调用远程操作的实例为Dispatch 。

    服务可用的端口可以使用getPorts方法枚举。 或者，您可以将服务端点接口传递到一元getPort方法，并让运行时选择兼容的端口。

    用于通过创建的所有对象处理程序链Service可以通过来设置HandlerResolver 。

    可以在服务上设置一个Executor ，以便更好地控制用于分派异步回调的线程。 例如，通过创建ThreadPoolExecutor并将其注册到服务，可以启用具有某些参数的线程池。

    从以下版本开始：
    1.6，JAX-WS 2.0
    另请参见：
    Provider ， HandlerResolver ， Executor

    • 构造方法详细信息

      • Service

        protected Service​(URL wsdlDocumentLocation,
                  QName serviceName)
        创建一个Service 。 指定的WSDL文档位置和服务限定名必须唯一标识一个wsdl:service元素。
        参数
        wsdlDocumentLocation - URL为服务的WSDL文档位置
        serviceName - QName为服务

      • Service

        protected Service​(URL wsdlDocumentLocation,
                  QName serviceName,
                  WebServiceFeature... features)
        创建一个Service 。 创建的实例配置了Web服务功能。 指定的WSDL文档位置和服务限定名必须唯一标识一个wsdl:service元素。
        参数
        wsdlDocumentLocation - URL为服务的WSDL文档位置
        serviceName - QName为服务
        features - 必须在服务上配置的Web Service功能。 如果提供程序不了解某项功能，则必须抛出WebServiceException异常。

    • 方法详细信息

      • getPort

        public <T> T getPort​(QName portName,
                     Class<T> serviceEndpointInterface)
        getPort方法返回代理。 服务客户端使用此代理来调用目标服务端点上的操作。 serviceEndpointInterface指定创建的动态代理实例支持的服务端点接口。
        参数类型
        T - 服务端点接口。
        参数
        portName - WSDL服务描述中服务端点的合格名称。
        serviceEndpointInterface - 动态代理实例支持的服务端点接口。
        结果
        支持指定服务端点接口的Object Proxy实例。
        异常
        WebServiceException - 在以下情况下抛出此异常：
        • 如果创建代理时出现错误。
        • 如果此方法需要缺少WSDL元数据。
        • 如果指定非法的serviceEndpointInterface或portName 。
        另请参见：
        Proxy ， InvocationHandler

      • getPort

        public <T> T getPort​(QName portName,
                     Class<T> serviceEndpointInterface,
                     WebServiceFeature... features)
        getPort方法返回代理。 服务客户端使用此代理来调用目标服务端点上的操作。 serviceEndpointInterface指定创建的动态代理实例支持的服务端点接口。
        参数类型
        T - 服务端点接口。
        参数
        portName - WSDL服务描述中服务端点的合格名称。
        serviceEndpointInterface - 动态代理实例支持的服务端点接口。
        features - 要在代理上配置的WebServiceFeatures的列表。 features参数中不支持的功能将具有默认值。
        结果
        支持指定服务端点接口的Object Proxy实例。
        异常
        WebServiceException - 在以下情况下抛出此异常：
        • 如果创建代理时出现错误。
        • 如果此方法需要缺少WSDL元数据。
        • 如果指定非法serviceEndpointInterface或portName 。
        • 如果启用了与该端口不兼容或不受支持的功能。
        从以下版本开始：
        1.6，JAX-WS 2.1
        另请参见：
        Proxy ， InvocationHandler ， WebServiceFeature

      • getPort

        public <T> T getPort​(Class<T> serviceEndpointInterface)
        getPort方法返回代理。 参数serviceEndpointInterface指定返回代理支持的服务端点接口。 在实现该方法时，JAX-WS运行时系统负责选择协议绑定（和端口）并相应地配置代理。 返回的代理不应由客户机重新配置。
        参数类型
        T - 服务端点接口。
        参数
        serviceEndpointInterface - 服务端点接口。
        结果
        支持指定服务端点接口的对象实例。
        异常
        WebServiceException -
        • 如果在创建代理时出现错误。
        • 如果此方法需要缺少WSDL元数据。
        • 如果指定了非法的serviceEndpointInterface 。

      • getPort

        public <T> T getPort​(Class<T> serviceEndpointInterface,
                     WebServiceFeature... features)
        getPort方法返回代理。 参数serviceEndpointInterface指定返回代理支持的服务端点接口。 在实现该方法时，JAX-WS运行时系统负责选择协议绑定（和端口）并相应地配置代理。 返回的代理不应由客户机重新配置。
        参数类型
        T - 服务端点接口。
        参数
        serviceEndpointInterface - 服务端点接口。
        features - 要在代理上配置的WebServiceFeatures的列表。 features参数中不支持的功能将具有默认值。
        结果
        支持指定服务端点接口的对象实例。
        异常
        WebServiceException -
        • 如果在创建代理时出现错误。
        • 如果此方法需要缺少WSDL元数据。
        • 如果指定了非法的serviceEndpointInterface 。
        • 如果启用了与该端口不兼容或不受支持的功能。
        从以下版本开始：
        1.6，JAX-WS 2.1
        另请参见：
        WebServiceFeature

      • getPort

        public <T> T getPort​(EndpointReference endpointReference,
                     Class<T> serviceEndpointInterface,
                     WebServiceFeature... features)
        getPort方法返回一个代理。 参数endpointReference指定将由返回的代理调用的端点。 如果endpointReference有任何参考参数，那么这些参考参数必须在发送到端点的所有消息上显示为SOAP头，表示它们是参考参数。 endpointReference's地址必须用于端点上的调用。 参数serviceEndpointInterface指定返回的代理支持的服务端点接口。 在此方法的实施中，JAX-WS运行时系统需要选择协议绑定（和端口），并从与此相关联的WSDL相应地配置代理的责任Service实例或从元数据endpointReference 。 如果此Service实例具有WSDL，并且endpointReference元数据也具有WSDL，则必须使用此实例中的WSDL。 如果这个Service实例没有WSDL，并且endpointReference确实有一个WSDL，那么可以使用来自endpointReference的WSDL。 返回的代理不应由客户机重新配置。 如果此Service实例具有与WSDL中包含的信息相匹配的已知代理端口，则返回该代理，否则将抛出WebServiceException异常。

        调用此方法具有与以下相同的行为 

          port = service.getPort(portName, serviceEndpointInterface);
        其中portName从的元数据检索endpointReference或从serviceEndpointInterface和与此相关的WSDL Service实例。
        参数类型
        T - 服务端点接口。
        参数
        endpointReference - 将由返回的代理调用的目标服务端点的 EndpointReference 。
        serviceEndpointInterface - 服务端点接口。
        features - 要在代理上配置的WebServiceFeatures的列表。 features参数中不支持的功能将具有默认值。
        结果
        支持指定服务端点接口的Object Proxy实例。
        异常
        WebServiceException -
        • 如果在创建代理时出现错误。
        • 如果此方法需要缺少WSDL元数据。
        • 如果endpointReference元数据与该Service实例的serviceName不匹配。
        • 如果portName不能从WSDL或提取endpointReference的元数据。
        • 如果指定无效的endpointReference 。
        • 如果指定无效的serviceEndpointInterface 。
        • 如果启用了与该端口不兼容或不受支持的功能。
        从以下版本开始：
        1.6，JAX-WS 2.1

      • createDispatch

        public <T> Dispatch<T> createDispatch​(QName portName,
                                      Class<T> type,
                                      Service.Mode mode)
        创建一个 Dispatch实例，供客户选择的对象使用。
        参数类型
        T - 消息或有效载荷的类型
        参数
        portName - 目标服务端点的合格名称
        type - 用于消息或消息有效载荷的对象类。 实现都必须支持javax.xml.transform.Source ， javax.xml.soap.SOAPMessage和javax.activation.DataSource ，这取决于所使用的绑定。
        mode - 控制创建的调度实例是消息还是有效负载，即客户端是否使用完整的协议消息或消息有效载荷。 例如，当使用SOAP协议时，此参数控制客户端是否使用SOAP消息或SOAP主体的内容。 当类型为SOAPMessage时，模式必须为MESSAGE。
        结果
        调度实例。
        异常
        WebServiceException - 如果在创建 Dispatch对象时有任何错误。
        另请参见：
        Source ， SOAPMessage

      • createDispatch

        public <T> Dispatch<T> createDispatch​(QName portName,
                                      Class<T> type,
                                      Service.Mode mode,
                                      WebServiceFeature... features)
        创建一个 Dispatch实例，供客户选择的对象使用。
        参数类型
        T - 消息或有效载荷的类型
        参数
        portName - 目标服务端点的合格名称
        type - 用于消息或消息有效载荷的对象类。 需要实施支持javax.xml.transform.Source和javax.xml.soap.SOAPMessage 。
        mode - 控制创建的调度实例是消息还是有效负载，即客户端是否使用完整的协议消息或消息有效载荷。 例如，当使用SOAP协议时，此参数控制客户端是否使用SOAP消息或SOAP主体的内容。 模式必须MESSAGE当类型为SOAPMessage 。
        features - 要在代理上配置的WebServiceFeatures的列表。 features参数中不支持的功能将具有默认值。
        结果
        调度实例。
        异常
        WebServiceException - 如果在创建 Dispatch对象时出现任何错误，或启用了与该端口不兼容或不受支持的功能。
        从以下版本开始：
        1.6，JAX-WS 2.1
        另请参见：
        Source ， SOAPMessage ， WebServiceFeature

      • createDispatch

        public <T> Dispatch<T> createDispatch​(EndpointReference endpointReference,
                                      Class<T> type,
                                      Service.Mode mode,
                                      WebServiceFeature... features)
        创建一个Dispatch实例，供客户选择的对象使用。 如果在endpointReference有任何参考参数，那么在发送到端点的所有消息上，这些参考参数必须显示为SOAP头，表示它们是参考参数。 endpointReference's地址必须用于端点上的调用。 在实现此方法时，JAX-WS运行时系统负责选择协议绑定（和端口），并从与该Service实例相关联的WSDL或从Service的元数据相应地配置endpointReference 。 如果此Service实例具有WSDL，并且endpointReference在其元数据中也具有WSDL，则必须使用此实例的WSDL。 如果此Service实例没有WSDL，并且endpointReference具有WSDL，则可以使用来自endpointReference的WSDL。 一个实现必须能够检索portName从endpointReference的元数据。

        此方法的行为与调用相同 

          dispatch = service.createDispatch(portName, type, mode, features);
        其中portName从WSDL或检索EndpointReference元数据。
        参数类型
        T - 消息或有效载荷的类型
        参数
        endpointReference -该 EndpointReference用于将由返回调用的目标服务端点 Dispatch对象。
        type - 用于消息或消息有效载荷的对象类。 需要实施支持javax.xml.transform.Source和javax.xml.soap.SOAPMessage 。
        mode - 控制创建的调度实例是消息还是面向负载，即客户端是否使用完整的协议消息或消息有效载荷。 例如，当使用SOAP协议时，此参数控制客户端是否使用SOAP消息或SOAP主体的内容。 模式必须MESSAGE当类型为SOAPMessage 。
        features - 要在代理上配置的WebServiceFeatures数组。 features参数中不支持的功能将具有默认值。
        结果
        调度实例
        异常
        WebServiceException -
        • 如果此方法需要缺少WSDL元数据。
        • 如果endpointReference元数据与与此Service实例相关联的WSDL的serviceName或portName不匹配。
        • 如果portName不能从确定EndpointReference的元数据。
        • 如果在创建Dispatch对象时有任何错误。
        • 如果启用了与该端口不兼容或不受支持的功能。
        从以下版本开始：
        1.6，JAX-WS 2.1
        另请参见：
        Source ， SOAPMessage ， WebServiceFeature

      • createDispatch

        public Dispatch<Object> createDispatch​(QName portName,
                                       JAXBContext context,
                                       Service.Mode mode)
        创建一个用于JAXB生成的对象的 Dispatch实例。
        参数
        portName - 目标服务端点的合格名称
        context - 用于编组 context消息或消息有效载荷的JAXB上下文。
        mode - 控制创建的调度实例是消息还是有效负载，即客户端是否使用完整的协议消息或消息有效载荷。 例如，当使用SOAP协议时，此参数控制客户端是否使用SOAP消息或SOAP主体的内容。
        结果
        调度实例。
        异常
        WebServiceException - 如果在创建 Dispatch对象时有任何错误。
        另请参见：
        JAXBContext

      • createDispatch

        public Dispatch<Object> createDispatch​(QName portName,
                                       JAXBContext context,
                                       Service.Mode mode,
                                       WebServiceFeature... features)
        创建一个用于JAXB生成的对象的 Dispatch实例。
        参数
        portName - 目标服务端点的合格名称
        context - 用于编组 context消息或消息有效载荷的JAXB上下文。
        mode - 控制所创建的调度实例是消息还是面向负载，即客户端是否使用完整的协议消息或消息有效载荷。 例如，当使用SOAP协议时，此参数控制客户端是否使用SOAP消息或SOAP主体的内容。
        features - 要在代理上配置的WebServiceFeatures的列表。 features参数中不支持的功能将具有默认值。
        结果
        调度实例。
        异常
        WebServiceException - 如果在创建 Dispatch对象时出现任何错误或启用了与该端口不兼容的功能或不受支持的功能。
        从以下版本开始：
        1.6，JAX-WS 2.1
        另请参见：
        JAXBContext ， WebServiceFeature

      • createDispatch

        public Dispatch<Object> createDispatch​(EndpointReference endpointReference,
                                       JAXBContext context,
                                       Service.Mode mode,
                                       WebServiceFeature... features)
        创建一个用于JAXB生成的对象的Dispatch实例。 如果endpointReference有任何参考参数，那么这些参考参数必须在发送到端点的所有消息上显示为SOAP头，表示它们是参考参数。 endpointReference's地址必须用于端点上的调用。 在实现此方法时，JAX-WS运行时系统负责选择协议绑定（和端口），并从与该Service实例相关联的WSDL或从Service的元数据相应地配置endpointReference 。 如果此Service实例具有WSDL，并且endpointReference在其元数据中也具有WSDL，则必须使用此实例的WSDL。 如果这个Service实例没有WSDL，并且endpointReference确实有一个WSDL，那么可以使用来自endpointReference的WSDL。 一个实现必须能够检索portName从endpointReference的元数据。

        此方法与调用相同 

          dispatch = service.createDispatch(portName, context, mode, features);
        其中portName从WSDL或endpointReference元数据检索。
        参数
        endpointReference -该 EndpointReference用于将由返回调用的目标服务端点 Dispatch对象。
        context - 用于编组 context消息或消息有效载荷的JAXB上下文。
        mode - 控制创建的调度实例是消息还是有效负载，即客户端是否使用完整的协议消息或消息有效载荷。 例如，当使用SOAP协议时，此参数控制客户端是否使用SOAP消息或SOAP主体的内容。
        features -数组WebServiceFeatures配置上的代理。 features参数中不支持的功能将具有默认值。
        结果
        调度实例
        异常
        WebServiceException -
        • 如果此方法需要缺少WSDL元数据。
        • 如果endpointReference元数据与该Service实例相关联的WSDL的serviceName或portName不匹配。
        • 如果portName不能从确定EndpointReference的元数据。
        • 如果在创建Dispatch对象时有任何错误。
        • 如果启用了与此端口不兼容或不受支持的功能。
        从以下版本开始：
        1.6，JAX-WS 2.1
        另请参见：
        JAXBContext ， WebServiceFeature

      • getServiceName

        public QName getServiceName​()
        获取此服务的名称。
        结果
        此服务的合格名称

      • getPorts

        public Iterator<QName> getPorts​()
        返回一个 Iterator的 QName的服务端点列表 QName服务分组
        结果
        返回 java.util.Iterator ，元素类型为 javax.xml.namespace.QName 。
        异常
        WebServiceException - 如果此Service类无法访问所需的WSDL元数据。

      • getWSDLDocumentLocation

        public URL getWSDLDocumentLocation​()
        获取此服务的WSDL文档的位置。
        结果
        此服务的WSDL文档的位置的URL。

      • getHandlerResolver

        public HandlerResolver getHandlerResolver​()
        返回配置的处理程序解析器。
        结果
        HandlerResolver HandlerResolver被这个 Service实例使用，或者如果没有的话是 null 。

      • setHandlerResolver

        public void setHandlerResolver​(HandlerResolver handlerResolver)
        设置HandlerResolver此Service实例。

        处理程序解析器（如果存在）将为创建的每个代理或分派实例调用一次，并且解析器返回的处理程序链将在实例上设置。

        参数
        handlerResolver - 用于所有随后创建的代理/调度对象的 HandlerResolver 。
        另请参见：
        HandlerResolver

      • getExecutor

        public Executor getExecutor​()
        返回这个Service实例的执行器。 执行器用于需要回调的所有异步调用。
        结果
        用于调用回调的 java.util.concurrent.Executor 。
        另请参见：
        Executor

      • setExecutor

        public void setExecutor​(Executor executor)
        设置这个Service实例的执行器。 执行器用于需要回调的所有异步调用。
        参数
        executor - 用于调用回调的 java.util.concurrent.Executor 。
        异常
        SecurityException - 如果实例不支持以安全原因设置执行程序（例如缺少必需的权限）。
        另请参见：
        Executor

      • create

        public static Service create​(URL wsdlDocumentLocation,
                             QName serviceName)
        创建一个Service实例。 指定的WSDL文档位置和服务限定名必须唯一标识一个wsdl:service元素。
        参数
        wsdlDocumentLocation - URL ，用于服务的WSDL文档位置
        serviceName - QName为服务
        结果
        服务实例
        异常
        WebServiceException - 创建指定服务时是否有任何错误。

      • create

        public static Service create​(URL wsdlDocumentLocation,
                             QName serviceName,
                             WebServiceFeature... features)
        创建一个Service实例。 创建的实例配置了Web服务功能。 指定的WSDL文档位置和服务限定名必须唯一标识一个wsdl:service元素。
        参数
        wsdlDocumentLocation - URL为服务的WSDL文档位置
        serviceName - QName为服务
        features - 必须在服务上配置的Web Service功能。 如果提供程序不了解某项功能，则必须抛出WebServiceException异常。
        结果
        配置了请求的Web服务功能的服务实例
        异常
        WebServiceException - 创建指定服务时是否有任何错误。
        从以下版本开始：
        1.7，JAX-WS 2.2

      • create

        public static Service create​(QName serviceName)
        创建一个 Service实例。
        参数
        serviceName - QName为服务
        结果
        服务实例
        异常
        WebServiceException - 创建指定服务时是否有任何错误

      • create

        public static Service create​(QName serviceName,
                             WebServiceFeature... features)
        创建一个Service实例。 创建的实例配置了Web服务功能。
        参数
        serviceName - QName为服务
        features - 必须在服务上配置的Web Service功能。 如果提供程序不了解某项功能，则必须抛出WebServiceException异常。
        结果
        配置了请求的Web服务功能的服务实例
        异常
        WebServiceException - 创建指定服务时是否有任何错误
        从以下版本开始：
        1.7，JAX-WS 2.2