1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315
/* * Copyright 2004 Sun Microsystems, Inc. All rights reserved. * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms. */ package javax.xml.ws; import javax.xml.namespace.QName; import java.util.Iterator; import javax.xml.ws.handler.HandlerResolver; import javax.xml.bind.JAXBContext; import javax.xml.ws.spi.ServiceDelegate; import javax.xml.ws.spi.Provider; /** * <code>Service</code> objects provide the client view of a Web service. * <p><code>Service</code> acts as a factory of the following: * <ul> * <li>Proxies for a target service endpoint. * <li>Instances of <code>javax.xml.ws.Dispatch</code> for * dynamic message-oriented invocation of a remote * operation. * </li> * * <p>The ports available on a service can be enumerated using the * <code>getPorts</code> method. Alternatively, you can pass a * service endpoint interface to the unary <code>getPort</code> method * and let the runtime select a compatible port. * * <p>Handler chains for all the objects created by a <code>Service</code> * can be set by means of a <code>HandlerResolver</code>. * * <p>An <code>Executor</code> 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 <code>ThreadPoolExecutor</code> and * registering it with the service. * * @since JAX-WS 2.0 * * @see javax.xml.ws.spi.Provider * @see javax.xml.ws.handler.HandlerResolver * @see java.util.concurrent.Executor **/ public class Service { private ServiceDelegate delegate; /** * The orientation of a dynamic client or service. MESSAGE provides * access to entire protocol message, PAYLOAD to protocol message * payload only. **/ public enum Mode { MESSAGE, PAYLOAD }; protected Service(java.net.URL wsdlDocumentLocation, QName serviceName) { delegate = Provider.provider().createServiceDelegate(wsdlDocumentLocation, serviceName, this.getClass()); } /** The getPort method returns a stub. A service client * uses this stub to invoke operations on the target * service endpoint. The <code>serviceEndpointInterface</code> * specifies the service endpoint interface that is supported by * the created dynamic proxy or stub instance. * * @param portName Qualified name of the service endpoint in * the WSDL service description * @param serviceEndpointInterface Service endpoint interface * supported by the dynamic proxy or stub * instance * @return Object Proxy instance that * supports the specified service endpoint * interface * @throws WebServiceException This exception is thrown in the * following cases: * <UL> * <LI>If there is an error in creation of * the proxy * <LI>If there is any missing WSDL metadata * as required by this method * <LI>Optionally, if an illegal * <code>serviceEndpointInterface</code> * or <code>portName</code> is specified * </UL> * @see java.lang.reflect.Proxy * @see java.lang.reflect.InvocationHandler **/ public <T> T getPort(QName portName, Class<T> serviceEndpointInterface) { return delegate.getPort(portName, serviceEndpointInterface); } /** The getPort method returns a stub. The parameter * <code>serviceEndpointInterface</code> 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. * * @param serviceEndpointInterface Service endpoint interface * @return Object instance that supports the * specified service endpoint interface * @throws WebServiceException * <UL> * <LI>If there is an error during creation * of the proxy * <LI>If there is any missing WSDL metadata * as required by this method * <LI>Optionally, if an illegal * <code>serviceEndpointInterface</code> * is specified * </UL> **/ public <T> T getPort(Class<T> serviceEndpointInterface) { return delegate.getPort(serviceEndpointInterface); } /** Creates a new port for the service. Ports created in this way contain * no WSDL port type information and can only be used for creating * <code>Dispatch</code>instances. * * @param portName Qualified name for the target service endpoint * @param bindingId A String identifier of a binding. * @param endpointAddress Address of the target service endpoint as a URI * @throws WebServiceException If any error in the creation of * the port * * @see javax.xml.ws.soap.SOAPBinding#SOAP11HTTP_BINDING * @see javax.xml.ws.soap.SOAPBinding#SOAP12HTTP_BINDING * @see javax.xml.ws.http.HTTPBinding#HTTP_BINDING **/ public void addPort(QName portName, String bindingId, String endpointAddress) { delegate.addPort(portName, bindingId, endpointAddress); } /** Creates a <code>Dispatch</code> instance for use with objects of * the users choosing. * * @param portName Qualified name for the target service endpoint * @param type The class of object used to messages or message * payloads. Implementations are required to support * <code>javax.xml.transform.Source</code>, <code>javax.xml.soap.SOAPMessage</code> * and <code>javax.activation.DataSource</code>, depending on * the binding in use. * @param mode Controls whether the created dispatch instance is message * or payload oriented, i.e. whether the user will work with complete * protocol messages or message payloads. E.g. when using the SOAP * protocol, this parameter controls whether the user will work with * SOAP messages or the contents of a SOAP body. Mode must be MESSAGE * when type is SOAPMessage. * * @return Dispatch instance * @throws WebServiceException If any error in the creation of * the <code>Dispatch</code> object * @see javax.xml.transform.Source * @see javax.xml.soap.SOAPMessage **/ public <T> Dispatch<T> createDispatch(QName portName, Class<T> type, Mode mode) { return delegate.createDispatch(portName, type, mode); } /** Creates a <code>Dispatch</code> instance for use with JAXB * generated objects. * * @param portName Qualified name for the target service endpoint * @param context The JAXB context used to marshall and unmarshall * messages or message payloads. * @param mode Controls whether the created dispatch instance is message * or payload oriented, i.e. whether the user will work with complete * protocol messages or message payloads. E.g. when using the SOAP * protocol, this parameter controls whether the user will work with * SOAP messages or the contents of a SOAP body. * * @return Dispatch instance * @throws ServiceException If any error in the creation of * the <code>Dispatch</code> object * * @see javax.xml.bind.JAXBContext **/ public Dispatch<Object> createDispatch(QName portName, JAXBContext context, Mode mode) { return delegate.createDispatch(portName, context, mode); } /** Gets the name of this service. * @return Qualified name of this service **/ public QName getServiceName() { return delegate.getServiceName(); } /** Returns an <code>Iterator</code> for the list of * <code>QName</code>s of service endpoints grouped by this * service * * @return Returns <code>java.util.Iterator</code> with elements * of type <code>javax.xml.namespace.QName</code> * @throws WebServiceException If this Service class does not * have access to the required WSDL metadata **/ public Iterator<javax.xml.namespace.QName> getPorts() { return delegate.getPorts(); } /** Gets the location of the WSDL document for this Service. * * @return URL for the location of the WSDL document for * this service **/ public java.net.URL getWSDLDocumentLocation() { return delegate.getWSDLDocumentLocation(); } /** * Returns the configured handler resolver. * * @return HandlerResolver The <code>HandlerResolver</code> being * used by this <code>Service</code> instance, or <code>null</code> * if there isn't one. **/ public HandlerResolver getHandlerResolver() { return delegate.getHandlerResolver(); } /** * Sets the <code>HandlerResolver</code> for this <code>Service</code> * instance. * <p> * 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. * * @param handlerResolver The <code>HandlerResolver</code> to use * for all subsequently created proxy/dispatch objects. * * @see javax.xml.ws.handler.HandlerResolver **/ public void setHandlerResolver(HandlerResolver handlerResolver) { delegate.setHandlerResolver(handlerResolver); } /** * Returns the executor for this <code>Service</code>instance. * * The executor is used for all asynchronous invocations that * require callbacks. * * @return The <code>java.util.concurrent.Executor</code> to be * used to invoke a callback. * * @see java.util.concurrent.Executor **/ public java.util.concurrent.Executor getExecutor() { return delegate.getExecutor(); } /** * Sets the executor for this <code>Service</code> instance. * * The executor is used for all asynchronous invocations that * require callbacks. * * @param executor The <code>java.util.concurrent.Executor</code> * 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 java.util.concurrent.Executor **/ public void setExecutor(java.util.concurrent.Executor executor) { delegate.setExecutor(executor); } /** * Create a <code>Service</code> instance. * * The specified WSDL document location and service qualified name must * uniquely identify a <code>wsdl:service</code> element. * * @param wsdlDocumentLocation URL for the WSDL document location * for the service * @param serviceName QName for the service * @throws WebServiceException If any error in creation of the * specified service **/ public static Service create( java.net.URL wsdlDocumentLocation, QName serviceName) { return new Service(wsdlDocumentLocation, serviceName); } /** * Create a <code>Service</code> instance. * * @param serviceName QName for the service * @throws WebServiceException If any error in creation of the * specified service */ public static Service create(QName serviceName) { return new Service(null, serviceName); } }