How to point to a separate Carbon OSGi Repository?

It’s a well-known fact that all Carbon based products can be deployed on top of other application servers like Tomcat, JBoss, Web Logic etc. For example, WSAS on tomcat, WSAS on Web Logic and ESB on tomcat. When deploying Carbon on a separate application server, we have to point to a Carbon home directory through the CARBON_HOME environment variable.

Some users may set up more than one instance of Carbon, pointing to the same Carbon home. In this case, everything under Carbon home directory is shared by these Carbon instances. That includes configuration files (CARBON_HOME/conf), Axis2 repository (CARBON_HOME/repository) and Carbon OSGi repository (CARBON_HOME/repository/components). Even though sharing of configurations and Axis2 repository is perfectly OK, Carbon OSGi repository can cause problems when it is shared by more than one instance of Carbon.

So this is where we want to point to a separate Carbon OSGi repository while sharing the other stuff. In Carbon 2.x, you can do that by using the CARBON_REPOSITORY environment variable. Set it to some folder and create a folder called ‘components’ inside that folder. Finally start the server.

Example: If your Carbon OSGi repository is at /carbonRepo, set CARBON_REPOSITORY=/carbonRepo and create a folder /carbonRepo/components. Now start the server.

Now your Carbon instance uses the above place as the OSGi repository. After starting the server, you can see lot of folders inside your components folder.

There is something important to remember here. Even though you separate the OSGi repository from CARBON_HOME, if you want to use components/lib folder or components/extensions folder, you have to use them inside CARBON_HOME.

Example : If you want the my-sql driver, you have to place it in CARBON_HOME/repository/components/lib folder. NOT in /carbonRepo/components/lib folder.

So If you are also trying to use the same CARBON_HOME for multiple Carbon instances, make sure you use separate Carbon OSGi repository for each and every instance as shown in the following diagram.

How to invoke an Axis2 JAXWS service RESTfully?

Have you ever tried to invoke an Axis2 JAXWS service in RESTful manner? Was it successfull? If not, you will find the reason in this post. And also you will find how to do it.

Most of the time we write simple JAXWS services like this..

@WebService
public class JAXWSAARService {

@WebMethod (operationName = “echo”, action = “urn:echo”)
public String echo(String in) {
return in;
}

}

In this service, @BindingType annotation is not used and according to the JAXWS specification, the default is SOAP 11 binding. So the generated WSDL for the above service will only generate a SOAP 11 binding. That’s why we can’t invoke the service in RESTful manner. If you try it, it will give you the following error.

“Incoming message protocol does not match endpoint protocol.”

In order to invoke a service RESTfully, an HTTP binding is needed. Therefore in the above service, you have to use the @BindingType annotation and set it’s value to HTTP binding as follows.

@WebService
@BindingType(value= HTTPBinding.HTTP_BINDING)
public class JAXWSAARService {
…
}

Now the Axis2 JAXWS deployer will generate an HTTP binding for you. Now you can invoke the service RESTfully using the following URL.

http://localhost:8080/axis2/services/JaxwsAarService.JaxwsAarPort/echo?in=hello

 

 

Sri Lanka wins 2 Bronze medals and 3 Honourable Mentions in the 50th IMO

It was a great pleasure for me to know that Sri Lanka has won 2 bronze medals and 3 honourable mentions in the 50th International Mathematical Olympiad (IMO) competition held recently in Germany. Our students have scored 74 marks and become the 50th in the rankings out of 104 countries. This is a great achievement in the context of IMO.

I had the opportunity of representing Sri Lankan team in the 44th IMO which was held in Japan. Our team could score only few marks and we were among the lowest scorers in the rankings. It’s an extremely tough competition and normally other counties prepare students for IMO from their childhood.

Contestants must be below 20 years and must have not entered a university. Competition is held for 2 days and 3 problems are given each day. Time for a problem is 1.5 hours. Each problem carries 7 marks and the total is 42.

Mr. Chanakya J. Wijeratne who is a senior lecturer at the department of mathematics, university of Colombo, is the person who is behind this great success. He has been training students for IMO for more than 6 years now. We also were trained under him and he is doing a great job for our country.

I think our students can win more and more medals in IMO (even golds) if we can train them at least for one year. Definitely the required brains are there. What we lack is training. So well done boys.. Keep it up..

Sachin passes 17000 in style

Cricket is almost like a religion in India and Sachin is a god for Indian cricket fans. What a player he is.. Still hungry for runs, still scores centuries, still a match winner ans still improving.

The little master passed 17000 ODI runs with a huge century which almost took India home in the high scoring 5th ODI against Aussies. Who can break Sachin’s batting records? Actually I don’t see any one. And also I think there won’t be anyone for some time. 17000 ODI runs with 45 hundreds and 91 fifties. Almost 13000 test runs with 42 hundreds and 53 fifties. Oh.. unbelievable for a cricketer.

I always enjoy his batting when he’s not playing against Sri Lankans . It’s great to watch his beautiful cover drives, straight drives, cuts, pulls etc. with an excellent technique.

I think he will play until the 2011 world cup and will definitely produce more and more centuries for India. So Sachin, score tons of runs against all the counties other than Sri Lanka . Thanks for providing great entertainment for over 2 decades.. Keep going..

Can we deploy additional web applications in Carbon??..

This is a very common question and most people are asking this again and again. Answer to this question is like “Yes and No” . So let me explain it in bit more details.

As you may already know, the standalone carbon server is build on top of an embedded Tomcat instance. Carbon is deployed within it as any other web application. In other words, Carbon itself is a web application. So it should be possible to deploy additional web apps in this embedded Tomcat instance and they should run in parallel with Carbon. But practically this is not the case.

We have done some customizations to this embedded Tomcat instance to support our OSGi based Carbon framework mounted on top of it. There are some additional libraries in CARBON_HOME/lib (equal to TOMCAT_HOME/lib) which are related to Carbon framework. Those jars can cause problems for your web application as Tomcat uses parent first class loading. And also, in Carbon we haven’t used all libraries which comes with a normal Tomcat instance. Therefore, some functionalities which are needed for full web application support may be not there.

Today, one user came up with a very good question. That is “If you have customised the embedded Tomcat instance to support Carbon, are we going to miss some functionalities when Carbon is deployed in some other Application server?”. The answer is “No”. So don’t worry about that . Those customizations are not directly related to product functionalities. All Carbon based products are tested on may application servers like Tomcat, WebLogic, WebSphere etc.

So in conclusion, we don’t recommend deploying other web apps inside any of our Carbon based products. But basic web apps will work. If you want to have your additional web apps in parallel with Carbon, the recommended approach is to deploy Carbon in some other application server and deploy the other web apps inside the same application server.

How to use Axis2 JSON

Some time back, I implemented JSON support for Axis2 and I’ve explained about the architecture and usage of it here. But in addition to the details provided in this article, there is something that I’ve missed. I’m going to explain it in this post.

When I was implementing this feature for Axis2, the main objective was to make it easy and efficient to get the incoming JSON string from the service. That’s why I’ve used OMSourcedElementImpl with an OMDataSource. When a message comes in, JSONOMBuilder creates an OMSourcedElementImpl using JSONDataSource. So the OMElement is not built until someone forcefully do that and the JSON string can be directly accessed from the JSONDataSource without converting it to XML.

Due to this decision, the OMElement built from the incoming JSON message doesn’t know the namespace of the incoming payload. Therefore, if you try to dispatch a JSON message from the RPCMessageReceiver, it will be failed providing “namespace mismatch” error. Therefore, only the RawXMLInOutMessageReceiver can be used for JSON services. So you have to get an OMElement as the parameter for the method.

You can have a look at the JSONIntegrationTest to have an idea about this. All the other important steps are provided in the above article.

Apache Axis2/Java Performance Results

Few days back, I did a performance test on Axis2/Java to compare performances of different kinds of services that can be created using Axis2. I used a service using ADB databinding, another service using Jaxbri databinding and another service using JAXWS. For simple scenarios, I tested for POJO services as well.

Test setup

* Services hosted on Tomcat 6
* Axis2 version : Trunk
* Apache bench
* Concurrency level : 30
* Measure : Requests per second
* JDK : 1.6
* OS : Ubuntu 9.04
* Memory : 8GB

Scenario 01 : Echo Integer

Five digit integer was used.

Scenario 02 : Echo String

Length of the string was varied to create 1KB, 5KB and 10KB payloads.

Scenario 03 : Echo complex type

An array of complex type objects were echoed. Class hierarchy consists of three levels. Tested for ADB, Jaxbri and JAXWS services using the same WSDL. Payload size was varied by increasing the number of elements in the array.

How to generate your JAXWS service from a WSDL using wsimport

If you have a WSDL file and want to generate a JAXWS service/client, this post will help you. You can use the wsimport tool which is shipped with JDK (1.5 onwards).

Install JDK on your machine and just try “wsimport” command in a shell. It will show you the help.

Here are the options it provides.

Usage: wsimport [options] <WSDL_URI>

where [options] include:
-b <path> specify jaxws/jaxb binding files or additional schemas (Each <path> must have its own -b)
-B<jaxbOption> Pass this option to JAXB schema compiler
-catalog <file> specify catalog file to resolve external entity references supports TR9401, XCatalog, and OASIS XML Catalog format.
-d <directory> specify where to place generated output files
-extension allow vendor extensions – functionality not specified by the specification.  Use of extensions may result in applications that are not portable or may not interoperate with other implementations
-help display help
-httpproxy:<host>:<port> specify a HTTP proxy server (port defaults to 8080)
-keep keep generated files
-p <pkg> specifies the target package
-quiet suppress wsimport output
-s <directory> specify where to place generated source files
-target <version> generate code as per the given JAXWS specification version. version 2.0 will generate compliant code for JAXWS 2.0 spec.
-verbose output messages about what the compiler is doing
-version print version information
-wsdllocation <location> @WebServiceClient.wsdlLocation value

Examples:
wsimport stock.wsdl -b stock.xml -b stock.xjb
wsimport -d generated http://example.org/stock?wsdl

Just as shown in the above 2nd example, generate .java files as well if you want to create a service out of this. Among these generate classes, there is a generated interface of you web service. Just implement that interface and that is your web service class. Then add the @WebService annotation at the top as follows.

@WebService(
serviceName = “ComplexService”,
targetNamespace = “http://complex.axis2.apache.org”,
portName = “ComplexServiceHttpSoap11Endpoint”,
wsdlLocation = “ComplexService.wsdl”,
endpointInterface = “org.apache.axis2.complex.ComplexServicePortType”)

These details should be according to your WSDL’s definitions.

Hierarchical Service Support for Axis2

Until Axis2 1.5, service deployment in Axis2 has been flat and global. All services must be deployed in AXIS2_HOME/repository/services directory and it was really hard to manage services separately. Think about a situation where a large organization uses Axis2 to deploy a large number of services from different departments. They all have to agree on service names before deploying to avoid conflicts. And also supporting multiple versions of the same service was not possible without changing the service name in the services.xml file.

So how can we overcome this issue? Supporting hierarchical service deployment is the ideal solution to this problem. In other words, the ability to deploy services inside any prefered directory structure inside “services” folder.

Ex : repository/services/foo/bar/version.aar

In this case, the EPR for the service will be ../axis2/services/foo/bar/Version. This makes it extremely easy to manage services and it is the natural way of managing things separately. And also If you want to deploy two different versions of the same service without changing anything other than your business logic, it can be easily done as follows.

repository/services/foo/1.0.0/version.aar
repository/services/foo/1.0.1/version.aar

I’ve already implemented this feature in Axis2 trunk and you can try this by just building the trunk. And also, this will be there from the next Axis2 release which will be 1.6. Hierarchical support is there for AAR services and all other types of services like JAXWS, POJO etc.

Limitations :

[1] Maximum supported hierarchical depth is 10. In other words, you can deploy services only up to 10 directory levels starting from /services directory. This limitation was introduced to avoid possible performance issues.

[2] You can’t have a service and a sub directory from the same name within your service hierarchy.

Ex : If you have a service with the name “foo” (defined in the services.xml of foo.aar), you can’t have a sub directory “foo” inside the same directory.

repository/services/mark/foo.aar
repository/services/mark/foo/bar/version.aar

In this case, “foo” service and “foo” sub directory are inside the “mark” directory. In this case, requests coming into version service will be dispatched to “foo” services. Therefore, this kind of situations should be avoided.

Uses of different “lib” folders in WSO2 Carbon

WSO2 Carbon is the OSGi based platform for all WSO2 java products. In Carbon, there are four different “lib” folders. If you have ever tried any of the Carbon based products, you may have thought “why are there four different libs?”. If so, this post will provide you the answer for that question.

These are the “lib” folders that you can find in Carbon.

[1] CARBON_HOME/webapps/ROOT/WEB-INF/lib

Carbon is a web app which is deployed in an embedded tomcat instance. This is the lib folder which is specific to Carbon web app just like any other web app has in WEB-INF/lib folder. Bridge servlet is the one who forwards each and every incoming request into the OSGi environment of Carbon. We have used this lib to place our Bridge Servlet. Tomcat pics it up from there and hands over the incoming requests to it.

[2] CARBON_HOME/repository/components/lib

This is the place to put your normal jars if you want them to become pure bundles in the OSGi environment. All packages in these bundles are exported into the OSGi environment. As you may know, Carbon can be extended as you wish. You can add your own bundles into it. So If you have dependent jars for those bundles, you can place those in this lib.

[3] CARBON_HOME/repository/lib

This is the place where all client libraries exist. When you run ‘ant’ from CARBON_HOME/bin, all needed jars are put into this folder. If you want to write a client (or you can generate it using the WSDL2Java tool in WSAS) and test it, the set of all jars you need in the classpath can be found in this lib. For example, WSAS samples are run by adding all these libs into client classpath.

[4] CARBON_HOME/lib

This is the place where we put all jars which are needed by tomcat to start and some others for specific reasons. This is same as the Tomcat root lib. These libraries can be seen from all webapps deployed. And also, if you place the same jar in this lib and also inside Carbon web app, it will be picked up from this root lib as Tomcat uses parent first class loading.