325N/A * Copyright (c) 2005, 2010, Oracle and/or its affiliates. All rights reserved. 325N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 325N/A * This code is free software; you can redistribute it and/or modify it 325N/A * under the terms of the GNU General Public License version 2 only, as 325N/A * published by the Free Software Foundation. Oracle designates this 325N/A * particular file as subject to the "Classpath" exception as provided 325N/A * by Oracle in the LICENSE file that accompanied this code. 325N/A * This code is distributed in the hope that it will be useful, but WITHOUT 325N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 325N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 325N/A * version 2 for more details (a copy is included in the LICENSE file that 325N/A * accompanied this code). 325N/A * You should have received a copy of the GNU General Public License version 325N/A * 2 along with this work; if not, write to the Free Software Foundation, 325N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 325N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 325N/A * or visit www.oracle.com if you need additional information or have any 325N/A * <code>Service</code> objects provide the client view of a Web service. 325N/A * <p><code>Service</code> acts as a factory of the following: 325N/A * <li>Proxies for a target service endpoint.</li> 325N/A * dynamic message-oriented invocation of a remote 325N/A * <p>The ports available on a service can be enumerated using the 325N/A * <code>getPorts</code> method. Alternatively, you can pass a 325N/A * service endpoint interface to the unary <code>getPort</code> method 325N/A * and let the runtime select a compatible port. 325N/A * <p>Handler chains for all the objects created by a <code>Service</code> 325N/A * can be set by means of a <code>HandlerResolver</code>. 325N/A * <p>An <code>Executor</code> may be set on the service in order 325N/A * to gain better control over the threads used to dispatch asynchronous 325N/A * callbacks. For instance, thread pooling with certain parameters 325N/A * can be enabled by creating a <code>ThreadPoolExecutor</code> and 325N/A * registering it with the service. 325N/A * @see java.util.concurrent.Executor 325N/A * The orientation of a dynamic client or service. <code>MESSAGE</code> provides 325N/A * access to entire protocol message, <code>PAYLOAD</code> to protocol message 325N/A * The <code>getPort</code> method returns a proxy. A service client 325N/A * uses this proxy to invoke operations on the target 325N/A * service endpoint. The <code>serviceEndpointInterface</code> 325N/A * specifies the service endpoint interface that is supported by 325N/A * the created dynamic proxy instance. 325N/A * @param portName Qualified name of the service endpoint in 325N/A * the WSDL service description. 325N/A * @param serviceEndpointInterface Service endpoint interface 325N/A * supported by the dynamic proxy instance. 325N/A * @return Object Proxy instance that 325N/A * supports the specified service endpoint 325N/A * @throws WebServiceException This exception is thrown in the 325N/A * <LI>If there is an error in creation of 325N/A * <LI>If there is any missing WSDL metadata 325N/A * as required by this method. 325N/A * <code>serviceEndpointInterface</code> 325N/A * or <code>portName</code> is specified. 325N/A * @see java.lang.reflect.Proxy 325N/A * @see java.lang.reflect.InvocationHandler 325N/A * The <code>getPort</code> method returns a proxy. A service client 325N/A * uses this proxy to invoke operations on the target 325N/A * service endpoint. The <code>serviceEndpointInterface</code> 325N/A * specifies the service endpoint interface that is supported by 325N/A * the created dynamic proxy instance. 325N/A * @param portName Qualified name of the service endpoint in 325N/A * the WSDL service description. 325N/A * @param serviceEndpointInterface Service endpoint interface 325N/A * supported by the dynamic proxy instance. 325N/A * @param features A list of WebServiceFeatures to configure on the 325N/A * proxy. Supported features not in the <code>features 325N/A * </code> parameter will have their default values. 325N/A * @return Object Proxy instance that 325N/A * supports the specified service endpoint 325N/A * @throws WebServiceException This exception is thrown in the 325N/A * <LI>If there is an error in creation of 325N/A * <LI>If there is any missing WSDL metadata 325N/A * as required by this method. 325N/A * <code>serviceEndpointInterface</code> 325N/A * or <code>portName</code> is specified. 325N/A * <LI>If a feature is enabled that is not compatible 325N/A * with this port or is unsupported. 325N/A * @see java.lang.reflect.Proxy 325N/A * @see java.lang.reflect.InvocationHandler 325N/A * @see WebServiceFeature 325N/A * The <code>getPort</code> method returns a proxy. The parameter 325N/A * <code>serviceEndpointInterface</code> specifies the service 325N/A * endpoint interface that is supported by the returned proxy. 325N/A * In the implementation of this method, the JAX-WS 325N/A * runtime system takes the responsibility of selecting a protocol 325N/A * binding (and a port) and configuring the proxy accordingly. 325N/A * The returned proxy should not be reconfigured by the client. 325N/A * @param serviceEndpointInterface Service endpoint interface. 325N/A * @return Object instance that supports the 325N/A * specified service endpoint interface. 325N/A * @throws WebServiceException 325N/A * <LI>If there is an error during creation 325N/A * <LI>If there is any missing WSDL metadata 325N/A * as required by this method. 325N/A * <code>serviceEndpointInterface</code> 325N/A * The <code>getPort</code> method returns a proxy. The parameter 325N/A * <code>serviceEndpointInterface</code> specifies the service 325N/A * endpoint interface that is supported by the returned proxy. 325N/A * In the implementation of this method, the JAX-WS 325N/A * runtime system takes the responsibility of selecting a protocol 325N/A * binding (and a port) and configuring the proxy accordingly. 325N/A * The returned proxy should not be reconfigured by the client. 325N/A * @param serviceEndpointInterface Service endpoint interface. 325N/A * @param features A list of WebServiceFeatures to configure on the 325N/A * proxy. Supported features not in the <code>features 325N/A * </code> parameter will have their default values. 325N/A * @return Object instance that supports the 325N/A * specified service endpoint interface. 325N/A * @throws WebServiceException 325N/A * <LI>If there is an error during creation 325N/A * <LI>If there is any missing WSDL metadata 325N/A * as required by this method. 325N/A * <code>serviceEndpointInterface</code> 325N/A * <LI>If a feature is enabled that is not compatible 325N/A * with this port or is unsupported. 325N/A * @see WebServiceFeature 325N/A * The <code>getPort</code> method returns a proxy. 325N/A * The parameter <code>endpointReference</code> specifies the 325N/A * endpoint that will be invoked by the returned proxy. If there 325N/A * are any reference parameters in the 325N/A * <code>endpointReference</code>, then those reference 325N/A * parameters MUST appear as SOAP headers, indicating them to be 325N/A * reference parameters, on all messages sent to the endpoint. 325N/A * The <code>endpointReference's</code> address MUST be used 325N/A * for invocations on the endpoint. 325N/A * The parameter <code>serviceEndpointInterface</code> specifies 325N/A * the service endpoint interface that is supported by the 325N/A * In the implementation of this method, the JAX-WS 325N/A * runtime system takes the responsibility of selecting a protocol 325N/A * binding (and a port) and configuring the proxy accordingly from 325N/A * the WSDL associated with this <code>Service</code> instance or 325N/A * from the metadata from the <code>endpointReference</code>. 325N/A * If this <code>Service</code> instance has a WSDL and 325N/A * the <code>endpointReference</code> metadata 325N/A * also has a WSDL, then the WSDL from this instance MUST be used. 325N/A * If this <code>Service</code> instance does not have a WSDL and 325N/A * the <code>endpointReference</code> does have a WSDL, then the 325N/A * WSDL from the <code>endpointReference</code> MAY be used. 325N/A * The returned proxy should not be reconfigured by the client. 325N/A * If this <code>Service</code> instance has a known proxy 325N/A * port that matches the information contained in 325N/A * then that proxy is returned, otherwise a WebServiceException 325N/A * Calling this method has the same behavior as the following 325N/A * <code>port = service.getPort(portName, serviceEndpointInterface);</code> 325N/A * where the <code>portName</code> is retrieved from the 325N/A * metadata of the <code>endpointReference</code> or from the 325N/A * <code>serviceEndpointInterface</code> and the WSDL 325N/A * associated with this <code>Service</code> instance. 325N/A * @param endpointReference The <code>EndpointReference</code> 325N/A * for the target service endpoint that will be invoked by the 325N/A * @param serviceEndpointInterface Service endpoint interface. 325N/A * @param features A list of <code>WebServiceFeatures</code> to configure on the 325N/A * proxy. Supported features not in the <code>features 325N/A * </code> parameter will have their default values. 325N/A * @return Object Proxy instance that supports the 325N/A * specified service endpoint interface. 325N/A * @throws WebServiceException 325N/A * <LI>If there is an error during creation 325N/A * <LI>If there is any missing WSDL metadata 325N/A * as required by this method. 325N/A * <LI>If the <code>endpointReference</code> metadata does 325N/A * not match the <code>serviceName</code> of this 325N/A * <code>Service</code> instance. 325N/A * <LI>If a <code>portName</code> cannot be extracted 325N/A * from the WSDL or <code>endpointReference</code> metadata. 325N/A * <code>endpointReference</code> 325N/A * <code>serviceEndpointInterface</code> 325N/A * <LI>If a feature is enabled that is not compatible 325N/A * with this port or is unsupported. 325N/A * Creates a new port for the service. Ports created in this way contain 325N/A * no WSDL port type information and can only be used for creating 325N/A * <code>Dispatch</code>instances. 325N/A * @param portName Qualified name for the target service endpoint. 325N/A * @param bindingId A String identifier of a binding. 325N/A * @param endpointAddress Address of the target service endpoint as a URI. 325N/A * @throws WebServiceException If any error in the creation of 325N/A * Creates a <code>Dispatch</code> instance for use with objects of 325N/A * the client's choosing. 325N/A * @param portName Qualified name for the target service endpoint 325N/A * @param type The class of object used for messages or message 325N/A * payloads. Implementations are required to support 325N/A * and <code>javax.activation.DataSource</code>, depending on 325N/A * @param mode Controls whether the created dispatch instance is message 325N/A * or payload oriented, i.e. whether the client will work with complete 325N/A * protocol messages or message payloads. E.g. when using the SOAP 325N/A * protocol, this parameter controls whether the client will work with 325N/A * SOAP messages or the contents of a SOAP body. Mode MUST be MESSAGE 325N/A * when type is SOAPMessage. 325N/A * @return Dispatch instance. 325N/A * @throws WebServiceException If any error in the creation of 325N/A * the <code>Dispatch</code> object. 325N/A * Creates a <code>Dispatch</code> instance for use with objects of 325N/A * the client's choosing. 325N/A * @param portName Qualified name for the target service endpoint 325N/A * @param type The class of object used for messages or message 325N/A * payloads. Implementations are required to support 325N/A * @param mode Controls whether the created dispatch instance is message 325N/A * or payload oriented, i.e. whether the client will work with complete 325N/A * protocol messages or message payloads. E.g. when using the SOAP 325N/A * protocol, this parameter controls whether the client will work with 325N/A * SOAP messages or the contents of a SOAP body. Mode MUST be <code>MESSAGE</code> 325N/A * when type is <code>SOAPMessage</code>. 325N/A * @param features A list of <code>WebServiceFeatures</code> to configure on the 325N/A * proxy. Supported features not in the <code>features 325N/A * </code> parameter will have their default values. 325N/A * @return Dispatch instance. 325N/A * @throws WebServiceException If any error in the creation of 325N/A * the <code>Dispatch</code> object or if a 325N/A * feature is enabled that is not compatible with 325N/A * this port or is unsupported. 325N/A * @see WebServiceFeature 325N/A * Creates a <code>Dispatch</code> instance for use with objects of 325N/A * the client's choosing. If there 325N/A * are any reference parameters in the 325N/A * <code>endpointReference</code>, then those reference 325N/A * parameters MUST appear as SOAP headers, indicating them to be 325N/A * reference parameters, on all messages sent to the endpoint. 325N/A * The <code>endpointReference's</code> address MUST be used 325N/A * for invocations on the endpoint. 325N/A * In the implementation of this method, the JAX-WS 325N/A * runtime system takes the responsibility of selecting a protocol 325N/A * binding (and a port) and configuring the dispatch accordingly from 325N/A * the WSDL associated with this <code>Service</code> instance or 325N/A * from the metadata from the <code>endpointReference</code>. 325N/A * If this <code>Service</code> instance has a WSDL and 325N/A * the <code>endpointReference</code> 325N/A * also has a WSDL in its metadata, then the WSDL from this instance MUST be used. 325N/A * If this <code>Service</code> instance does not have a WSDL and 325N/A * the <code>endpointReference</code> does have a WSDL, then the 325N/A * WSDL from the <code>endpointReference</code> MAY be used. 325N/A * An implementation MUST be able to retrieve the <code>portName</code> from the 325N/A * <code>endpointReference</code> metadata. 325N/A * This method behaves the same as calling 325N/A * <code>dispatch = service.createDispatch(portName, type, mode, features);</code> 325N/A * where the <code>portName</code> is retrieved from the 325N/A * WSDL or <code>EndpointReference</code> metadata. 325N/A * @param endpointReference The <code>EndpointReference</code> 325N/A * for the target service endpoint that will be invoked by the 325N/A * returned <code>Dispatch</code> object. 325N/A * @param type The class of object used to messages or message 325N/A * payloads. Implementations are required to support 325N/A * @param mode Controls whether the created dispatch instance is message 325N/A * or payload oriented, i.e. whether the client will work with complete 325N/A * protocol messages or message payloads. E.g. when using the SOAP 325N/A * protocol, this parameter controls whether the client will work with 325N/A * SOAP messages or the contents of a SOAP body. Mode MUST be <code>MESSAGE</code> 325N/A * when type is <code>SOAPMessage</code>. 325N/A * @param features An array of <code>WebServiceFeatures</code> to configure on the 325N/A * proxy. Supported features not in the <code>features 325N/A * </code> parameter will have their default values. 325N/A * @return Dispatch instance 325N/A * @throws WebServiceException 325N/A * <LI>If there is any missing WSDL metadata 325N/A * as required by this method. 325N/A * <li>If the <code>endpointReference</code> metadata does 325N/A * not match the <code>serviceName</code> or <code>portName</code> 325N/A * with this <code>Service</code> instance. 325N/A * <li>If the <code>portName</code> cannot be determined 325N/A * from the <code>EndpointReference</code> metadata. 325N/A * <li>If any error in the creation of 325N/A * the <code>Dispatch</code> object. 325N/A * <li>If a feature is enabled that is not 325N/A * compatible with this port or is unsupported. 325N/A * @see WebServiceFeature 325N/A * Creates a <code>Dispatch</code> instance for use with JAXB 325N/A * @param portName Qualified name for the target service endpoint 325N/A * @param context The JAXB context used to marshall and unmarshall 325N/A * messages or message payloads. 325N/A * @param mode Controls whether the created dispatch instance is message 325N/A * or payload oriented, i.e. whether the client will work with complete 325N/A * protocol messages or message payloads. E.g. when using the SOAP 325N/A * protocol, this parameter controls whether the client will work with 325N/A * SOAP messages or the contents of a SOAP body. 325N/A * @return Dispatch instance. 325N/A * @throws WebServiceException If any error in the creation of 325N/A * the <code>Dispatch</code> object. 325N/A * Creates a <code>Dispatch</code> instance for use with JAXB 325N/A * @param portName Qualified name for the target service endpoint 325N/A * @param context The JAXB context used to marshall and unmarshall 325N/A * messages or message payloads. 325N/A * @param mode Controls whether the created dispatch instance is message 325N/A * or payload oriented, i.e. whether the client will work with complete 325N/A * protocol messages or message payloads. E.g. when using the SOAP 325N/A * protocol, this parameter controls whether the client will work with 325N/A * SOAP messages or the contents of a SOAP body. 325N/A * @param features A list of <code>WebServiceFeatures</code> to configure on the 325N/A * proxy. Supported features not in the <code>features 325N/A * </code> parameter will have their default values. 325N/A * @return Dispatch instance. 325N/A * @throws WebServiceException If any error in the creation of 325N/A * the <code>Dispatch</code> object or if a 325N/A * feature is enabled that is not compatible with 325N/A * this port or is unsupported. 325N/A * @see WebServiceFeature 325N/A * Creates a <code>Dispatch</code> instance for use with JAXB 325N/A * generated objects. If there 325N/A * are any reference parameters in the 325N/A * <code>endpointReference</code>, then those reference 325N/A * parameters MUST appear as SOAP headers, indicating them to be 325N/A * reference parameters, on all messages sent to the endpoint. 325N/A * The <code>endpointReference's</code> address MUST be used 325N/A * for invocations on the endpoint. 325N/A * In the implementation of this method, the JAX-WS 325N/A * runtime system takes the responsibility of selecting a protocol 325N/A * binding (and a port) and configuring the dispatch accordingly from 325N/A * the WSDL associated with this <code>Service</code> instance or 325N/A * from the metadata from the <code>endpointReference</code>. 325N/A * If this <code>Service</code> instance has a WSDL and 325N/A * the <code>endpointReference</code> 325N/A * also has a WSDL in its metadata, then the WSDL from this instance 325N/A * If this <code>Service</code> instance does not have a WSDL and 325N/A * the <code>endpointReference</code> does have a WSDL, then the 325N/A * WSDL from the <code>endpointReference</code> MAY be used. 325N/A * An implementation MUST be able to retrieve the <code>portName</code> from the 325N/A * <code>endpointReference</code> metadata. 325N/A * This method behavies the same as calling 325N/A * <code>dispatch = service.createDispatch(portName, context, mode, features);</code> 325N/A * where the <code>portName</code> is retrieved from the 325N/A * WSDL or <code>endpointReference</code> metadata. 325N/A * @param endpointReference The <code>EndpointReference</code> 325N/A * for the target service endpoint that will be invoked by the 325N/A * returned <code>Dispatch</code> object. 325N/A * @param context The JAXB context used to marshall and unmarshall 325N/A * messages or message payloads. 325N/A * @param mode Controls whether the created dispatch instance is message 325N/A * or payload oriented, i.e. whether the client will work with complete 325N/A * protocol messages or message payloads. E.g. when using the SOAP 325N/A * protocol, this parameter controls whether the client will work with 325N/A * SOAP messages or the contents of a SOAP body. 325N/A * @param features An array of <code>WebServiceFeatures</code> to configure on the 325N/A * proxy. Supported features not in the <code>features 325N/A * </code> parameter will have their default values. 325N/A * @return Dispatch instance 325N/A * @throws WebServiceException 325N/A * <li>If there is any missing WSDL metadata 325N/A * as required by this method. 325N/A * <li>If the <code>endpointReference</code> metadata does 325N/A * not match the <code>serviceName</code> or <code>portName</code> 325N/A * with this <code>Service</code> instance. 325N/A * <li>If the <code>portName</code> cannot be determined 325N/A * from the <code>EndpointReference</code> metadata. 325N/A * <li>If any error in the creation of 325N/A * the <code>Dispatch</code> object. 325N/A * <li>if a feature is enabled that is not 325N/A * compatible with this port or is unsupported. 325N/A * @see WebServiceFeature 325N/A * Gets the name of this service. 325N/A * @return Qualified name of this service 325N/A * Returns an <code>Iterator</code> for the list of 325N/A * <code>QName</code>s of service endpoints grouped by this 325N/A * @return Returns <code>java.util.Iterator</code> with elements 325N/A * @throws WebServiceException If this Service class does not 325N/A * have access to the required WSDL metadata. 325N/A * Gets the location of the WSDL document for this Service. 325N/A * @return URL for the location of the WSDL document for 325N/A * Returns the configured handler resolver. 325N/A * @return HandlerResolver The <code>HandlerResolver</code> being 325N/A * used by this <code>Service</code> instance, or <code>null</code> 325N/A * Sets the <code>HandlerResolver</code> for this <code>Service</code> 325N/A * The handler resolver, if present, will be called once for each 325N/A * proxy or dispatch instance that is created, and the handler chain 325N/A * returned by the resolver will be set on the instance. 325N/A * @param handlerResolver The <code>HandlerResolver</code> to use 325N/A * Returns the executor for this <code>Service</code>instance. 325N/A * The executor is used for all asynchronous invocations that 325N/A * @return The <code>java.util.concurrent.Executor</code> to be 325N/A * used to invoke a callback. 325N/A * @see java.util.concurrent.Executor 325N/A * Sets the executor for this <code>Service</code> instance. 325N/A * The executor is used for all asynchronous invocations that 325N/A * @param executor The <code>java.util.concurrent.Executor</code> 325N/A * to be used to invoke a callback. 325N/A * @throws SecurityException If the instance does not support 325N/A * setting an executor for security reasons (e.g. the 325N/A * necessary permissions are missing). 325N/A * @see java.util.concurrent.Executor 325N/A * Creates a <code>Service</code> instance. 325N/A * The specified WSDL document location and service qualified name MUST 325N/A * uniquely identify a <code>wsdl:service</code> element. 325N/A * @param wsdlDocumentLocation <code>URL</code> for the WSDL document location 325N/A * @param serviceName <code>QName</code> for the service 325N/A * @throws WebServiceException If any error in creation of the 325N/A * Creates a <code>Service</code> instance. The created instance is 325N/A * configured with the web service features. 325N/A * The specified WSDL document location and service qualified name MUST 325N/A * uniquely identify a <code>wsdl:service</code> element. 325N/A * @param wsdlDocumentLocation <code>URL</code> for the WSDL document location 325N/A * @param serviceName <code>QName</code> for the service 325N/A * @param features Web Service features that must be configured on 325N/A * the service. If the provider doesn't understand a feature, 325N/A * it must throw a WebServiceException. 325N/A * @throws WebServiceException If any error in creation of the 325N/A * Creates a <code>Service</code> instance. 325N/A * @param serviceName <code>QName</code> for the service 325N/A * @throws WebServiceException If any error in creation of the 325N/A * Creates a <code>Service</code> instance. The created instance is 325N/A * configured with the web service features. 325N/A * @param serviceName <code>QName</code> for the service 325N/A * @param features Web Service features that must be configured on 325N/A * the service. If the provider doesn't understand a feature, 325N/A * it must throw a WebServiceException. 325N/A * @throws WebServiceException If any error in creation of the