Learning axis2.xml - Part1
By Deepal Jayasingha
- 30 Aug, 2008
When we look at the Apache Axis2 deployment model, we see three main configuration files that can be used to:
- Configure a service
- Configure a module and
- Configure the whole system.
In this tutorial we will discuss axis2.xml, the configuration file used for the configuration of the entire Axis2 deployment system. Specifically, we will look at some of the most important axis2.xml parameters as well as their usages. Towards the end of this tutorial, you will be able to configure axis2.xml using your own parameters, and customize the behavior of Axis2 Web services engine.
If you look at axis2.xml configuration file, you will see, that one of the most commonly used elements is the parameter element. In Axis2, you could have parameters at different levels, where the parameters are configured differently based on the level. For example, you can have a parameter called “foo” in axis2.xml with the value “xyz”, where you override that same parameter in a service by adding another parameter with the same name and a different value.
In my personal view, I see parameters as one of the very powerful tools in Axis2, specially considering that we can extend and customize Axis2 with zero code changes using these parameters.
The structure of a typical parameter is shown below. It has a name and a value:
However, you can have very complex parameters as well, in that case the value of the parameter could be a complex XML element.
In addition to name attribute in the parameter element, you can have an optional attribute called “locked” as well. The idea of a locked attribute is, to make sure that no one can override the value of the parameter (because as I mentioned earlier there are instancez where servicez override global parameters). So a parameter with a locked attribute will look like the following:
<parameter name=”foo” locked=”true”>xyz</parameter>
Note : Value of the looked attribute can be either “true” or “false”
By default, axis2.xml has a number of parameters that you can use to configure the behavior of the system. Now let's look at them and see how we could nfigure them:
By changing the value to “false” or “true” you can turn-off and on the hot-deployment feature in Axis2.
In the same manner, if you want to turn-on or off the hot-update feature then you can use the following parameter:
If you want to configure the lifetime of a SOAP session, then you can do that by configuring the time that you want the session to exist, by using the following parameter. Time is given in milliseconds.
By changing the following parameter, you can configure the fault handling mechanism in Axis2, in other words you can tell Axis2 whether you want to send the stack trace with the fault or not.
If you have deployed Axis2 in any application server, such as Tomcat or Jboss, then you might know that anyone can login to the your system using the default user name and password. However, following two parameters help you to change the default password and username of the administration console of Axis2.
<parameter name="userName">admin</parameter> <parameter name="password">axis2</parameter>
When you integrate Axis2 with any application server, and Axis2 generates a service URL, by default it will put “axis2” as the root. If you need to change that, then you can do so by changing the following parameter with the value you need.
In the same way when Axis2 generates a service URL, it adds “services” in the middle for dispatching purposes. However, you could also configure that using the following parameter:
Change the parameter to the service path and context root you want , then Axis2 will generate a customized service address as well as dispatch the service to the right location.
When Axis2 generates the WSDL for a given service , it generates three bindings by default. So if you look at a auto-generated WSDL file, then you can see that it has three bindings as well as corresponding service address for them. However, there are instances where you do not need to generate all three bindings and you need to configure that. So the following three parameters help configure the WSDL generation behavior in Axis2.
To disable the REST or HTTP binding generation
<parameter name="disableREST" locked="false">true</parameter>
To disable the SOAP 1.2 binding generation
<parameter name="disableSOAP12" locked="true">true</parameter>
To disable the SOAP 1.1 binding generation
<parameter name="disableSOAP11" locked="true">true</parameter>
If you are running behind a proxy or if you have a public domain name, and you want Axis2 to generate its service URL with your own address, then you can do that by adding the following parameter. As I mentioned , this is very useful if you are running behind a proxy , then you can have the address of the proxy as the value in the following parameter. If you let Axis2 generate the service URL, it will generate that using the server's IP address, but no one will be able to access the service from that address. So the following parameter is extremely handy in that scenario.
In addition to these top-level parameters we discussed, there are a number of other parameters in axis2.xml inside some other elements. You can learn them in the next part of the tutorial.
As we know by now, there are a number of parameters that you can use to configure Axis2. Some of those parameters may be used at deployment time and some othjers at the runtime. Irrespective of the usage of these parameters, Axis2 allows you to configure them as you wish. In addition, you can also add new parameters into axis2.xml and use them in your services, modules and handlers.
Deepal Jayasinghe , Tech Lead , deepal [AT] wso2 [dot] com