2007/09/23
23 Sep, 2007

Web Services Endpoints with Apache Axis2/C

  • Samisa Abeysinghe
  • VP, Training - WSO2

Introduction

Web services enpoints in Axis2/CThere were several queries over the developer and user mailing lists of Apache Axis2/C on the ability to customize the endpoint address format of hosted services. While answering those queries over the mailing list, I happened to look into the implementation in great detail that expanded my know-how on dealing with concepts related to endpoint addresses in Apache Axis2/C. I fixed a few existing bugs, updated the documentation and then thought of writing on the topic in more detail, hence resulted in this article.

Starting from the version 1.1.0, Apache Axis2/C would have much flexibility in terms of being able to customize the endpoint URL where a service would be hosted.

Applies To

Apache Axis2/C 1.1.0
Environment Any

Endpoint URL Format

With Apache Axis2/C, when you run samples, the default service endpoints are of the form:

https://[host]:[port]/axis2/services/[service_name]

[host] is the host name on which you run the server where the services are hosted.

[port] is the port on which you run the server.

[service_name] is the name of the service that you want to access.

As an example, with the simple axis2 server, to consume the echo service, you can run the echo client against the endpoint

https://localhost:9090/axis2/services/echo

With the Apache2 httpd module, assuming that you run the Web server on port 80, the endpoint for echo service could be

https://localhost/axis2/services/echo

To access the math service, you have to replace echo in the above endpoint with math

With the endpoints, it may seem that the segment, /axis2/services, the prefix of the service, to be hard coded. The question is, can one customize that segment, in other words, can that be changed as the user desires?

The answer for the above question was 'no', prior to the 1.1.0 release of Axis2/C. However, with Axis2/C 1.1.0 release, this segment too can be configured to make the service endpoint customized.

Endpoints with Simple Axis2 Server

With simple axis2 server, the only mandatory part of the endpoint address is /services segment. When the URI dispatcher searches for the service being invoked, it uses /service as the prefix to parse the endpoint address and to locate the service. In other words, anything following /services would be considered the service name.

In line with the above description, it is not a must to have /axis2 segment in the service endpoint address when using the simple axis2 server. Hence both https://localhost:9090/axis2/services/echo and https://localhost:9090/services/echo would point to the same service, namely echo.

In fact the URL https://localhost:9090/[anything_here]/services/echo would always point to the echo service with simple axis2 server.

Compile Time Configuration

The question is, can one customize it to replace /services with a custom value? From 1.1.0 release, the answer is, 'yes you can'.

How can one do that. Well, either you have to edit the source and change the value of the macro AXIS2_REQUEST_URL_PREFIX in the header axis2_const.h or set the CFLAGS environment variable on Linux before configuring.

Example:

export CFLAGS="-g3 -O0 -DAXIS2_REQUEST_URL_PREFIX='\"test\"'"

Then follow the normal make and install operations. It is recommended not to edit the source, but rather to use CFLAGS when configuring Axis2/C. On Windows, you can edit the makefile in build\win32 folder and add the AXIS2_REQUEST_URL_PREFIX macro with the value you desire to the CFLAGS variable.

You will notice a major limitation when customizing the service endpoint prefix location with simple axis2 server. That is, it can only be done at compile time and not through a configuration file at runtime. Yes that is a limitation, if you want to customize the service endpoint, you have to rebuild form source. However, this limitation only applies to the simple axis2 server. If you are using the Apache2 httpd module, everything could be configured using configuration files hence no need of recompiling. This is a reasonable solution, because the simple axis2 server would hardly be used in production.

Endpoints with Apache2 httpd Module

With Apache2 httpd module, you get the luxury of configuring the way how the service endpoints look the way you want.

First, lets see the elements in the Apache2 httd module configuration that are to be included in httpd.conf configuration file that deals with the format of the service endpoint addresses. Please see the documentation for more details on Axis2/C httpd module configuration options.

When you configure httpd.conf to include Apache Axis2/C as a module, you add a <Location> entry similar to the following:

<Location /axis2>
SetHandler axis2_module
</Location>

The /axis2 path in the starting tag of the location entry tells httpd Web server that any request directed to the root resource of axis2 should be handled by Axis2/C module. In other words, it says that any Web service endpoint address hosted with this Web server has to start with axis2. Hence, unlike in the case of simple axis2 server, the starting axis2 part of the endpoint address is not optional.

In addition to this, the Axis2/C engine, uses /service as the service URI prefix to find the name of the service to be invoked form the endpoint address as mentioned earlier. Hence, with the default configuration, the endpoint address must start with /axis2 and the service name has to be prefixed with /service.

Hence, assuming httpd runs on port 80, the URL https://localhost/axis2/services/echo would point to the echo service with the Axis2/C httpd module. And to be more generic, the following URL would always represent the echo service with the Axis2/C httpd module:

https://localhost/axis2/[anything_here]/services/echo

Changing axis2 Refix

The first interesting question is, can we have something other than axis2 s the starting element in the endpoint address? The obvious answer is yes, and it is trivial how to archive this. Change /axis2 part of the <Location> element that you added to httpd.conf file.

As an example, if you want the echo service endpoint address to look something like:

https://localhost/foo/services/echo

then edit the <Location> element of Axis2/C module in Apache httpd.conf file to:

<Location /foo>
SetHandler axis2_module
</Location>

Changing services Prefix

The second interesting question is, can we have something other than services s the service prefix in the endpoint address? The answer is, again, 'yes'. Starting form the Axis2/C release 1.1.0, this would be possible, thanks to a new configuration element introduced to be added to httpd.conf, named Axis2ServiceURLPrefix

Now if you want the echo service endpoint address to look something like:

https://localhost/foo/bar/echo

then edit the Apache httpd.conf file to include the following elements for the Axis2/C httpd module:

Axis2ServiceURLPrefix   bar
<Location /foo>
SetHandler axis2_module
</Location>

The rationale of the setting is trivial, use foo as the start element of the endpoint address and use bar as the service prefix.

Now you know that you can configure the service endpoints the way you want with the Apache Axis2/C httpd module.

Fancy Endpoint Addresses

If you want a more fancy looking URL format in your endpoint addresses, you can do that too.

As an example, if you have the following in your Apache httpd.conf file:

Axis2ServiceURLPrefix   bar/beta
<Location /foo/alpha>
SetHandler axis2_module
</Location>

Then the echo service endpoint address would look something like:

https://localhost/foo/alpha/bar/beta/echo

One Prefix in Place of Both axis2 and services

There would be one more interesting question that you may raise. Can we merge the endpoint start element and the service prefix, so that we would not have to have two mandatory elements in the service endpoint address? In other words, can the echo service endpoint address look something like:

https://localhost/foo/echo

The simple answer is 'yes'. And this is how you do it, use the same values for both the location element and the service URL prefix.

As an example, Apache httpd.conf file could be edited to include the following elements for the Apache Axis2/C module:

Axis2ServiceURLPrefix foo
<Location /foo>
SetHandler axis2_module
</Location>

Cannot Drop axis2 Prefix

One last question, that I would have to answer, 'no', is that can we drop the endpoint start element that we provide in the <Location> element. In other words, an the echo service endpoint address look something like:

https://localhost/echo

This can be done, using the following configuration:

Axis2ServiceURLPrefix   /
<Location />
SetHandler axis2_module
</Location>

However, because Axis2/C requires some form of service endpoint prefix, this setting causes service invocations to fail in some cases like the REST HTTP GET method. Hence, it is recommended not to use the above setting, even for the subset of cases that it works. The key argument against using this setting, is that when you set the above, all requests that come to the httpd Web server, with which you have deployed Axis2/C, gets directed to the Axis2/C module to be dealt with. Hence, you will not be able to host any other documents or modules with the Web server. Also, it is not a good idea to use the document root as the module's root location, as the Web server implementation may have made some assumptions on that. In fact, when I used the above settings, I ran into undefined behavior in case of the math sample. I did not invest time to investigate in depth on this, as it is highly unlikely one would want to have such an endpoint address format requirement in a production environment.

Conclusion

Starting form the release 1.1.0, Apache Axis2/C have let the user decide the format of the endpoint address to be used for the service deployments. The greatest flexibility could be achieved by using the Apache Axis2/C httpd module for deploying the services. Deploying with Apache2 httpd Web server is the more viable solution for those who want to deploy Apache Axis2/C in enterprise production environments.

Resources

Apache Axis2/C official Web site - http://ws.apache.org/axis2/c/

Axis2/C downloads - http://ws.apache.org/axis2/c/download.cgi

Axis2/C Mailing lists - http://ws.apache.org/axis2/c/lists_issues.html

 

About Author

  • Samisa Abeysinghe
  • VP, Training
  • WSO2 Inc.