com.nsftools.jurst

Class WsdlSoapWrapper

Known Direct Subclasses:
SoapHelper

public class WsdlSoapWrapper
extends java.lang.Object

The WsdlSoapWrapper class provides a simple way to call a web service using Apache SOAP and WSDL4J, without necessarily having to read the WSDL file yourself and figure out what the methods and namespaces and parameters should be.

Okay, you'll have to have a little knowledge of the contents of the WSDL file in many cases, but it's a lot easier than making all the calls from scratch.

Here's an example of actually calling a web service:

 WsdlSoapWrapper wsw = new WsdlSoapWrapper("http://localhost/EchoService?WSDL");
 Vector params = new Vector();
 String p1 = "Hello";
 params.add(new Parameter("ParamName", p1.getClass(), p1, null));
 Response resp = callMethod("testMethod", params);
 if (!resp.generatedFault()) {
 	Parameter result = resp.getReturnValue();
 }
 

If you need to pass or return a complex data type, you can use addComplexDatatype to register a Class to handle the type like this:

 WsdlSoapWrapper wsw = new WsdlSoapWrapper("http://localhost/EchoService?WSDL");
 wsw.addComplexDatatype("BookInfo", BookInfo.class);
 

See the comments in the SoapHelper class (which is a subclass of WsdlSoapWrapper) for more examples. In fact, in most cases you can make your SOAP calls with callSimpleMethod in SoapWrapper much more easily than using callMethod here.

Other items of note:

Version:
0.9.2

Author:
Julian Robichaux

Constructor Summary

WsdlSoapWrapper(String wsdlURI)
Create a new WsdlSoapWrapper object that will reference a WSDL file at the given location (can be an http:// or a file:/// path)

Method Summary

void
addComplexDatatype(String datatypeName, Class datatypeClass)
Same as addComplexDatatype(namespace, datatypeName, datatypeClass), only the namespace is determined by searching through the types that are returned by the getTypes method.
void
addComplexDatatype(String namespace, String datatypeName, Class datatypeClass)
Add a complex data type to the SOAPMappingRegistry for any calls you make with this SoapHelper.
void
addReturnDatatype(String datatypeName, Deserializer deserializer)
Add a data type to the SOAPMappingRegistry for values that are returned by calls you make with this SoapHelper.
void
addReturnDatatype(String datatypeName, String namespace, Deserializer deserializer)
This version of the addReturnDatatype method allows you to specify a particular namespace.
Response
callMethod(String methodName, Vector params)
Call the method with the given name, using the list of parameters that are passed, and return the Response object that is generated.
Response
callMethod(MethodInfo mi, Vector params)
Same as callMethod(methodName, params), except you pass a MethodInfo object instead of a method name.
void
debugPrint(Object obj)
If a debugStream has been set (by default it's null), try to print debug information to the Stream.
Vector
getAllMethods(String wsdlURI)
For the WSDL file at the given location, return a Vector containing a MethodInfo object for each method in the WSDL file.
PrintStream
getDebugOut()
Returns the PrintStream that we're sending debug output to, if any (this is null by default).
String
getLastXmlResponse()
Get the last response that was received via callMethod as an XML String, if possible.
MethodInfo
getMethod(String methodName)
Look for a method with the given methodName in the given WSDL file, and return a MethodInfo object with information about it.
MethodInfo
getMethod(String methodName, boolean caseSensitive)
Look for a method with the given methodName in the given WSDL file, and return a MethodInfo object with information about it.
String
getMethodInputNamespace(BindingOperation bindOp)
Given a BindingOperation in a WSDL file, try to get the namespace that is specified for the input message, if one has been specified.
Vector
getMethodList()
Returns a Vector of MethodInfo objects, one for each method in the WSDL file that was given when this object was instantiated.
String
getMethodSoapAction(BindingOperation bindOp)
Given a BindingOperation in a WSDL file, try to get the SOAP Action that is specified for that operation, if one has been specified.
String
getNamespaceForType(String typeName, boolean caseSensitive)
Attempt to find and return the namespace used by the given complex data type.
String
getPortSoapURL(Port port)
For a given Port specification in a WSDL file, return the URL that should be used to make calls to this Port.
String
getRawSOAPMessage(Call call)
For the given SOAP Call object, return the SOAP message it represents, in raw XML form.
String
getRawSOAPMessage(Envelope env, SOAPMappingRegistry smr, SOAPContext ctx)
For a given Envelope, Mapping, and Context, return the SOAP message it represents, in raw XML form.
String
getRawSOAPResponse(Response resp, Call call)
For the given SOAP Call and Response, return the SOAP message that the Response represents, in raw XML form (the Call should be the Call that produced the Response, which is necessary to obtain the SOAPRegistryMapping that was used).
int
getTimeout()
Map
getTypes()
Return a Map of data types (standard and complex) that are used as Input or Output parameters in this WSDL file.
Definition
getWsdlDef(String wsdlURI)
Attempt to get the WSDL file at the given URI as a Definition, using any of the authentication or proxy parameters that have been specified so far.
boolean
isCaseSensitive()
void
setBasicAuthentication(String username, String password)
If basic authentication is used to connect to the web service, enter the user name and password here.
void
setCaseSensitive(boolean caseSensitive)
Determines whether or not the method names are case-sensitive.
void
setDebugOut(PrintStream stream)
Set the PrintStream that you want debug messages to be sent to, if any (by default this is null).
void
setProxyAuthentication(String proxyServer, int port, String username, String password)
If you must authenticate through a proxy server to connect to the web service, enter the proxy server host name, port, username, and password here.
void
setTimeout(int timeout)
Specifies a connection timeout value in milliseconds, if any.

Constructor Details

WsdlSoapWrapper

public WsdlSoapWrapper(String wsdlURI)
Create a new WsdlSoapWrapper object that will reference a WSDL file at the given location (can be an http:// or a file:/// path)

Parameters:
wsdlURI - a String giving the path to the WSDL file we'll be referencing (can be "http://..." or "file:///...")

Method Details

addComplexDatatype

public void addComplexDatatype(String datatypeName,
                               Class datatypeClass)
            throws WSDLException
Same as addComplexDatatype(namespace, datatypeName, datatypeClass), only the namespace is determined by searching through the types that are returned by the getTypes method. If the datatypeName is not found in the getTypes list, "" is used for the namespace.

Parameters:
datatypeName - the name of the complex data type you're mapping (i.e. -- the name specified in the WSDL file)
datatypeClass - the Java Class you want to map to this complex data type


addComplexDatatype

public void addComplexDatatype(String namespace,
                               String datatypeName,
                               Class datatypeClass)
            throws WSDLException
Add a complex data type to the SOAPMappingRegistry for any calls you make with this SoapHelper. This is necessary if complex data types are used as parameters or responses.

Parameters:
namespace - the namespace this type belongs to. You can also pass an empty String if you don't want a namespace associated with this data type (which could be the case if you're using it to deserialize a return value from a system that doesn't include data types with the return values -- often the case with Microsoft web services)
datatypeName - the name of the complex data type you're mapping (i.e. -- the name specified in the WSDL file)
datatypeClass - the Java Class you want to map to this complex data type, which should (obviously) have the same structure as the data type (see the Apache SOAP samples for examples of how this works). It also MUST have the characteristics of a JavaBean, with get/set statements for all variables that are in the complex data type you're modeling.


addReturnDatatype

public void addReturnDatatype(String datatypeName,
                              Deserializer deserializer)
            throws WSDLException
Add a data type to the SOAPMappingRegistry for values that are returned by calls you make with this SoapHelper. This is necessary the web service you are calling does not include data types with the XML elements in the SOAP body that is returned (which is common with Microsoft web services).

Normally, Apache SOAP will automatically deserialize common data types based on the type that is given for each value (like xsd:string, xsd:int, etc.). But if the return values don't have any data types specified, you'll have to provide mappings for each value that is returned. For example:

 wsw.addReturnDatatype("Result", new StringDeserializer());
 

Another use of this method is to specify that a response parameter should be returned as a raw XML node, with no translation, using the XmlNodeDeserializer class like this:

 wsw.addReturnDatatype("Result", new XmlNodeDeserializer());
 

This method attempts to guess what the namespace of the type will be, based on the types that are used as input and output parameters of the methods defined in the WSDL file. If you want to use an empty namespace instead, use the version of this method that allows you to specify a namespace, and pass "" as the namespace parameter.

Parameters:
datatypeName - the name of the data type you're mapping (i.e. -- the name of the parameter that is being returned, like "Result")
deserializer - a Deserializer that will be used to read this data. A number of deserializers for common data types are available in org.apache.soap.encoding.soapenc.* (StringDeserializer, ArrayDeserializer, etc)


addReturnDatatype

public void addReturnDatatype(String datatypeName,
                              String namespace,
                              Deserializer deserializer)
            throws WSDLException
This version of the addReturnDatatype method allows you to specify a particular namespace. Otherwise, see the description of the other version of this method for more information about what it does.

Parameters:
datatypeName -
namespace -
deserializer -


callMethod

public Response callMethod(String methodName,
                           Vector params)
            throws MalformedURLException,
                   SOAPException,
                   WSDLException
Call the method with the given name, using the list of parameters that are passed, and return the Response object that is generated.

Parameters:
methodName - the method that we're calling (if the WSDL file has overloaded the method, the first one found will be called)
params - Vector of org.apache.soap.rpc.Parameter objects, one for each parameter you want to pass to the call (or null if no parameters are desired)

Returns:
the Response object generated by this call, which will have the generatedFault() = true if there was an error on the web service side (normal Java Exceptions will be thrown in the case of runtime errors on the client or connectivity side)


callMethod

public Response callMethod(MethodInfo mi,
                           Vector params)
            throws MalformedURLException,
                   SOAPException,
                   WSDLException
Same as callMethod(methodName, params), except you pass a MethodInfo object instead of a method name. See documentation for that version of this method for more information on usage.

This is good if you want to save the effort of accessing and parsing a WSDL file (which is necessary if you just pass a method name) because you've stored away the MethodInfo information somewhere, or if you'd rather pass your own hardcoded MethodInfo values, rather than the ones that are automatically generated by reading the WSDL file.


debugPrint

public void debugPrint(Object obj)
If a debugStream has been set (by default it's null), try to print debug information to the Stream. Debugging messages are scattered throughout various methods in this class.

If you just want to see what it does, you can call setDebugOut(System.out) on the SoapHelper object you create and use it as you normally would.


getAllMethods

public Vector getAllMethods(String wsdlURI)
            throws WSDLException
For the WSDL file at the given location, return a Vector containing a MethodInfo object for each method in the WSDL file.

Parameters:
wsdlURI - a String giving the path to the WSDL file we'll be referencing (can be "http://..." or "file:///...")

Returns:
a Vector of MethodInfo objects


getDebugOut

public PrintStream getDebugOut()
Returns the PrintStream that we're sending debug output to, if any (this is null by default).

Returns:
the current debug PrintStream


getLastXmlResponse

public String getLastXmlResponse()
Get the last response that was received via callMethod as an XML String, if possible. This can be helpful in debugging errors.


getMethod

public MethodInfo getMethod(String methodName)
            throws WSDLException
Look for a method with the given methodName in the given WSDL file, and return a MethodInfo object with information about it. A WSDLException will be thrown if the method is not found.

Parameters:
methodName - a String giving the name of the method we're looking for (the match IS case-sensitive)

Returns:
a Vector of MethodInfo objects


getMethod

public MethodInfo getMethod(String methodName,
                            boolean caseSensitive)
            throws WSDLException
Look for a method with the given methodName in the given WSDL file, and return a MethodInfo object with information about it. A WSDLException will be thrown if the method is not found.

Parameters:
methodName - a String giving the name of the method we're looking for
caseSensitive - whether or not the search for the methodName is case-sensitive (true) or not (false)

Returns:
a Vector of MethodInfo objects


getMethodInputNamespace

public String getMethodInputNamespace(BindingOperation bindOp)
Given a BindingOperation in a WSDL file, try to get the namespace that is specified for the input message, if one has been specified.

Parameters:
bindOp - the BindingOperation we're looking at

Returns:
the namespace for this BindingOperation's input, if one could be found (null or "" if not)


getMethodList

public Vector getMethodList()
            throws WSDLException
Returns a Vector of MethodInfo objects, one for each method in the WSDL file that was given when this object was instantiated.

Returns:
a Vector of MethodInfo objects


getMethodSoapAction

public String getMethodSoapAction(BindingOperation bindOp)
Given a BindingOperation in a WSDL file, try to get the SOAP Action that is specified for that operation, if one has been specified.

Parameters:
bindOp - the BindingOperation we're looking at

Returns:
the SOAP Action for this BindingOperation, if one could be found (null or "" if not)


getNamespaceForType

public String getNamespaceForType(String typeName,
                                  boolean caseSensitive)
            throws WSDLException
Attempt to find and return the namespace used by the given complex data type. The caseSensitive parameter determines whether the data type name match is case-sensitive or not, as we're searching the type list in the WSDL file.

The type list is generated by looking at the input and output message definitions for each method, so it's possible that there are complex data types that are defined in the WSDL file that won't be listed here, because they aren't used as parameters or return values. So, for example, a complex data type that is nested within another complex data type might not show up on this list.

Parameters:
typeName - the name of the data type we're looking for
caseSensitive - whether or not the name match should be case-sensitive

Returns:
a String representing the namespace used by this data type, or "" if the type name was not found


getPortSoapURL

public String getPortSoapURL(Port port)
For a given Port specification in a WSDL file, return the URL that should be used to make calls to this Port.

Parameters:
port - the Port we're looking at

Returns:
a String indicating the URL associated with this Port (or null if one could not be found)


getRawSOAPMessage

public String getRawSOAPMessage(Call call)
For the given SOAP Call object, return the SOAP message it represents, in raw XML form.

Parameters:
call - a Call object that's ready to be sent

Returns:
a String representing the XML SOAP message that would be generated by this Call object, or an error message if there was a problem


getRawSOAPMessage

public String getRawSOAPMessage(Envelope env,
                                SOAPMappingRegistry smr,
                                SOAPContext ctx)
For a given Envelope, Mapping, and Context, return the SOAP message it represents, in raw XML form.

Parameters:
env - an Envelope object, normally from a call to Call.buildEnvelope() or Response.buildEnvelope()
smr - a SOAPMappingRegistry, normally from Call.getSOAPMappingRegistry()
ctx - a SOAPContext, normally from RPCMessage.getSOAPContext()

Returns:
a String representing the XML SOAP message that would be generated from these parameters, or an error message if there was a problem


getRawSOAPResponse

public String getRawSOAPResponse(Response resp,
                                 Call call)
For the given SOAP Call and Response, return the SOAP message that the Response represents, in raw XML form (the Call should be the Call that produced the Response, which is necessary to obtain the SOAPRegistryMapping that was used).

Please note that the XML string that is generated by this version of the getRawSOAPMessage method is NOT necessarily the same as the actual message that was received. It is simply a represenation of the information that was parsed into the given Response object. If you want the actual message that was returned you will need to use a sniffer or proxy like TCPMon.

Parameters:
resp - a Response object that has been received as a SOAP response to a Call
call - a Call object that has been sent

Returns:
a String representing the XML SOAP message that could have created this Response object, or an error message if there was a problem


getTimeout

public int getTimeout()

Returns:
Returns the timeout.


getTypes

public Map getTypes()
            throws WSDLException
Return a Map of data types (standard and complex) that are used as Input or Output parameters in this WSDL file. The key for each Map entry is the name of the data type, and the value for each entry is that type's namespace.

Returns:
a Map of data type names and their namespaces


getWsdlDef

public Definition getWsdlDef(String wsdlURI)
            throws WSDLException,
                   IOException,
                   MalformedURLException
Attempt to get the WSDL file at the given URI as a Definition, using any of the authentication or proxy parameters that have been specified so far. Normally, the URI will be something like http://myserver/file.wsdl or file:///c:/file.wsdl

I'm not entirely sure this will work if the URI is specified as an https:// path. It's possible, but you would at least need to have JSSE included and configured properly. For more information on JSSE, see:
http://java.sun.com/j2se/1.4.2/docs/guide/security/jsse/JSSERefGuide.html

Parameters:
wsdlURI - a String giving the path to the WSDL file we'll be referencing (can be "http://..." or "file:///...")

Returns:
a WSDL4J Definition based on the WSDL file


isCaseSensitive

public boolean isCaseSensitive()

Returns:
Returns the caseSensitive.


setBasicAuthentication

public void setBasicAuthentication(String username,
                                   String password)
If basic authentication is used to connect to the web service, enter the user name and password here.


setCaseSensitive

public void setCaseSensitive(boolean caseSensitive)
Determines whether or not the method names are case-sensitive. Default is false (NOT case-sensitive).


setDebugOut

public void setDebugOut(PrintStream stream)
Set the PrintStream that you want debug messages to be sent to, if any (by default this is null). Common values are System.err or a PrintStream that is wrapped around a FileOutputStream.

Parameters:
stream - the PrintStream to write to


setProxyAuthentication

public void setProxyAuthentication(String proxyServer,
                                   int port,
                                   String username,
                                   String password)
If you must authenticate through a proxy server to connect to the web service, enter the proxy server host name, port, username, and password here.


setTimeout

public void setTimeout(int timeout)
Specifies a connection timeout value in milliseconds, if any. Default is 0 (no timeout).