001 /*
002 * Copyright 2005-2006 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package javax.xml.ws;
027
028 import javax.xml.namespace.QName;
029 import java.util.Iterator;
030 import javax.xml.ws.handler.HandlerResolver;
031 import javax.xml.bind.JAXBContext;
032 import javax.xml.ws.spi.ServiceDelegate;
033 import javax.xml.ws.spi.Provider;
034
035 /**
036 * <code>Service</code> objects provide the client view of a Web service.
037 * <p><code>Service</code> acts as a factory of the following:
038 * <ul>
039 * <li>Proxies for a target service endpoint.
040 * <li>Instances of <code>javax.xml.ws.Dispatch</code> for
041 * dynamic message-oriented invocation of a remote
042 * operation.
043 * </li>
044 *
045 * <p>The ports available on a service can be enumerated using the
046 * <code>getPorts</code> method. Alternatively, you can pass a
047 * service endpoint interface to the unary <code>getPort</code> method
048 * and let the runtime select a compatible port.
049 *
050 * <p>Handler chains for all the objects created by a <code>Service</code>
051 * can be set by means of a <code>HandlerResolver</code>.
052 *
053 * <p>An <code>Executor</code> may be set on the service in order
054 * to gain better control over the threads used to dispatch asynchronous
055 * callbacks. For instance, thread pooling with certain parameters
056 * can be enabled by creating a <code>ThreadPoolExecutor</code> and
057 * registering it with the service.
058 *
059 * @since JAX-WS 2.0
060 *
061 * @see javax.xml.ws.spi.Provider
062 * @see javax.xml.ws.handler.HandlerResolver
063 * @see java.util.concurrent.Executor
064 **/
065 public class Service {
066
067 private ServiceDelegate delegate;
068
069 /**
070 * The orientation of a dynamic client or service. MESSAGE provides
071 * access to entire protocol message, PAYLOAD to protocol message
072 * payload only.
073 **/
074 public enum Mode {
075 MESSAGE, PAYLOAD
076 };
077
078 protected Service(java.net.URL wsdlDocumentLocation,
079 QName serviceName) {
080 delegate = Provider.provider().createServiceDelegate(
081 wsdlDocumentLocation, serviceName, this .getClass());
082 }
083
084 /** The getPort method returns a stub. A service client
085 * uses this stub to invoke operations on the target
086 * service endpoint. The <code>serviceEndpointInterface</code>
087 * specifies the service endpoint interface that is supported by
088 * the created dynamic proxy or stub instance.
089 *
090 * @param portName Qualified name of the service endpoint in
091 * the WSDL service description
092 * @param serviceEndpointInterface Service endpoint interface
093 * supported by the dynamic proxy or stub
094 * instance
095 * @return Object Proxy instance that
096 * supports the specified service endpoint
097 * interface
098 * @throws WebServiceException This exception is thrown in the
099 * following cases:
100 * <UL>
101 * <LI>If there is an error in creation of
102 * the proxy
103 * <LI>If there is any missing WSDL metadata
104 * as required by this method
105 * <LI>Optionally, if an illegal
106 * <code>serviceEndpointInterface</code>
107 * or <code>portName</code> is specified
108 * </UL>
109 * @see java.lang.reflect.Proxy
110 * @see java.lang.reflect.InvocationHandler
111 **/
112 public <T> T getPort(QName portName,
113 Class<T> serviceEndpointInterface) {
114 return delegate.getPort(portName, serviceEndpointInterface);
115 }
116
117 /** The getPort method returns a stub. The parameter
118 * <code>serviceEndpointInterface</code> specifies the service
119 * endpoint interface that is supported by the returned proxy.
120 * In the implementation of this method, the JAX-WS
121 * runtime system takes the responsibility of selecting a protocol
122 * binding (and a port) and configuring the proxy accordingly.
123 * The returned proxy should not be reconfigured by the client.
124 *
125 * @param serviceEndpointInterface Service endpoint interface
126 * @return Object instance that supports the
127 * specified service endpoint interface
128 * @throws WebServiceException
129 * <UL>
130 * <LI>If there is an error during creation
131 * of the proxy
132 * <LI>If there is any missing WSDL metadata
133 * as required by this method
134 * <LI>Optionally, if an illegal
135 * <code>serviceEndpointInterface</code>
136 * is specified
137 * </UL>
138 **/
139 public <T> T getPort(Class<T> serviceEndpointInterface) {
140 return delegate.getPort(serviceEndpointInterface);
141 }
142
143 /** Creates a new port for the service. Ports created in this way contain
144 * no WSDL port type information and can only be used for creating
145 * <code>Dispatch</code>instances.
146 *
147 * @param portName Qualified name for the target service endpoint
148 * @param bindingId A String identifier of a binding.
149 * @param endpointAddress Address of the target service endpoint as a URI
150 * @throws WebServiceException If any error in the creation of
151 * the port
152 *
153 * @see javax.xml.ws.soap.SOAPBinding#SOAP11HTTP_BINDING
154 * @see javax.xml.ws.soap.SOAPBinding#SOAP12HTTP_BINDING
155 * @see javax.xml.ws.http.HTTPBinding#HTTP_BINDING
156 **/
157 public void addPort(QName portName, String bindingId,
158 String endpointAddress) {
159 delegate.addPort(portName, bindingId, endpointAddress);
160 }
161
162 /** Creates a <code>Dispatch</code> instance for use with objects of
163 * the users choosing.
164 *
165 * @param portName Qualified name for the target service endpoint
166 * @param type The class of object used to messages or message
167 * payloads. Implementations are required to support
168 * <code>javax.xml.transform.Source</code>, <code>javax.xml.soap.SOAPMessage</code>
169 * and <code>javax.activation.DataSource</code>, depending on
170 * the binding in use.
171 * @param mode Controls whether the created dispatch instance is message
172 * or payload oriented, i.e. whether the user will work with complete
173 * protocol messages or message payloads. E.g. when using the SOAP
174 * protocol, this parameter controls whether the user will work with
175 * SOAP messages or the contents of a SOAP body. Mode must be MESSAGE
176 * when type is SOAPMessage.
177 *
178 * @return Dispatch instance
179 * @throws WebServiceException If any error in the creation of
180 * the <code>Dispatch</code> object
181 * @see javax.xml.transform.Source
182 * @see javax.xml.soap.SOAPMessage
183 **/
184 public <T> Dispatch<T> createDispatch(QName portName,
185 Class<T> type, Mode mode) {
186 return delegate.createDispatch(portName, type, mode);
187 }
188
189 /** Creates a <code>Dispatch</code> instance for use with JAXB
190 * generated objects.
191 *
192 * @param portName Qualified name for the target service endpoint
193 * @param context The JAXB context used to marshall and unmarshall
194 * messages or message payloads.
195 * @param mode Controls whether the created dispatch instance is message
196 * or payload oriented, i.e. whether the user will work with complete
197 * protocol messages or message payloads. E.g. when using the SOAP
198 * protocol, this parameter controls whether the user will work with
199 * SOAP messages or the contents of a SOAP body.
200 *
201 * @return Dispatch instance
202 * @throws ServiceException If any error in the creation of
203 * the <code>Dispatch</code> object
204 *
205 * @see javax.xml.bind.JAXBContext
206 **/
207 public Dispatch<Object> createDispatch(QName portName,
208 JAXBContext context, Mode mode) {
209 return delegate.createDispatch(portName, context, mode);
210 }
211
212 /** Gets the name of this service.
213 * @return Qualified name of this service
214 **/
215 public QName getServiceName() {
216 return delegate.getServiceName();
217 }
218
219 /** Returns an <code>Iterator</code> for the list of
220 * <code>QName</code>s of service endpoints grouped by this
221 * service
222 *
223 * @return Returns <code>java.util.Iterator</code> with elements
224 * of type <code>javax.xml.namespace.QName</code>
225 * @throws WebServiceException If this Service class does not
226 * have access to the required WSDL metadata
227 **/
228 public Iterator<javax.xml.namespace.QName> getPorts() {
229 return delegate.getPorts();
230 }
231
232 /** Gets the location of the WSDL document for this Service.
233 *
234 * @return URL for the location of the WSDL document for
235 * this service
236 **/
237 public java.net.URL getWSDLDocumentLocation() {
238 return delegate.getWSDLDocumentLocation();
239 }
240
241 /**
242 * Returns the configured handler resolver.
243 *
244 * @return HandlerResolver The <code>HandlerResolver</code> being
245 * used by this <code>Service</code> instance, or <code>null</code>
246 * if there isn't one.
247 **/
248 public HandlerResolver getHandlerResolver() {
249 return delegate.getHandlerResolver();
250 }
251
252 /**
253 * Sets the <code>HandlerResolver</code> for this <code>Service</code>
254 * instance.
255 * <p>
256 * The handler resolver, if present, will be called once for each
257 * proxy or dispatch instance that is created, and the handler chain
258 * returned by the resolver will be set on the instance.
259 *
260 * @param handlerResolver The <code>HandlerResolver</code> to use
261 * for all subsequently created proxy/dispatch objects.
262 *
263 * @see javax.xml.ws.handler.HandlerResolver
264 **/
265 public void setHandlerResolver(HandlerResolver handlerResolver) {
266 delegate.setHandlerResolver(handlerResolver);
267 }
268
269 /**
270 * Returns the executor for this <code>Service</code>instance.
271 *
272 * The executor is used for all asynchronous invocations that
273 * require callbacks.
274 *
275 * @return The <code>java.util.concurrent.Executor</code> to be
276 * used to invoke a callback.
277 *
278 * @see java.util.concurrent.Executor
279 **/
280 public java.util.concurrent.Executor getExecutor() {
281 return delegate.getExecutor();
282 }
283
284 /**
285 * Sets the executor for this <code>Service</code> instance.
286 *
287 * The executor is used for all asynchronous invocations that
288 * require callbacks.
289 *
290 * @param executor The <code>java.util.concurrent.Executor</code>
291 * to be used to invoke a callback.
292 *
293 * @throws SecurityException If the instance does not support
294 * setting an executor for security reasons (e.g. the
295 * necessary permissions are missing).
296 *
297 * @see java.util.concurrent.Executor
298 **/
299 public void setExecutor(java.util.concurrent.Executor executor) {
300 delegate.setExecutor(executor);
301 }
302
303 /**
304 * Create a <code>Service</code> instance.
305 *
306 * The specified WSDL document location and service qualified name must
307 * uniquely identify a <code>wsdl:service</code> element.
308 *
309 * @param wsdlDocumentLocation URL for the WSDL document location
310 * for the service
311 * @param serviceName QName for the service
312 * @throws WebServiceException If any error in creation of the
313 * specified service
314 **/
315 public static Service create(java.net.URL wsdlDocumentLocation,
316 QName serviceName) {
317 return new Service(wsdlDocumentLocation, serviceName);
318 }
319
320 /**
321 * Create a <code>Service</code> instance.
322 *
323 * @param serviceName QName for the service
324 * @throws WebServiceException If any error in creation of the
325 * specified service
326 */
327 public static Service create(QName serviceName) {
328 return new Service(null, serviceName);
329 }
330 }
|