Prev Class | Next Class | Frames | No Frames |
Summary: Nested | Field | Method | Constr | Detail: Nested | Field | Method | Constr |
java.lang.Object
com.nsftools.jurst.WsdlSoapWrapper
public class WsdlSoapWrapper
extends java.lang.Object
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:
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"); 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(); }
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:WsdlSoapWrapper wsw = new WsdlSoapWrapper("http://localhost/EchoService?WSDL"); wsw.addComplexDatatype("BookInfo", BookInfo.class);
caseSensitive
variable controls
whether the method names in the WSDL file are looked up in a
case-sensitive or non-case-sensitive manner (by default, this is
false, so it's NOT case-sensitive)timeout
variable to a
number greater than zero to enforce a timeout value when calling
a web service (the timeout is in milliseconds)setDebugOut
.
This will show you, among other things, the raw XML SOAP messages
that are sent out as requests and the raw XML SOAP responses that
are received.Constructor Summary | |
|
Method Summary | |
void |
|
void |
|
void |
|
void |
|
Response |
|
Response |
|
void |
|
Vector |
|
PrintStream |
|
String |
|
MethodInfo |
|
MethodInfo |
|
String |
|
Vector |
|
String |
|
String |
|
String |
|
String |
|
String |
|
String |
|
int | |
Map |
|
Definition |
|
boolean | |
void |
|
void |
|
void |
|
void |
|
void |
|
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:///...")
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
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.
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: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 StringDeserializer());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.wsw.addReturnDatatype("Result", new XmlNodeDeserializer());
- 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)
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
-
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)
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.
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.
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
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
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.
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
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 forcaseSensitive
- whether or not the search for the methodName is case-sensitive (true) or not (false)
- Returns:
- a Vector of MethodInfo objects
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)
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
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)
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 forcaseSensitive
- 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
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)
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
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
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 Callcall
- 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
public int getTimeout()
- Returns:
- Returns the timeout.
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
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
public boolean isCaseSensitive()
- Returns:
- Returns the caseSensitive.
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.
public void setCaseSensitive(boolean caseSensitive)
Determines whether or not the method names are case-sensitive. Default is false (NOT case-sensitive).
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
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.
public void setTimeout(int timeout)
Specifies a connection timeout value in milliseconds, if any. Default is 0 (no timeout).