javax.xml.ws.Service Maven / Gradle / Ivy
/*
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
*
* Copyright (c) 2005-2010 Oracle and/or its affiliates. All rights reserved.
*
* The contents of this file are subject to the terms of either the GNU
* General Public License Version 2 only ("GPL") or the Common Development
* and Distribution License("CDDL") (collectively, the "License"). You
* may not use this file except in compliance with the License. You can
* obtain a copy of the License at
* https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html
* or packager/legal/LICENSE.txt. See the License for the specific
* language governing permissions and limitations under the License.
*
* When distributing the software, include this License Header Notice in each
* file and include the License file at packager/legal/LICENSE.txt.
*
* GPL Classpath Exception:
* Oracle designates this particular file as subject to the "Classpath"
* exception as provided by Oracle in the GPL Version 2 section of the License
* file that accompanied this code.
*
* Modifications:
* If applicable, add the following below the License Header, with the fields
* enclosed by brackets [] replaced by your own identifying information:
* "Portions Copyright [year] [name of copyright owner]"
*
* Contributor(s):
* If you wish your version of this file to be governed by only the CDDL or
* only the GPL Version 2, indicate your decision by adding "[Contributor]
* elects to include this software in this distribution under the [CDDL or GPL
* Version 2] license." If you don't indicate a single choice of license, a
* recipient has the option to distribute your version of this file under
* either the CDDL, the GPL Version 2 or to extend the choice of license to
* its licensees as provided above. However, if you add GPL Version 2 code
* and therefore, elected the GPL Version 2 license, then the option applies
* only if the new code is made subject to such option by the copyright
* holder.
*/
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;
/**
* Service objects provide the client view of a Web service.
* Service acts as a factory of the following:
*
* - Proxies for a target service endpoint.
* - Instances of {@link javax.xml.ws.Dispatch} for
* dynamic message-oriented invocation of a remote
* operation.
*
*
*
* The ports available on a service can be enumerated using the
* getPorts method. Alternatively, you can pass a
* service endpoint interface to the unary getPort method
* and let the runtime select a compatible port.
*
*
Handler chains for all the objects created by a Service
* can be set by means of a HandlerResolver.
*
*
An Executor 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 ThreadPoolExecutor 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());
}
protected Service(java.net.URL wsdlDocumentLocation, QName serviceName, WebServiceFeature ... features) {
delegate = Provider.provider().createServiceDelegate(wsdlDocumentLocation,
serviceName,
this.getClass(), features);
}
/**
* The getPort method returns a proxy. A service client
* uses this proxy to invoke operations on the target
* service endpoint. The serviceEndpointInterface
* specifies the service endpoint interface that is supported by
* the created dynamic proxy instance.
*
* @param portName Qualified name of the service endpoint in
* the WSDL service description.
* @param serviceEndpointInterface Service endpoint interface
* supported by the dynamic proxy instance.
* @return Object Proxy instance that
* supports the specified service endpoint
* interface.
* @throws WebServiceException This exception is thrown in the
* following cases:
*
* - If there is an error in creation of
* the proxy.
*
- If there is any missing WSDL metadata
* as required by this method.
*
- If an illegal
*
serviceEndpointInterface
* or portName is specified.
*
* @see java.lang.reflect.Proxy
* @see java.lang.reflect.InvocationHandler
**/
public T getPort(QName portName,
Class serviceEndpointInterface) {
return delegate.getPort(portName, serviceEndpointInterface);
}
/**
* The getPort method returns a proxy. A service client
* uses this proxy to invoke operations on the target
* service endpoint. The serviceEndpointInterface
* specifies the service endpoint interface that is supported by
* the created dynamic proxy instance.
*
* @param portName Qualified name of the service endpoint in
* the WSDL service description.
* @param serviceEndpointInterface Service endpoint interface
* supported by the dynamic proxy instance.
* @param features A list of WebServiceFeatures to configure on the
* proxy. Supported features not in the features
* parameter will have their default values.
* @return Object Proxy instance that
* supports the specified service endpoint
* interface.
* @throws WebServiceException This exception is thrown in the
* following cases:
*
* - If there is an error in creation of
* the proxy.
*
- If there is any missing WSDL metadata
* as required by this method.
*
- If an illegal
*
serviceEndpointInterface
* or portName is specified.
* - If a feature is enabled that is not compatible
* with this port or is unsupported.
*
* @see java.lang.reflect.Proxy
* @see java.lang.reflect.InvocationHandler
* @see WebServiceFeature
*
* @since JAX-WS 2.1
**/
public T getPort(QName portName,
Class serviceEndpointInterface, WebServiceFeature... features) {
return delegate.getPort(portName, serviceEndpointInterface, features);
}
/**
* The getPort method returns a proxy. The parameter
* serviceEndpointInterface 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
*
* - If there is an error during creation
* of the proxy.
*
- If there is any missing WSDL metadata
* as required by this method.
*
- If an illegal
*
serviceEndpointInterface
* is specified.
*
**/
public T getPort(Class serviceEndpointInterface) {
return delegate.getPort(serviceEndpointInterface);
}
/**
* The getPort method returns a proxy. The parameter
* serviceEndpointInterface 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.
* @param features A list of WebServiceFeatures to configure on the
* proxy. Supported features not in the features
* parameter will have their default values.
* @return Object instance that supports the
* specified service endpoint interface.
* @throws WebServiceException
*
* - If there is an error during creation
* of the proxy.
*
- If there is any missing WSDL metadata
* as required by this method.
*
- If an illegal
*
serviceEndpointInterface
* is specified.
* - If a feature is enabled that is not compatible
* with this port or is unsupported.
*
*
* @see WebServiceFeature
*
* @since JAX-WS 2.1
**/
public T getPort(Class serviceEndpointInterface,
WebServiceFeature... features) {
return delegate.getPort(serviceEndpointInterface, features);
}
/**
* The getPort method returns a proxy.
* The parameter endpointReference specifies the
* endpoint that will be invoked by the returned proxy. If there
* are any reference parameters in the
* endpointReference, then those reference
* parameters MUST appear as SOAP headers, indicating them to be
* reference parameters, on all messages sent to the endpoint.
* The endpointReference's address MUST be used
* for invocations on the endpoint.
* The parameter serviceEndpointInterface 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 from
* the WSDL associated with this Service instance or
* from the metadata from the endpointReference.
* If this Service instance has a WSDL and
* the endpointReference metadata
* also has a WSDL, then the WSDL from this instance MUST be used.
* If this Service instance does not have a WSDL and
* the endpointReference does have a WSDL, then the
* WSDL from the endpointReference MAY be used.
* The returned proxy should not be reconfigured by the client.
* If this Service instance has a known proxy
* port that matches the information contained in
* the WSDL,
* then that proxy is returned, otherwise a WebServiceException
* is thrown.
*
* Calling this method has the same behavior as the following
*
* port = service.getPort(portName, serviceEndpointInterface);
*
* where the portName is retrieved from the
* metadata of the endpointReference or from the
* serviceEndpointInterface and the WSDL
* associated with this Service instance.
*
* @param endpointReference The EndpointReference
* for the target service endpoint that will be invoked by the
* returned proxy.
* @param serviceEndpointInterface Service endpoint interface.
* @param features A list of WebServiceFeatures to configure on the
* proxy. Supported features not in the features
* parameter will have their default values.
* @return Object Proxy instance that supports the
* specified service endpoint interface.
* @throws WebServiceException
*
* - If there is an error during creation
* of the proxy.
*
- If there is any missing WSDL metadata
* as required by this method.
*
- If the
endpointReference metadata does
* not match the serviceName of this
* Service instance.
* - If a
portName cannot be extracted
* from the WSDL or endpointReference metadata.
* - If an invalid
*
endpointReference
* is specified.
* - If an invalid
*
serviceEndpointInterface
* is specified.
* - If a feature is enabled that is not compatible
* with this port or is unsupported.
*
*
* @since JAX-WS 2.1
**/
public T getPort(EndpointReference endpointReference,
Class serviceEndpointInterface, WebServiceFeature... features) {
return delegate.getPort(endpointReference, serviceEndpointInterface, features);
}
/**
* 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
* Dispatchinstances.
*
* @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 Dispatch instance for use with objects of
* the client's choosing.
*
* @param portName Qualified name for the target service endpoint
* @param type The class of object used for messages or message
* payloads. Implementations are required to support
* javax.xml.transform.Source, javax.xml.soap.SOAPMessage
* and javax.activation.DataSource, depending on
* the binding in use.
* @param mode Controls whether the created dispatch instance is message
* or payload oriented, i.e. whether the client will work with complete
* protocol messages or message payloads. E.g. when using the SOAP
* protocol, this parameter controls whether the client 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 Dispatch object.
*
* @see javax.xml.transform.Source
* @see javax.xml.soap.SOAPMessage
**/
public Dispatch createDispatch(QName portName, Class type, Mode mode) {
return delegate.createDispatch(portName, type, mode);
}
/**
* Creates a Dispatch instance for use with objects of
* the client's choosing.
*
* @param portName Qualified name for the target service endpoint
* @param type The class of object used for messages or message
* payloads. Implementations are required to support
* javax.xml.transform.Source and javax.xml.soap.SOAPMessage.
* @param mode Controls whether the created dispatch instance is message
* or payload oriented, i.e. whether the client will work with complete
* protocol messages or message payloads. E.g. when using the SOAP
* protocol, this parameter controls whether the client will work with
* SOAP messages or the contents of a SOAP body. Mode MUST be MESSAGE
* when type is SOAPMessage.
* @param features A list of WebServiceFeatures to configure on the
* proxy. Supported features not in the features
* parameter will have their default values.
*
* @return Dispatch instance.
* @throws WebServiceException If any error in the creation of
* the Dispatch object or if a
* feature is enabled that is not compatible with
* this port or is unsupported.
*
* @see javax.xml.transform.Source
* @see javax.xml.soap.SOAPMessage
* @see WebServiceFeature
*
* @since JAX-WS 2.1
**/
public Dispatch createDispatch(QName portName, Class type,
Service.Mode mode, WebServiceFeature... features) {
return delegate.createDispatch(portName, type, mode, features);
}
/**
* Creates a Dispatch instance for use with objects of
* the client's choosing. If there
* are any reference parameters in the
* endpointReference, then those reference
* parameters MUST appear as SOAP headers, indicating them to be
* reference parameters, on all messages sent to the endpoint.
* The endpointReference's address MUST be used
* for invocations on the endpoint.
* 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 dispatch accordingly from
* the WSDL associated with this Service instance or
* from the metadata from the endpointReference.
* If this Service instance has a WSDL and
* the endpointReference
* also has a WSDL in its metadata, then the WSDL from this instance MUST be used.
* If this Service instance does not have a WSDL and
* the endpointReference does have a WSDL, then the
* WSDL from the endpointReference MAY be used.
* An implementation MUST be able to retrieve the portName from the
* endpointReference metadata.
*
* This method behaves the same as calling
*
* dispatch = service.createDispatch(portName, type, mode, features);
*
* where the portName is retrieved from the
* WSDL or EndpointReference metadata.
*
* @param endpointReference The EndpointReference
* for the target service endpoint that will be invoked by the
* returned Dispatch object.
* @param type The class of object used to messages or message
* payloads. Implementations are required to support
* javax.xml.transform.Source and javax.xml.soap.SOAPMessage.
* @param mode Controls whether the created dispatch instance is message
* or payload oriented, i.e. whether the client will work with complete
* protocol messages or message payloads. E.g. when using the SOAP
* protocol, this parameter controls whether the client will work with
* SOAP messages or the contents of a SOAP body. Mode MUST be MESSAGE
* when type is SOAPMessage.
* @param features An array of WebServiceFeatures to configure on the
* proxy. Supported features not in the features
* parameter will have their default values.
*
* @return Dispatch instance
* @throws WebServiceException
*
* - If there is any missing WSDL metadata
* as required by this method.
*
- If the
endpointReference metadata does
* not match the serviceName or portName
* of a WSDL associated
* with this Service instance.
* - If the
portName cannot be determined
* from the EndpointReference metadata.
* - If any error in the creation of
* the
Dispatch object.
* - If a feature is enabled that is not
* compatible with this port or is unsupported.
*
*
* @see javax.xml.transform.Source
* @see javax.xml.soap.SOAPMessage
* @see WebServiceFeature
*
* @since JAX-WS 2.1
**/
public Dispatch createDispatch(EndpointReference endpointReference,
Class type, Service.Mode mode,
WebServiceFeature... features) {
return delegate.createDispatch(endpointReference, type, mode, features);
}
/**
* Creates a Dispatch 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 client will work with complete
* protocol messages or message payloads. E.g. when using the SOAP
* protocol, this parameter controls whether the client will work with
* SOAP messages or the contents of a SOAP body.
*
* @return Dispatch instance.
* @throws WebServiceException If any error in the creation of
* the Dispatch object.
*
* @see javax.xml.bind.JAXBContext
**/
public Dispatch