1 /*
2 * Copyright (c) 2005, 2015, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package javax.xml.ws.spi;
27
28 import java.net.URL;
29 import java.util.List;
30 import java.util.Iterator;
31 import java.util.Map;
32 import java.util.ServiceLoader;
33 import javax.xml.namespace.QName;
34 import javax.xml.ws.*;
35 import javax.xml.ws.wsaddressing.W3CEndpointReference;
36
37 import org.w3c.dom.Element;
38
39 /**
40 * Service provider for {@code ServiceDelegate} and
41 * {@code Endpoint} objects.
42 *
43 * @since 1.6, JAX-WS 2.0
44 */
45 public abstract class Provider {
46
47 /**
48 * A constant representing the name of the default
49 * {@code Provider} implementation class.
50 **/
51 // Using two strings so that package renaming doesn't change it
52 private static final String DEFAULT_JAXWSPROVIDER =
60
61 /**
62 *
63 * Creates a new provider object.
64 * <p>
65 * The algorithm used to locate the provider subclass to use consists
66 * of the following steps:
67 * <ul>
68 * <li> Use the service-provider loading facilities, defined by the {@link java.util.ServiceLoader} class,
69 * to attempt to locate and load an implementation of {@link javax.xml.ws.spi.Provider} service using
70 * the {@linkplain java.util.ServiceLoader#load(java.lang.Class) default loading mechanism}.
71 * <li>Use the configuration file "jaxws.properties". The file is in standard
72 * {@link java.util.Properties} format and typically located in the
73 * {@code conf} directory of the Java installation. It contains the fully qualified
74 * name of the implementation class with the key {@code javax.xml.ws.spi.Provider}.
75 * <li> If a system property with the name {@code javax.xml.ws.spi.Provider}
76 * is defined, then its value is used as the name of the implementation class.
77 * <li> Finally, a platform default implementation is used.
78 * </ul>
79 *
80 */
81 public static Provider provider() {
82 try {
83 return FactoryFinder.find(Provider.class, DEFAULT_JAXWSPROVIDER);
84 } catch (WebServiceException ex) {
85 throw ex;
86 } catch (Exception ex) {
87 throw new WebServiceException("Unable to createEndpointReference Provider", ex);
88 }
89 }
90
91 /**
92 * Creates a service delegate object.
93 *
94 * @param wsdlDocumentLocation A URL pointing to the WSDL document
95 * for the service, or {@code null} if there isn't one.
96 * @param serviceName The qualified name of the service.
97 * @param serviceClass The service class, which MUST be either
98 * {@code javax.xml.ws.Service} or a subclass thereof.
99 * @return The newly created service delegate.
106 * Creates a service delegate object.
107 *
108 * @param wsdlDocumentLocation A URL pointing to the WSDL document
109 * for the service, or {@code null} if there isn't one.
110 * @param serviceName The qualified name of the service.
111 * @param serviceClass The service class, which MUST be either
112 * {@code javax.xml.ws.Service} or a subclass thereof.
113 * @param features Web Service features that must be configured on
114 * the service. If the provider doesn't understand a feature,
115 * it must throw a WebServiceException.
116 * @return The newly created service delegate.
117 *
118 * @since 1.7, JAX-WS 2.2
119 */
120 public ServiceDelegate createServiceDelegate(
121 java.net.URL wsdlDocumentLocation,
122 QName serviceName, Class<? extends Service> serviceClass, WebServiceFeature ... features) {
123 throw new UnsupportedOperationException("JAX-WS 2.2 implementation must override this default behaviour.");
124 }
125
126
127 /**
128 *
129 * Creates an endpoint object with the provided binding and implementation
130 * object.
131 *
132 * @param bindingId A URI specifying the desired binding (e.g. SOAP/HTTP)
133 * @param implementor A service implementation object to which
134 * incoming requests will be dispatched. The corresponding
135 * class MUST be annotated with all the necessary Web service
136 * annotations.
137 * @return The newly created endpoint.
138 */
139 public abstract Endpoint createEndpoint(String bindingId,
140 Object implementor);
141
142
143 /**
144 * Creates and publishes an endpoint object with the specified
145 * address and implementation object.
146 *
147 * @param address A URI specifying the address and transport/protocol
148 * to use. A http: URI MUST result in the SOAP 1.1/HTTP
149 * binding being used. Implementations may support other
150 * URI schemes.
151 * @param implementor A service implementation object to which
152 * incoming requests will be dispatched. The corresponding
153 * class MUST be annotated with all the necessary Web service
154 * annotations.
155 * @return The newly created endpoint.
156 */
157 public abstract Endpoint createAndPublishEndpoint(String address,
158 Object implementor);
159
160 /**
161 * read an EndpointReference from the infoset contained in
162 * {@code eprInfoset}.
182 * are any reference parameters in the
183 * {@code endpointReference}, then those reference
184 * parameters MUST appear as SOAP headers, indicating them to be
185 * reference parameters, on all messages sent to the endpoint.
186 * The parameter {@code serviceEndpointInterface} specifies
187 * the service endpoint interface that is supported by the
188 * returned proxy.
189 * The parameter {@code endpointReference} specifies the
190 * endpoint that will be invoked by the returned proxy.
191 * In the implementation of this method, the JAX-WS
192 * runtime system takes the responsibility of selecting a protocol
193 * binding (and a port) and configuring the proxy accordingly from
194 * the WSDL metadata of the
195 * {@code serviceEndpointInterface} and the {@code EndpointReference}.
196 * For this method
197 * to successfully return a proxy, WSDL metadata MUST be available and the
198 * {@code endpointReference} MUST contain an implementation understood
199 * {@code serviceName} metadata.
200 *
201 *
202 * @param endpointReference the EndpointReference that will
203 * be invoked by the returned proxy.
204 * @param serviceEndpointInterface Service endpoint interface
205 * @param features A list of WebServiceFeatures to configure on the
206 * proxy. Supported features not in the {@code features
207 * } parameter will have their default values.
208 * @return Object Proxy instance that supports the
209 * specified service endpoint interface
210 * @throws WebServiceException
211 * <UL>
212 * <LI>If there is an error during creation
213 * of the proxy
214 * <LI>If there is any missing WSDL metadata
215 * as required by this method}
216 * <LI>If this
217 * {@code endpointReference}
218 * is illegal
219 * <LI>If an illegal
220 * {@code serviceEndpointInterface}
221 * is specified
|
1 /*
2 * Copyright (c) 2005, 2017, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package javax.xml.ws.spi;
27
28 import java.util.List;
29 import java.util.Map;
30 import javax.xml.namespace.QName;
31 import javax.xml.ws.*;
32 import javax.xml.ws.wsaddressing.W3CEndpointReference;
33
34 import org.w3c.dom.Element;
35
36 /**
37 * Service provider for {@code ServiceDelegate} and
38 * {@code Endpoint} objects.
39 *
40 * @since 1.6, JAX-WS 2.0
41 */
42 public abstract class Provider {
43
44 /**
45 * A constant representing the name of the default
46 * {@code Provider} implementation class.
47 **/
48 // Using two strings so that package renaming doesn't change it
49 private static final String DEFAULT_JAXWSPROVIDER =
57
58 /**
59 *
60 * Creates a new provider object.
61 * <p>
62 * The algorithm used to locate the provider subclass to use consists
63 * of the following steps:
64 * <ul>
65 * <li> Use the service-provider loading facilities, defined by the {@link java.util.ServiceLoader} class,
66 * to attempt to locate and load an implementation of {@link javax.xml.ws.spi.Provider} service using
67 * the {@linkplain java.util.ServiceLoader#load(java.lang.Class) default loading mechanism}.
68 * <li>Use the configuration file "jaxws.properties". The file is in standard
69 * {@link java.util.Properties} format and typically located in the
70 * {@code conf} directory of the Java installation. It contains the fully qualified
71 * name of the implementation class with the key {@code javax.xml.ws.spi.Provider}.
72 * <li> If a system property with the name {@code javax.xml.ws.spi.Provider}
73 * is defined, then its value is used as the name of the implementation class.
74 * <li> Finally, a platform default implementation is used.
75 * </ul>
76 *
77 * @return provider object
78 */
79 public static Provider provider() {
80 try {
81 return FactoryFinder.find(Provider.class, DEFAULT_JAXWSPROVIDER);
82 } catch (WebServiceException ex) {
83 throw ex;
84 } catch (Exception ex) {
85 throw new WebServiceException("Unable to createEndpointReference Provider", ex);
86 }
87 }
88
89 /**
90 * Creates a service delegate object.
91 *
92 * @param wsdlDocumentLocation A URL pointing to the WSDL document
93 * for the service, or {@code null} if there isn't one.
94 * @param serviceName The qualified name of the service.
95 * @param serviceClass The service class, which MUST be either
96 * {@code javax.xml.ws.Service} or a subclass thereof.
97 * @return The newly created service delegate.
104 * Creates a service delegate object.
105 *
106 * @param wsdlDocumentLocation A URL pointing to the WSDL document
107 * for the service, or {@code null} if there isn't one.
108 * @param serviceName The qualified name of the service.
109 * @param serviceClass The service class, which MUST be either
110 * {@code javax.xml.ws.Service} or a subclass thereof.
111 * @param features Web Service features that must be configured on
112 * the service. If the provider doesn't understand a feature,
113 * it must throw a WebServiceException.
114 * @return The newly created service delegate.
115 *
116 * @since 1.7, JAX-WS 2.2
117 */
118 public ServiceDelegate createServiceDelegate(
119 java.net.URL wsdlDocumentLocation,
120 QName serviceName, Class<? extends Service> serviceClass, WebServiceFeature ... features) {
121 throw new UnsupportedOperationException("JAX-WS 2.2 implementation must override this default behaviour.");
122 }
123
124 /**
125 *
126 * Creates an endpoint object with the provided binding and implementation
127 * object.
128 *
129 * @param bindingId A URI specifying the desired binding (e.g. SOAP/HTTP)
130 * @param implementor A service implementation object to which
131 * incoming requests will be dispatched. The corresponding
132 * class MUST be annotated with all the necessary Web service
133 * annotations.
134 * @return The newly created endpoint.
135 */
136 public abstract Endpoint createEndpoint(String bindingId,
137 Object implementor);
138
139 /**
140 * Creates and publishes an endpoint object with the specified
141 * address and implementation object.
142 *
143 * @param address A URI specifying the address and transport/protocol
144 * to use. A http: URI MUST result in the SOAP 1.1/HTTP
145 * binding being used. Implementations may support other
146 * URI schemes.
147 * @param implementor A service implementation object to which
148 * incoming requests will be dispatched. The corresponding
149 * class MUST be annotated with all the necessary Web service
150 * annotations.
151 * @return The newly created endpoint.
152 */
153 public abstract Endpoint createAndPublishEndpoint(String address,
154 Object implementor);
155
156 /**
157 * read an EndpointReference from the infoset contained in
158 * {@code eprInfoset}.
178 * are any reference parameters in the
179 * {@code endpointReference}, then those reference
180 * parameters MUST appear as SOAP headers, indicating them to be
181 * reference parameters, on all messages sent to the endpoint.
182 * The parameter {@code serviceEndpointInterface} specifies
183 * the service endpoint interface that is supported by the
184 * returned proxy.
185 * The parameter {@code endpointReference} specifies the
186 * endpoint that will be invoked by the returned proxy.
187 * In the implementation of this method, the JAX-WS
188 * runtime system takes the responsibility of selecting a protocol
189 * binding (and a port) and configuring the proxy accordingly from
190 * the WSDL metadata of the
191 * {@code serviceEndpointInterface} and the {@code EndpointReference}.
192 * For this method
193 * to successfully return a proxy, WSDL metadata MUST be available and the
194 * {@code endpointReference} MUST contain an implementation understood
195 * {@code serviceName} metadata.
196 *
197 *
198 * @param <T> Service endpoint interface
199 * @param endpointReference the EndpointReference that will
200 * be invoked by the returned proxy.
201 * @param serviceEndpointInterface Service endpoint interface
202 * @param features A list of WebServiceFeatures to configure on the
203 * proxy. Supported features not in the {@code features
204 * } parameter will have their default values.
205 * @return Object Proxy instance that supports the
206 * specified service endpoint interface
207 * @throws WebServiceException
208 * <UL>
209 * <LI>If there is an error during creation
210 * of the proxy
211 * <LI>If there is any missing WSDL metadata
212 * as required by this method}
213 * <LI>If this
214 * {@code endpointReference}
215 * is illegal
216 * <LI>If an illegal
217 * {@code serviceEndpointInterface}
218 * is specified
|