hi all,
The main objective of this module is to let users to publish their existing
Java classes as web services and access them with out warring about Axis2
and web services. This module let users to publish web services and access
them some what similar way as Java RMI does.
Axis2-rmi uses a custom deployer and a custom archive file format to deploy
java classes. The archive file which has the .rsa (rmi service archive)
extension has the following structure.
META-INF
config.xml
<java classes>
For the moment there is a config.xml file under the META-INF folder and java
classes at the top folder. Later this can be improved to put jar files to a
lib folder as well. The config.xml file is used to specify the service
classes and other configuration details to the deployer. It has the
following structure.
<config xmlns="http://ws.apache.org/axis2/rmi";>
<extensionClasses>
<extensionClass>sample.rmi.server.dto.ChildClass</extensionClass>
</extensionClasses>
<packageToNamespaceMapings>
<packageToNamespaceMap>
<namespace>http://sample/service</namespace>
<packageName>sample.rmi.server</packageName>
</packageToNamespaceMap>
</packageToNamespaceMapings>
<services>
<service>
<serviceClass>sample.rmi.server.Service1</serviceClass>
</service>
</services>
</config>
As you can see config.xml is used to specify any configuration details like
extention classes, package to namespace mappings and services.
Now lets see a step by step example to understand how to use Axis2-rmi to
deploy a java service and access them from the client.
Step 1 deploy the service
In java RMI the first step in writing a distributed system is to write the
service and register it. Similarly here also we have to first create the
service and deploy it using the above file format.
For a example if we want to deploy the following java service.
package sample.rmi.server;
public class Service1 {
public Object method1(Object param1){
return param1;
}
}
Here the both input and output parameters are object type. The idea here is
to publish this web service and invoke it by sending an input parameter
actually in TestClass1 type.
package sample.rmi.server;
public class TestClass1 {
private String param1;
private String parma2;
public String getParam1() {
return param1;
}
public void setParam1(String param1) {
this.param1 = param1;
}
public String getParma2() {
return parma2;
}
public void setParma2(String parma2) {
this.parma2 = parma2;
}
}
To deploy this service one can use the following config.xml. This is self
explainable.( please change any as necessary). To find a correct working
sample please see the rmi sample under samples folder.
<config xmlns="http://ws.apache.org/axis2/rmi";>
<extensionClasses>
<extensionClass>sample.rmi.server .TestClass1</extensionClass>
</extensionClasses>
<packageToNamespaceMapings>
<packageToNamespaceMap>
<namespace>http://sample/service</namespace>
<packageName>sample.rmi.server</packageName>
</packageToNamespaceMap>
</packageToNamespaceMapings>
<services>
<service>
<serviceClass>sample.rmi.server.Service1</serviceClass>
</service>
</services>
</config>
The .rsa file should look like this
META-INF
config.xml
sample.rmi.server.Service1.class
sample.rmi.server .TestClass1.class
There is a Custom deployer declaration in the Axis2.xml file for this.
<deployer extension=".rsa" directory="rmiservices" class="
org.apache.axis2.rmi.deploy.RMIServiceDeployer"/>
So you have to put the above created archive file to rmiservices folder
under repository. (if there is no folder please create one.) Then the Axis2
server can be started as usual and This service wsdl can be seen.
Step 2 access the client.
In Java RMI we create an Stub file to access the service. Here also it can
be given a Stub generation tool to generate the stub for the service
interface. But for the moment this feature is not there and RMIClient can be
used directly access the service.
public class TestService1 {
private Configurator configurator;
public TestService1() {
this.configurator = new Configurator();
this.configurator.addPackageToNamespaceMaping("sample.rmi.server", "
http://sample/service";);
this.configurator.addExtension(TestClass1 .class);
}
public void testMethod13() {
try {
RMIClient rmiClient = new RMIClient(Service1.class, this.configurator, "
http://localhost:8080/axis2/services/Service1";);
List inputObjects = new ArrayList();
TestClass1 testClass1 = new TestClass1();
testClass1.setParam1("test string");
testClass1.setParam2("test string");
inputObjects.add(testClass1);
TestClass1 result = (TestClass1) rmiClient.invokeMethod("method1",
inputObjects);
System.out.println("Param 1 ==>" + result.getParam1());
System.out.println("Param 2 ==>" + result.getParam2());
} catch (Exception e) {
e.printStackTrace();
}
}
This client can be run putting all the jars under lib directory to class
path.
This way people can invoke their existing java classes using Soap protocol
in a similar way with Java RMI. An advanced Axis2 user may use the following
way to deploy a java class service and start the simple http server .
ConfigurationContext confContext =
ConfigurationContextFactory.createConfigurationContextFromFileSystem(
AXIS2_REPOSITORY_LOCATION, AXIS2_CONFIG_FILE);
// add the service
// if you want to specify additional configuration details, the constructor
with
// the configurater as an argumet can be used.
ClassDeployer classDeployer = new ClassDeployer(confContext);
classDeployer.deployClass(Service1.class);
SimpleHTTPServer simpleHttpServer = new SimpleHTTPServer(confContext,
5555);
simpleHttpServer.start();
Features in the Current implementation (Please see the rmi sample under
sample folder)
1.
POJO support (simple beans, arrays, composite beans, null value
handling)
2.
Extensions and polymorphisem.
3.
Fault handling
4.
Collection class support (List, ArrayList, Set , HashSet)
5.
Package to namespace mapping
Features plaing to implement (feel free to add to this list)
1.
Map support (Map , HashMap)
2.
MTOM support. (DataHandler class support)
3.
Dom element support
4.
Configure nillable and minOccurs attributes through config.xml
5.
Provide a codegen tool to generate the stub.
6.
Qname support.
Architecture and Performance.
Axis2 rmi keeps a metadata model to keep java classes and their xml mapping
details. This meta data model is used to Generate the wsdl, to marshall the
java object structure and to unmarshall java object structure. Hence this
meta data model has provide the following advantages.
1.
directly marshal(serialize) and unmarshal(parse) the object structure
to the xml stream with out using and intermediate xml object structure.
2.
Minimize the performance over head with java reflection since it keeps
the relavent java method in metadata structure.
3.
Enable usage of extensions and polymorphism, which requires the
inheritance relationships at the serialization and deserialization time.
Thanks,
Amila.
--
Amila Suriarachchi,
WSO2 Inc.
