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.spi;
027
028 import java.util.Iterator;
029 import javax.xml.namespace.QName;
030 import javax.xml.ws.Dispatch;
031 import javax.xml.ws.Service;
032 import javax.xml.ws.handler.HandlerResolver;
033 import javax.xml.bind.JAXBContext;
034
035 /**
036 * Service delegates are used internally by <code>Service</code> objects
037 * to allow pluggability of JAX-WS implementations.
038 * <p>
039 * Every <code>Service</code> object has its own delegate, created using
040 * the javax.xml.ws.Provider#createServiceDelegate method. A <code>Service</code>
041 * object delegates all of its instance methods to its delegate.
042 *
043 * @see javax.xml.ws.Service
044 * @see javax.xml.ws.spi.Provider
045 *
046 * @since JAX-WS 2.0
047 */
048 public abstract class ServiceDelegate {
049
050 protected ServiceDelegate() {
051 }
052
053 /** The getPort method returns a stub. A service client
054 * uses this stub to invoke operations on the target
055 * service endpoint. The <code>serviceEndpointInterface</code>
056 * specifies the service endpoint interface that is supported by
057 * the created dynamic proxy or stub instance.
058 *
059 * @param portName Qualified name of the service endpoint in
060 * the WSDL service description
061 * @param serviceEndpointInterface Service endpoint interface
062 * supported by the dynamic proxy or stub
063 * instance
064 * @return Object Proxy instance that
065 * supports the specified service endpoint
066 * interface
067 * @throws WebServiceException This exception is thrown in the
068 * following cases:
069 * <UL>
070 * <LI>If there is an error in creation of
071 * the proxy
072 * <LI>If there is any missing WSDL metadata
073 * as required by this method
074 * <LI>Optionally, if an illegal
075 * <code>serviceEndpointInterface</code>
076 * or <code>portName</code> is specified
077 * </UL>
078 * @see java.lang.reflect.Proxy
079 * @see java.lang.reflect.InvocationHandler
080 **/
081
082 public abstract <T> T getPort(QName portName,
083 Class<T> serviceEndpointInterface);
084
085 /** The getPort method returns a stub. The parameter
086 * <code>serviceEndpointInterface</code> specifies the service
087 * endpoint interface that is supported by the returned proxy.
088 * In the implementation of this method, the JAX-WS
089 * runtime system takes the responsibility of selecting a protocol
090 * binding (and a port) and configuring the proxy accordingly.
091 * The returned proxy should not be reconfigured by the client.
092 *
093 * @param serviceEndpointInterface Service endpoint interface
094 * @return Object instance that supports the
095 * specified service endpoint interface
096 * @throws WebServiceException
097 * <UL>
098 * <LI>If there is an error during creation
099 * of the proxy
100 * <LI>If there is any missing WSDL metadata
101 * as required by this method
102 * <LI>Optionally, if an illegal
103 * <code>serviceEndpointInterface</code>
104 * is specified
105 * </UL>
106 **/
107 public abstract <T> T getPort(Class<T> serviceEndpointInterface);
108
109 /** Creates a new port for the service. Ports created in this way contain
110 * no WSDL port type information and can only be used for creating
111 * <code>Dispatch</code>instances.
112 *
113 * @param portName Qualified name for the target service endpoint
114 * @param bindingId A URI identifier of a binding.
115 * @param endpointAddress Address of the target service endpoint as a URI
116 * @throws WebServiceException If any error in the creation of
117 * the port
118 *
119 * @see javax.xml.ws.soap.SOAPBinding#SOAP11HTTP_BINDING
120 * @see javax.xml.ws.soap.SOAPBinding#SOAP12HTTP_BINDING
121 * @see javax.xml.ws.http.HTTPBinding#HTTP_BINDING
122 **/
123 public abstract void addPort(QName portName, String bindingId,
124 String endpointAddress);
125
126 /** Creates a <code>Dispatch</code> instance for use with objects of
127 * the users choosing.
128 *
129 * @param portName Qualified name for the target service endpoint
130 * @param type The class of object used to messages or message
131 * payloads. Implementations are required to support
132 * javax.xml.transform.Source and javax.xml.soap.SOAPMessage.
133 * @param mode Controls whether the created dispatch instance is message
134 * or payload oriented, i.e. whether the user will work with complete
135 * protocol messages or message payloads. E.g. when using the SOAP
136 * protocol, this parameter controls whether the user will work with
137 * SOAP messages or the contents of a SOAP body. Mode must be MESSAGE
138 * when type is SOAPMessage.
139 *
140 * @return Dispatch instance
141 * @throws WebServiceException If any error in the creation of
142 * the <code>Dispatch</code> object
143 * @see javax.xml.transform.Source
144 * @see javax.xml.soap.SOAPMessage
145 **/
146 public abstract <T> Dispatch<T> createDispatch(QName portName,
147 Class<T> type, Service.Mode mode);
148
149 /** Creates a <code>Dispatch</code> instance for use with JAXB
150 * generated objects.
151 *
152 * @param portName Qualified name for the target service endpoint
153 * @param context The JAXB context used to marshall and unmarshall
154 * messages or message payloads.
155 * @param mode Controls whether the created dispatch instance is message
156 * or payload oriented, i.e. whether the user will work with complete
157 * protocol messages or message payloads. E.g. when using the SOAP
158 * protocol, this parameter controls whether the user will work with
159 * SOAP messages or the contents of a SOAP body.
160 *
161 * @return Dispatch instance
162 * @throws ServiceException If any error in the creation of
163 * the <code>Dispatch</code> object
164 *
165 * @see javax.xml.bind.JAXBContext
166 **/
167 public abstract Dispatch<Object> createDispatch(QName portName,
168 JAXBContext context, Service.Mode mode);
169
170 /** Gets the name of this service.
171 * @return Qualified name of this service
172 **/
173 public abstract QName getServiceName();
174
175 /** Returns an <code>Iterator</code> for the list of
176 * <code>QName</code>s of service endpoints grouped by this
177 * service
178 *
179 * @return Returns <code>java.util.Iterator</code> with elements
180 * of type <code>javax.xml.namespace.QName</code>
181 * @throws WebServiceException If this Service class does not
182 * have access to the required WSDL metadata
183 **/
184 public abstract Iterator<javax.xml.namespace.QName> getPorts();
185
186 /** Gets the location of the WSDL document for this Service.
187 *
188 * @return URL for the location of the WSDL document for
189 * this service
190 **/
191 public abstract java.net.URL getWSDLDocumentLocation();
192
193 /**
194 * Returns the configured handler resolver.
195 *
196 * @return HandlerResolver The <code>HandlerResolver</code> being
197 * used by this <code>Service</code> instance, or <code>null</code>
198 * if there isn't one.
199 **/
200 public abstract HandlerResolver getHandlerResolver();
201
202 /**
203 * Sets the <code>HandlerResolver</code> for this <code>Service</code>
204 * instance.
205 * <p>
206 * The handler resolver, if present, will be called once for each
207 * proxy or dispatch instance that is created, and the handler chain
208 * returned by the resolver will be set on the instance.
209 *
210 * @param handlerResolver The <code>HandlerResolver</code> to use
211 * for all subsequently created proxy/dispatch objects.
212 *
213 * @see javax.xml.ws.handler.HandlerResolver
214 **/
215 public abstract void setHandlerResolver(
216 HandlerResolver handlerResolver);
217
218 /**
219 * Returns the executor for this <code>Service</code>instance.
220 *
221 * The executor is used for all asynchronous invocations that
222 * require callbacks.
223 *
224 * @return The <code>java.util.concurrent.Executor</code> to be
225 * used to invoke a callback.
226 *
227 * @see java.util.concurrent.Executor
228 **/
229 public abstract java.util.concurrent.Executor getExecutor();
230
231 /**
232 * Sets the executor for this <code>Service</code> instance.
233 *
234 * The executor is used for all asynchronous invocations that
235 * require callbacks.
236 *
237 * @param executor The <code>java.util.concurrent.Executor</code>
238 * to be used to invoke a callback.
239 *
240 * @throws SecurityException If the instance does not support
241 * setting an executor for security reasons (e.g. the
242 * necessary permissions are missing).
243 *
244 * @see java.util.concurrent.Executor
245 **/
246 public abstract void setExecutor(
247 java.util.concurrent.Executor executor);
248
249 }
|