org.apache.axis.client

Class Service

public class Service extends Object implements Service, Serializable, Referenceable

Axis' JAXRPC Dynamic Invoation Interface implementation of the Service interface. The Service class should be used a the starting point for access SOAP Web Services. Typically, a Service will be created with a WSDL document and along with a serviceName you can then ask for a Call object that will allow you to invoke a Web Service.

Author: Doug Davis (dug@us.ibm.com)

Nested Class Summary
protected static class	Service.HandlerRegistryImpl

Field Summary
protected Call	_call

Constructor Summary
	Service() Constructs a new Service object - this assumes the caller will set the appropriate fields by hand rather than getting them from the WSDL.
	Service(QName serviceName) Constructs a new Service object - this assumes the caller will set the appropriate fields by hand rather than getting them from the WSDL.
	Service(EngineConfiguration engineConfiguration, AxisClient axisClient) Constructs a Service using the supplied configuration and engine directly.
	Service(EngineConfiguration config) Constructs a new Service object as above, but also passing in the EngineConfiguration which should be used to set up the AxisClient.
	Service(URL wsdlDoc, QName serviceName) Constructs a new Service object for the service in the WSDL document pointed to by the wsdlDoc URL and serviceName parameters.
	Service(Parser parser, QName serviceName) Constructs a new Service object for the service in the WSDL document
	Service(String wsdlLocation, QName serviceName) Constructs a new Service object for the service in the WSDL document pointed to by the wsdlLocation and serviceName parameters.
	Service(InputStream wsdlInputStream, QName serviceName) Constructs a new Service object for the service in the WSDL document in the wsdlInputStream and serviceName parameters.

Method Summary
Call	createCall(QName portName) Creates a new Call object - will prefill as much info from the WSDL as it can.
Call	createCall(QName portName, String operationName) Creates a new Call object - will prefill as much info from the WSDL as it can.
Call	createCall(QName portName, QName operationName) Creates a new Call object - will prefill as much info from the WSDL as it can.
Call	createCall() Creates a new Call object with no prefilled data.
protected AxisClient	getAxisClient()
boolean	getCacheWSDL() Tells whether or not we're caching WSDL
Call	getCall() Returns last Call object associated with this service.
Call[]	getCalls(QName portName) Gets an array of preconfigured Call objects for invoking operations on the specified port.
AxisEngine	getEngine() Returns the current AxisEngine used by this Service and all of the Call objects created from this Service object.
protected EngineConfiguration	getEngineConfiguration() Constructs a EngineConfig if one is not available.
HandlerRegistry	getHandlerRegistry() Returns the configured HandlerRegistry instance for this Service instance.
boolean	getMaintainSession() If true, this service wants to track sessions.
Remote	getPort(QName portName, Class proxyInterface) Return either an instance of a generated stub, if it can be found, or a dynamic proxy for the given proxy interface.
Remote	getPort(Class proxyInterface) Return a dynamic proxy for the given proxy interface.
Remote	getPort(String endpoint, Class proxyInterface) Return an object which acts as a dynamic proxy for the passed interface class.
Iterator	getPorts() Returns an `Iterator` for the list of `QName`s of service endpoints grouped by this service
Reference	getReference() Returns a reference to this object.
QName	getServiceName() Returns the qualified name of the service (if one is set).
TypeMappingRegistry	getTypeMappingRegistry() Returns the current TypeMappingRegistry or null.
URL	getWSDLDocumentLocation() Returns the location of the WSDL document used to prefill the data (if one was used at all).
Parser	getWSDLParser()
protected Service	getWSDLService()
void	setCacheWSDL(boolean flag) Allows users to turn caching of WSDL documents on or off.
void	setEngine(AxisEngine engine) Sets this Service's AxisEngine.
void	setEngineConfiguration(EngineConfiguration config) Set this Service's engine configuration.
void	setMaintainSession(boolean yesno) Determine whether we'd like to track sessions or not.
void	setTypeMappingRegistry(TypeMappingRegistry registry) Defines the current Type Mappig Registry.
void	setTypeMappingVersion(String version) Set the typemapping version

Field Detail

_call

protected Call _call

Constructor Detail

Service

public Service()

Constructs a new Service object - this assumes the caller will set the appropriate fields by hand rather than getting them from the WSDL.

Service

public Service(QName serviceName)

Constructs a new Service object - this assumes the caller will set the appropriate fields by hand rather than getting them from the WSDL.

Service

public Service(EngineConfiguration engineConfiguration, AxisClient axisClient)

Constructs a Service using the supplied configuration and engine directly.

Parameters: engineConfiguration axisClient

Service

public Service(EngineConfiguration config)

Constructs a new Service object as above, but also passing in the EngineConfiguration which should be used to set up the AxisClient.

Service

public Service(URL wsdlDoc, QName serviceName)

Constructs a new Service object for the service in the WSDL document pointed to by the wsdlDoc URL and serviceName parameters.

Parameters: wsdlDoc URL of the WSDL document serviceName Qualified name of the desired service

Throws: ServiceException If there's an error finding or parsing the WSDL

Service

public Service(Parser parser, QName serviceName)

Constructs a new Service object for the service in the WSDL document

Parameters: parser Parser for this service serviceName Qualified name of the desired service

Throws: ServiceException If there's an error

Service

public Service(String wsdlLocation, QName serviceName)

Constructs a new Service object for the service in the WSDL document pointed to by the wsdlLocation and serviceName parameters. This is just like the previous constructor but instead of URL the wsdlLocation parameter points to a file on the filesystem relative to the current directory.

Parameters: wsdlLocation Location of the WSDL relative to the current dir serviceName Qualified name of the desired service

Throws: ServiceException If there's an error finding or parsing the WSDL

Service

public Service(InputStream wsdlInputStream, QName serviceName)

Constructs a new Service object for the service in the WSDL document in the wsdlInputStream and serviceName parameters. This is just like the previous constructor but instead of reading the WSDL from a file (or from a URL) it is in the passed in InputStream.

Parameters: wsdlInputStream InputStream containing the WSDL serviceName Qualified name of the desired service

Throws: ServiceException If there's an error finding or parsing the WSDL

Method Detail

createCall

public Call createCall(QName portName)

Creates a new Call object - will prefill as much info from the WSDL as it can. Right now it's just the target URL of the Web Service.

Parameters: portName PortName in the WSDL doc to search for

Returns: Call Used for invoking the Web Service

Throws: ServiceException If there's an error

createCall

public Call createCall(QName portName, String operationName)

Creates a new Call object - will prefill as much info from the WSDL as it can. Right now it's target URL, SOAPAction, Parameter types, and return type of the Web Service.

Parameters: portName PortName in the WSDL doc to search for operationName Operation(method) that's going to be invoked

Returns: Call Used for invoking the Web Service

Throws: ServiceException If there's an error

createCall

public Call createCall(QName portName, QName operationName)

Creates a new Call object - will prefill as much info from the WSDL as it can. Right now it's target URL, SOAPAction, Parameter types, and return type of the Web Service.

Parameters: portName PortName in the WSDL doc to search for operationName Operation(method) that's going to be invoked

Returns: Call Used for invoking the Web Service

Throws: ServiceException If there's an error

createCall

public Call createCall()

Creates a new Call object with no prefilled data. This assumes that the caller will set everything manually - no checking of any kind will be done against the WSDL.

Returns: Call Used for invoking the Web Service

Throws: ServiceException If there's an error

getAxisClient

protected AxisClient getAxisClient()

getCacheWSDL

public boolean getCacheWSDL()

Tells whether or not we're caching WSDL

getCall

public Call getCall()

Deprecated: please use Stub._getCall

Returns last Call object associated with this service. Note that since the Service is not thread-safe, you may not get the last call object that you created on this thread. please use Stub._getCall

getCalls

public Call[] getCalls(QName portName)

Gets an array of preconfigured Call objects for invoking operations on the specified port. There is one Call object per operation that can be invoked on the specified port. Each Call object is pre-configured and does not need to be configured using the setter methods on Call interface. This method requires the Service implementation class to have access to the WSDL related metadata.

Throws: ServiceException - If this Service class does not have access to the required WSDL metadata or if an illegal portName is specified.

getEngine

public AxisEngine getEngine()

Returns the current AxisEngine used by this Service and all of the Call objects created from this Service object. Note: Not part of the JAX-RPC spec.

Returns: AxisEngine the engine

getEngineConfiguration

protected EngineConfiguration getEngineConfiguration()

Constructs a EngineConfig if one is not available.

getHandlerRegistry

public HandlerRegistry getHandlerRegistry()

Returns the configured HandlerRegistry instance for this Service instance. NOTE: This Service currently does not support the configuration of a HandlerRegistry! It will throw a java.lang.UnsupportedOperationException.

Returns: HandlerRegistry

Throws: java.lang.UnsupportedOperationException - if the Service class does not support the configuration of a HandlerRegistry.

getMaintainSession

public boolean getMaintainSession()

If true, this service wants to track sessions.

getPort

public Remote getPort(QName portName, Class proxyInterface)

Return either an instance of a generated stub, if it can be found, or a dynamic proxy for the given proxy interface.

Parameters: portName The name of the service port proxyInterface The Remote object returned by this method will also implement the given proxyInterface

Returns: java.rmi.Remote The stub implementation.

Throws: ServiceException If there's an error

getPort

public Remote getPort(Class proxyInterface)

Return a dynamic proxy for the given proxy interface.

Parameters: proxyInterface The Remote object returned by this method will also implement the given proxyInterface

Returns: java.rmi.Remote The stub implementation

Throws: ServiceException If there's an error

getPort

public Remote getPort(String endpoint, Class proxyInterface)

Return an object which acts as a dynamic proxy for the passed interface class. This is a more "dynamic" version in that it doesn't actually require WSDL, simply an endpoint address. Note: Not part of the JAX-RPC spec.

Parameters: endpoint the URL which will be used as the SOAP endpoint proxyInterface the interface class which we wish to mimic via a dynamic proxy

Throws: ServiceException

getPorts

public Iterator getPorts()

Returns an Iterator for the list of QNames of service endpoints grouped by this service

Returns: Returns java.util.Iterator with elements of type javax.xml.namespace.QName

Throws: ServiceException If this Service class does not have access to the required WSDL metadata

getReference

public Reference getReference()

Returns a reference to this object.

Returns: Reference ...

getServiceName

public QName getServiceName()

Returns the qualified name of the service (if one is set).

Returns: QName Fully qualified name of this service.

getTypeMappingRegistry

public TypeMappingRegistry getTypeMappingRegistry()

Returns the current TypeMappingRegistry or null.

Returns: TypeMappingRegistry The registry

getWSDLDocumentLocation

public URL getWSDLDocumentLocation()

Returns the location of the WSDL document used to prefill the data (if one was used at all).

Returns: URL URL pointing to the WSDL doc

getWSDLParser

public Parser getWSDLParser()

getWSDLService

protected Service getWSDLService()

setCacheWSDL

public void setCacheWSDL(boolean flag)

Allows users to turn caching of WSDL documents on or off. Default is 'true' (on).

setEngine

public void setEngine(AxisEngine engine)

Sets this Service's AxisEngine. This engine will be shared by all Call objects created from this Service object. Note: Not part of the JAX-RPC spec.

Parameters: engine Sets this Service's AxisEngine to the passed in one

setEngineConfiguration

public void setEngineConfiguration(EngineConfiguration config)

Set this Service's engine configuration. Note that since all of the constructors create the AxisClient right now, this is basically a no-op. Putting it in now so that we can make lazy engine instantiation work, and not have to duplicate every single Service constructor with a EngineConfiguration argument.

If you need to use a non-default EngineConfiguration, do the following before calling the Service constructor:

AxisProperties.setProperty(EngineConfigurationFactory.SYSTEM_PROPERTY_NAME, "classname.of.new.EngineConfigurationFactory");

Where the second parameter is the name of your new class that implements EngineConfigurationFactory and apublic static EngineConfigurationFactory newFactory(Object param) method. See EngineConfigurationFactoryDefault for an example of how to do this.

This way, when the Service class constructor calls
EngineConfigurationFactoryFinder.newFactory().getClientEngineConfig() the getClientEngineConfig() of your own EngineConfigurationFactory will be called, and your configuration will be used in the constructed Service object.

Another way is to use the "discovery" method of EngineConfigurationFactoryFinder.

Parameters: config the EngineConfiguration we want to use.

setMaintainSession

public void setMaintainSession(boolean yesno)

Determine whether we'd like to track sessions or not. This information is passed to all Call objects created from this service. Calling setMaintainSession will only affect future instantiations of the Call object, not those that already exist. Note: Not part of JAX-RPC specification.

Parameters: yesno true if session state is desired, false if not.

setTypeMappingRegistry

public void setTypeMappingRegistry(TypeMappingRegistry registry)

Defines the current Type Mappig Registry.

Parameters: registry The TypeMappingRegistry

Throws: ServiceException if there's an error

setTypeMappingVersion

public void setTypeMappingVersion(String version)

Set the typemapping version

Parameters: version