com.nsftools.jurst

Class SoapHelper


public class SoapHelper
extends WsdlSoapWrapper

The SoapHelper class is an extension of the WsdlSoapWrapper that simplifies calls to SOAP-based web services even more than WsdlSoapWrapper does.

You'll still 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. To start with, you can use the SoapHelper class to give you information about the available methods in a WSDL file, like this:

 SoapHelper helper = new SoapHelper("http://localhost/EchoService?WSDL");
 System.out.println(helper.dumpMethodList());
 

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

 SoapHelper sh = new SoapHelper("http://localhost/EchoService?WSDL");
 ArrayList paramList = new ArrayList();
 paramList.add("Does This Work?");
 System.out.println("Response = " + sh.callSimpleMethodList("echoString", paramList));
 

Or, more concisely:

 SoapHelper sh = new SoapHelper("http://localhost/EchoService?WSDL");
 System.out.println("Response = " + sh.callSimpleMethod("echoString", "Does This Work?"));
 

If you need to pass or return a complex data type, you can do something like this:

 SoapHelper sh = new SoapHelper(wsdl);
 // you'll need to have already created the BookInfo class
 // that matches up to the web service's BookInfo data type
 sh.addComplexDatatype("BookInfo", BookInfo.class);
 Object obj = sh.callSimpleMethod("getBookInfo", "Cryptomonicon");
 // the response will be a String if there was a Fault; otherwise
 // it's supposed to be an instance of BookInfo
 if (obj instanceof String) {
 	System.out.println("String response = " + obj);
 } else if (obj instanceof BookInfo) {
 	BookInfo bi = (BookInfo)obj;
 	System.out.println("BooksInfo response " + bi);
 } else {
 	System.out.println("Response was a " + obj.getClass().getName());
 }
 

You can use the callMethod routine from the parent WsdlSoapWrapper class if you need a little more control over the parameters you send and the response that you get back, but I've found that in most cases I can get away with one of the callSimpleMethod calls. See the comments in the WsdlSoapWrapper class for more details and information.

AUTHOR'S NOTE:
Okay, now this whole overloaded callSimpleMethod business is UG-LY. But Java didn't introduce the concept of varargs until Java 1.5, and lots of people are still on older versions of Java right now. So we've got 11 differerent versions of callSimpleMethod -- with no params, with one param, with two params, etc. All that, just to make it easier for the user to call a web service. So instead of:

	ArrayList paramList = new ArrayList();
	paramList.add("whatever");
	Object obj = sh.callSimpleMethodList("method1", paramList);
 

you can just call:

 	Object obj = sh.callSimpleMethod("method1", "whatever");
 

Granted, it's only saving 2 lines of code, but sometimes that's what makes people happy.

Version:
0.9.2

Author:
Julian Robichaux

Constructor Summary

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

Method Summary

Object
callSimpleMethod(String methodName)
Overloaded version of callSimpleMethod that allows you to easily call a method that has no parameters.
Object
callSimpleMethod(String methodName, Object value1)
Overloaded version of callSimpleMethod that allows you to easily call a method that has one parameter.
Object
callSimpleMethod(String methodName, Object value1, Object value2)
Easily call a method that has two parameters.
Object
callSimpleMethod(String methodName, Object value1, Object value2, Object value3)
Easily call a method that has three parameters.
Object
callSimpleMethod(String methodName, Object value1, Object value2, Object value3, Object value4)
Easily call a method that has four parameters.
Object
callSimpleMethod(String methodName, Object value1, Object value2, Object value3, Object value4, Object value5)
Easily call a method that has five parameters.
Object
callSimpleMethod(String methodName, Object value1, Object value2, Object value3, Object value4, Object value5, Object value6)
Easily call a method that has six parameters.
Object
callSimpleMethod(String methodName, Object value1, Object value2, Object value3, Object value4, Object value5, Object value6, Object value7)
Easily call a method that has seven parameters.
Object
callSimpleMethod(String methodName, Object value1, Object value2, Object value3, Object value4, Object value5, Object value6, Object value7, Object value8)
Easily call a method that has eight parameters.
Object
callSimpleMethod(String methodName, Object value1, Object value2, Object value3, Object value4, Object value5, Object value6, Object value7, Object value8, Object value9)
Easily call a method that has nine parameters.
Object
callSimpleMethod(String methodName, Object value1, Object value2, Object value3, Object value4, Object value5, Object value6, Object value7, Object value8, Object value9, Object value10)
Easily call a method that has ten parameters.
Object
callSimpleMethodList(String methodName, List paramValues)
Call the method with the given name, using the list of parameters that are passed, and return the Java object that is generated by the Response (or a String containing Fault information in the case of a fault).
Object
callSimpleMethodList(MethodInfo mi, List paramValues)
Same as callSimpleMethodList(methodName, paramValues), except you pass your own MethodInfo object instead of a method name.
String
dumpMethodList()
Returns a String value containing information about all the methods in the WSDL file that was given when this object was instantiated.
String
dumpTypeList()
Returns a String value containing information about the data types (standard or complex) in the WSDL file that was given when this object was instantiated.
boolean
isFault()
Returns true if the last call to callSimpleMethod resulted in a Fault, false otherwise (note that this is NOT set by callMethod, only by callSimpleMethod).

Methods inherited from class com.nsftools.jurst.WsdlSoapWrapper

addComplexDatatype, addComplexDatatype, addReturnDatatype, addReturnDatatype, callMethod, callMethod, debugPrint, getAllMethods, getDebugOut, getLastXmlResponse, getMethod, getMethod, getMethodInputNamespace, getMethodList, getMethodSoapAction, getNamespaceForType, getPortSoapURL, getRawSOAPMessage, getRawSOAPMessage, getRawSOAPResponse, getTimeout, getTypes, getWsdlDef, isCaseSensitive, setBasicAuthentication, setCaseSensitive, setDebugOut, setProxyAuthentication, setTimeout

Constructor Details

SoapHelper

public SoapHelper(String wsdlURI)
Create a new SoapHelper 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

callSimpleMethod

public Object callSimpleMethod(String methodName)
            throws MalformedURLException,
                   SOAPException,
                   WSDLException
Overloaded version of callSimpleMethod that allows you to easily call a method that has no parameters. This method will end up calling callSimpleMethodList, so please see the documentation for that method for information about usage and return values.


callSimpleMethod

public Object callSimpleMethod(String methodName,
                               Object value1)
            throws MalformedURLException,
                   SOAPException,
                   WSDLException
Overloaded version of callSimpleMethod that allows you to easily call a method that has one parameter. This method will end up calling callSimpleMethodList, so please see the documentation for that method for information about usage and return values.

The values that are passed can be any type of object (String, Double, custom class, etc.) that is an appropriate parameter for the web service method that is being called. You can also pass an Object array (String[], Double[], etc.) as a parameter, if appropriate.

If you wish to pass a primitive as a parameter, please use the corresponding Java Object instead (i.e. -- Integer instead of integer).


callSimpleMethod

public Object callSimpleMethod(String methodName,
                               Object value1,
                               Object value2)
            throws MalformedURLException,
                   SOAPException,
                   WSDLException
Easily call a method that has two parameters. See callSimpleMethod(methodName, value1) for details.


callSimpleMethod

public Object callSimpleMethod(String methodName,
                               Object value1,
                               Object value2,
                               Object value3)
            throws MalformedURLException,
                   SOAPException,
                   WSDLException
Easily call a method that has three parameters. See callSimpleMethod(methodName, value1) for details.


callSimpleMethod

public Object callSimpleMethod(String methodName,
                               Object value1,
                               Object value2,
                               Object value3,
                               Object value4)
            throws MalformedURLException,
                   SOAPException,
                   WSDLException
Easily call a method that has four parameters. See callSimpleMethod(methodName, value1) for details.


callSimpleMethod

public Object callSimpleMethod(String methodName,
                               Object value1,
                               Object value2,
                               Object value3,
                               Object value4,
                               Object value5)
            throws MalformedURLException,
                   SOAPException,
                   WSDLException
Easily call a method that has five parameters. See callSimpleMethod(methodName, value1) for details.


callSimpleMethod

public Object callSimpleMethod(String methodName,
                               Object value1,
                               Object value2,
                               Object value3,
                               Object value4,
                               Object value5,
                               Object value6)
            throws MalformedURLException,
                   SOAPException,
                   WSDLException
Easily call a method that has six parameters. See callSimpleMethod(methodName, value1) for details.


callSimpleMethod

public Object callSimpleMethod(String methodName,
                               Object value1,
                               Object value2,
                               Object value3,
                               Object value4,
                               Object value5,
                               Object value6,
                               Object value7)
            throws MalformedURLException,
                   SOAPException,
                   WSDLException
Easily call a method that has seven parameters. See callSimpleMethod(methodName, value1) for details.


callSimpleMethod

public Object callSimpleMethod(String methodName,
                               Object value1,
                               Object value2,
                               Object value3,
                               Object value4,
                               Object value5,
                               Object value6,
                               Object value7,
                               Object value8)
            throws MalformedURLException,
                   SOAPException,
                   WSDLException
Easily call a method that has eight parameters. See callSimpleMethod(methodName, value1) for details.


callSimpleMethod

public Object callSimpleMethod(String methodName,
                               Object value1,
                               Object value2,
                               Object value3,
                               Object value4,
                               Object value5,
                               Object value6,
                               Object value7,
                               Object value8,
                               Object value9)
            throws MalformedURLException,
                   SOAPException,
                   WSDLException
Easily call a method that has nine parameters. See callSimpleMethod(methodName, value1) for details.


callSimpleMethod

public Object callSimpleMethod(String methodName,
                               Object value1,
                               Object value2,
                               Object value3,
                               Object value4,
                               Object value5,
                               Object value6,
                               Object value7,
                               Object value8,
                               Object value9,
                               Object value10)
            throws MalformedURLException,
                   SOAPException,
                   WSDLException
Easily call a method that has ten parameters. See callSimpleMethod(methodName, value1) for details.


callSimpleMethodList

public Object callSimpleMethodList(String methodName,
                                   List paramValues)
            throws MalformedURLException,
                   SOAPException,
                   WSDLException
Call the method with the given name, using the list of parameters that are passed, and return the Java object that is generated by the Response (or a String containing Fault information in the case of a fault).

The difference between this and callMethod is with this you pass a List of Objects that should be used as parameters, and the Objects in that List are included in the order specified by the parameter list in the WSDL file (whereas with callMethod you match the parameter name to the object for each Parameter object in the Vector). Also, callMethod returns the actual Response object generated by the SOAP call, while this method returns the object contained within the Response object (or a String containing Fault data).

Parameters:
methodName - the method that we're calling (if the WSDL file has overloaded the method, the first one found will be called)
paramValues - List of Objects, one for each parameter you want to pass to the call (or null if no parameters are desired)

Returns:
the Java Object contained within the Response from this call, or a String containing Fault data 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)


callSimpleMethodList

public Object callSimpleMethodList(MethodInfo mi,
                                   List paramValues)
            throws MalformedURLException,
                   SOAPException,
                   WSDLException
Same as callSimpleMethodList(methodName, paramValues), except you pass your own MethodInfo object instead of a method name. See documentation of the other version of this method for more information.


dumpMethodList

public String dumpMethodList()
Returns a String value containing information about all the methods in the WSDL file that was given when this object was instantiated. This is really just a convenience, for times when you want to know how this class sees the WSDL contents.

Returns:
a String with information about all the methods in this WSDL file


dumpTypeList

public String dumpTypeList()
Returns a String value containing information about the data types (standard or complex) in the WSDL file that was given when this object was instantiated.

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.

Returns:
a String with information about the data types in this WSDL file that are used as parameters for request or response messages


isFault

public boolean isFault()
Returns true if the last call to callSimpleMethod resulted in a Fault, false otherwise (note that this is NOT set by callMethod, only by callSimpleMethod).