==========================
Prerequisites
==========================
1. Apache Axis2 -
We use Apache Axis2 to generate Java classes which can be used to call the Web service
2. Oracle Java JDK -
Required by Axis2 and needed to compile the generated Java code.
3. Apache Ant -
Not absolutely necessary but this does provide the easiest way to compile the code.
==========================
Configuration
==========================
For the tools above to work correctly you will need to configure 3 environment variables:
1. JAVA_HOME needs to point to the location where the JDK has been installed.
2. AXIS2_HOME needs to point to the location where Axis2 has been unpacked.
3. ANT_HOME needs to point to the location where Ant has been unpacked.
==========================
Usage
==========================
1. Generating Java classes from WSDL definition
The first step is to generate the Java classes which can call the Web service. The Axis2 tool wsdl2java can do this; this tool can be found in the bin directory of you Axis2 installation. Suppose your Web service WSDL definition is available at _http://somehost/myWSDLLocation_ then the following command can be used to generate the classes:
wsdl2java -s -uw -uri _http://somehost/myWSDLLocation_
In this command we used the following switches:
-s To only generate synchronously callable methods (the asyncrhonous methods will not be easily callable from MATLAB anyway).
-uw To unwrap the databinder classes which makes calling the methods easier as you do not need to wrap and unwrap the in- and output parameters anymore
-uri To specify the location of the WSDL definition.
2. Compiling the Java classes
wsdl4java should automatically have generated an Ant Task build.xml which should make compiling the code as simple as running ant (from the ANT_HOME/bin directory):
ant
This should create a JAR-file in a directory called build/lib.
3. Bringing the Java classes into MATLAB
The JAR-file created under 2. can be loaded into MATLAB using the JAVAADDPATH function, for example:
javaaddpath build/lib/myJARFile.jar
4. Calling the Java classes
You can now instantiate an object of the class, for example:
myService = myNameSpace.MyServiceStub
Then, if working with a .NET Web service you may need to disable chuncked data transfer using:
serviceClient = javaMethod('_getServiceClient',myService);
serviceClient.getOptions().setProperty( org.apache.axis2.transport.http.HTTPConstants.CHUNKED, java.lang.Boolean.FALSE);
Now you should be able to call the Web service operations, see the example below.
==========================
Example
==========================
In this example we assume that our Web service is called myService in the com.mathworks.ts namespace and that it is located at:
http://localhost:8080/myWebApplication/myService
And its WSDL definition can be found at:
http://localhost:8080/myWebApplication/myService?wsdl
Further we assume that our Web service offers the following operations:
String hello(String txt)
Simple example operation
Parameters:
txt - Your name.
Returns:
Hello TXT!
myStruct getStruct()
An operation which returns a more complex datatype.
Returns:
Example myStruct with:
A = "A"
B = "B"
C = 3.14
myStruct[] getStructArray(int N)
An operation which returns an array of a more complex datatype.
Parameters:
N - Number of elements in the array to return.
Returns:
Array of myStruct.
String getAFromStruct(myStruct s)
An operation which takes a more complex datatype as input.
Parameters:
s - myStruct input.
Returns:
The value of field A of the input.
In all this, myStruct is defined as a structure with fields A, B and C. Where A and B are strings and C is a double; so for example:
myStruct =
A: 'A'
B: 'B'
C: 3.1400
Now as described above, first we need to generate the Java classes and compile them into a JAR-file. To do this in an easy way from within MATLAB we can use the attached createClasses.m function:
>> createClasses('http://localhost:8080/myWebApplication/myService?wsdl')
This gives us build/lib/myService-test-client.jar. Which we can import into MATLAB using:
>> javaaddpath build/lib/myService-test-client.jar
Then to instantiate an object of our generated class:
>> myService = com.mathworks.ts.MyServiceStub;
And now we can start calling the operations. For example the "hello" operation:
>> hello = myService.hello('World')
hello =
Hello World !
Or the getStruct operation:
>> jmyStruct1 = myService.getStruct
jmyStruct1 =
com.mathworks.ts.MyServiceStub$MyStruct@e26e44
As we can see this returns a Java object with the following methods:
>> methods(jmyStruct1)
Methods for class com.mathworks.ts.MyServiceStub$MyStruct:
MyServiceStub$MyStruct getB getOMElement isReaderMTOMAware serialize setC
equals getC getPullParser notify setA toString
getA getClass hashCode notifyAll setB wait
So we can see that the A, B and C fields can be accessed through getA, getB and getC, for example:
>> jmyStruct1.getC
ans =
3.1400
Using these methods we can convert the Java object into a MATLAB structure; the attached j2s.m function can help us with that:
>> myStruct1 = j2s(jmyStruct1)
myStruct1 =
A: 'A'
B: 'B'
C: 3.1400
Similarly we can also call the getStructArray operation:
>> jmyStruct2 = myService.getStructArray(3);
>> myStruct2 = j2s(jmyStruct2)
myStruct2 =
1x3 struct array with fields:
A
B
C
Lastly we can call the getAFromStruct operation which actually takes a myStruct as input. For that we first need to create a myStruct object:
>> jmyStuctIn = javaObject('com.mathworks.ts.MyServiceStub$MyStruct');
And then we can assign a value to the A field:
>> jmyStuctIn.setA('MATLAB')
Now we can use this object to call the operation:
>> A = myService.getAFromStruct(jmyStuctIn)
A =
MATLAB
