Axis2/C Deployed in Microsoft Internet Information Services (IIS) Family

This article by Supun Kamburugamuva touches Axis2/C and IIS ISAPI technologies and goes on to explain how these two technologies can be combined to create a rich communication platform.

Introduction

Microsoft Internet Information Server (IIS) is a popular Web Server. IIS provides a rich set of functionalities to create communication platforms of dynamic nature. ISAPI, CGI, FCGI, ASP.NET are some of the widely used tools by dynamic content generating applications to use IIS as a gateway to the HTTP world. Axis2/C is a popular Web Services Engine written in C and delivers and consumes Web services using protocols such as HTTP, TCP and AMQP. Axis2/C can be deployed in IIS 5.1, 6 and 7 using the ISAPI technology. Axis2/C uses the HTTP protocol when deployed in IIS.

Applies To

Table of Contents

• Overall Architecture
• IIS Web Development Technologies
  
  • ISAPI Filters
  • ISAPI Extensions
• Axis2/C Requirements
• Axis2/C ISAPI Module
  
  • Desing
  • Implementation
• Configurations
• Summary
• References

Overall Architecture

IIS serves deployed content through the Hyper Text Transfer Protocol (HTTP).  Usually the content served by IIS is in the format of Hyper Text Markup Language (HTML). Web browsers requests HTML content via HTTP and servers respond by delivering requested content, again via the HTTP. Web servers like the IIS have the ability to create responses from both static content as well as using dynamic content generation applications. Some of the most popular dynamic content generators for the Web are PHP, ASP.NET, Perl, Python etc.

In terms of Web services, the overall picture is more or less still the same. Instead of requesting HTML content via HTTP, Web services clients requests XML content (SOAP) via HTTP and Web Server generates this content by using Web service Engines as dynamic content generators. When authors of  Web services deploy services in Web servers, it is similar to the .PHP files that you deploy when generating dynamic HTML. The difference is that Web services can be consumed not only using HTTP, but also using other protocols such as SMTP, TCP, AMQP etc. This means that Web services are independent of transports.

In our case, Axis2/C is the dynamic content generator and the content generated is in XML format. The diagram below illustrates the overall architecture of the connection between Axis2/C and IIS.







Here, we can see that the IIS is the front end for the Web service's client. The client talks to the IIS using HTTP and the IIS hands them over to Axis2/C for processing. Although, actual Web services are deployed in Axis2/C, clients see them though they are deployed in the IIS. The clients do not see the Axis2/C engine.

IIS Web Development Technologies

Let us now look at what options are available for Axis2/C and IIS to talks to each other. As I've mentioned earlier, IIS offers different ways to extend its functionality. Because  Axis2/C is written in C, we cannot use technologies like ASP.NET or ASP. With ISAPI and CGI modules written in C/C++ - these are the only options available for us.

There are some limitations with CGI that makes the connection between Axis2/C and IIS inefficient. With CGI, each time a request comes to Axis2/C, IIS creates a new process to load Axis2/C, then process the request using Axis2/C and returns the result. This creation of new process for every request and loading of Axis2/C from the scratch is inefficient and not suitable for a high performance Web service engine like Axis2/C.

So we are down to one option; Internet Server Application Interface (ISAPI). IIS exposes two development technologies for ISAPI. These two are ISAPI extensions and ISAPI filters. ISAPI extensions and ISAPI filters are DLL files that should be developed using C or C++ that provides the maximum control over the IIS for a module writer. ISAPI modules are loaded by IIS and unlike with CGI, IIS uses threads to isolate and synchronize the processing between separate requests for ISAPI. These features are ideal for Axis2/C. 

ISAPI Filters

ISAPI filters are used for lightweight tasks such as modifying or enhancing the IIS server functionality. They are loaded by the IIS when the server starts and remains loaded until it shuts down. Filters receive every request that comes to the server and it is up to the filter to decide the requests that needs processing. It is not recommended to use ISAPI filters for tasks that require heavy processing.

ISAPI Extensions

ISAPI extensions can handle incoming requests to the IIS server. Extensions are loaded by the IIS as and when they are requested, and usually stay put until the server shuts down. ISAPI extensions are called when a request mapping to a specific DLL arrives at theserver. Usually the IIS is able to figure out which ISAPI extension needs to be called, by mapping URL extensions to a DLL name. For example, an ISAPI extension can be written to handle request for URLs ending with “.abc”.  In this case, the IIS should be configured to call the specific DLL for the  ”.abc” extension. Also, ISAPI extensions can be called directly by specifying the full name like http://iiswebserver/myapp/isapiextension.dll.

With the IIS version 6 and later, ISAPI extensions can be designed to handle all incoming requests as well. These special types of extensions are known as Wildcard Script Maps.

Having recognized the two technologies used by the Axis2/C to connect to IIS, let’s now look at the requirements of Axis2/C. 

Axis2/C Requirements

A typical HTTP request for Axis2/C is a POST request with a URL and a SOAP message (XML). Below, I have given both HTTP headers and content as they appear in a request.

POST /axis2/services/math HTTP/1.1
User-Agent: Axis2C/1.4.0
Content-Length: 264
Content-Type: application/soap+xml;charset=UTF-8
Host: 127.0.0.1:9090

<soapenv:Envelope xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope">
    <soapenv:Header></soapenv:Header>
    <soapenv:Body>
        <ns1:add xmlns:ns1="http://ws.apache.org/axis2/services/math">
            <param1>40</param1>
            <param2>8</param2>
        </ns1:add>
    </soapenv:Body>
</soapenv:Envelope>

To deploy Axis2/C in a Web server, the following requirements should be met:

1. There should be a way to recognize requests specifically targeting the Axis2/C engine (Axis2/C is not the only thing deployed in a Web server) to allow such requests to be handed over to Axis2/C for further processing.
2. Axis2/C should be able to read data from the incoming request. This includes both HTTP headers and data.
3. Axis2/C should be able to send responses back. This too includes both HTTP headers and data.

Having recognized the requirements, let us now look at how they are met in the Axis2/C ISAPI module.

Axis2/C ISAPI Module

The module is designed as a ISAPI filter + ISAPI extension. The extension is common to all versions of IIS and the filter is used only in the IIS 5.1.

Design

Axis2/C involves heavy processing. This means a filter is not suitable for the handling of processing in Axis2/C. So the processing should be done by an ISAPI extension as they are designed for tasks involving high processing. But with IIS 5.1, there is no a way to configure the IIS to call the ISAPI extension DLL for Axis2/C requests. As you can clearly see, there is no extension component in the request URL. Usually, the IIS uses this extension to map a request to an ISAPI DLL.. But as Axis2/C doesn’t have an extension and the request URL is user configurable - there should be another mechanism for IIS to decide whether the request is for Axis2/C or not.

IIS 5.1

With IIS 5.1, an ISAPI filter is used for mapping incoming requests to the ISAPI extension. The mapping is simple. The filter assumes a fixed location for the ISAPI extension DLL, which is.  /axis2/mod_axis2_IIS.dll. Since the filter is accessed for every incoming request, it can choose the requests to be processed by examining the full URL. If the request is for Axis2/C, filter modifies the incoming URL to point to the ISAPI extension DLL. This ensures that the extension DLL is only called for the Axis2/C requests. When processing arrives at the extension, it then extracts the relevant information from the IIS and calls Axis2/C. When Axis2/C completes processing, the extension again extracts the properties from the Axis2/C engine and returns the response. This functionality in the extensions is common to all the versions of the IIS.

Note that both ISAPI filter and extension are built into a single DLL.

IIS 6 & 7

Filter component of the ISAPI module is not used with IIS 6 & 7. Instead a Wildcard Script Map is used for filtering incoming requests. So, we have a single ISAPI extension that does both incoming request filtering and processing. A Wild Card Script Map extension is also an ISAPI extension. In IIS configuration, we can specify a particular extension as a Wildcard Script Map. When we configure the IIS for recognizing a DLL as a Wildcard Script Map, the extension is called for every request. Now, in this single extension, we check incoming requests for Axis2/C. If the request is for Axis2/C we hand over the request to Axis2/C.  If the request is not for Axis2/C, it is passed over to the IIS to be handed over to the appropriate processor. 

Implementation

It is easy to write ISAPI modules. As I have previously mentioned ISAPI extensions and filters are DLL files. IIS expects a set of functions implemented and exported by every ISAPI DLL. These functions are called entry point functions and are called by IIS in different stages. Some of these functions are called when IIS starts, some are called when IIS process a request. It is up to the module writer to use the information passed by IIS and do the required processing. 

ISAPI Filter

An ISAPI filter DLL file should expose three entry point functions. These functions are used by IIS to initialize, notify and terminate the filters. TerminateFilter funtion is optional.

BOOL WINAPI GetFilterVersion(PHTTP_FILTER_VERSION pVer);
DWORD WINAPI HttpFilterProc(PHTTP_FILTER_CONTEXT pfc, DWORD notificationType, LPVOID pvNotification);
BOOL WINAPI TerminateFilter(DWORD dwFlags);

Now I'll explain how these functions are used in IIS 5.1 as filter is used only in that version.

GetFilterVersion

The GetFilterVersion is the entry point function to the DLL and it is called when IIS first loads the filter. In this function we register the filter to listen to the important event

SF_NOTIFY_PREPROC_HEADERS

This event occurs immediately after IIS has pre-processed headers, but before IIS has begun to process header content. This gives us the chance to change the URL header to point to the ISAPI Extenstion.

Also we set the filter notify order to high by using

SF_NOTIFY_ORDER_HIGH

This ensures that our filter gets a higher precedence.

HttpFilterProc

For every notification event that the filter is registered in the GetFilterVersion function HttpFilterProc function is called. Inside this function actual modification of the headers happens.  After the modifications we allow IIS for further process the request.

TerminateFilter

This function is not implemented because the module doesn’t initialize anything in the filter initializing function.

ISAPI Extension

ISAPI extension DLLs should expose three entry point functions. These functions are used for initializing; perform processing and terminating the extensions. TerminateExtension function is optional.

BOOL WINAPI GetExtensionVersion(HSE_VERSION_INFO* pVer);
DWORD WINAPI HttpExtensionProc(LPEXTENSION_CONTROL_BLOCK lpECB);
BOOL WINAPI TerminateExtension(DWORD dwFlags);

Extension is the place where all the major processing happens. Infact with IIS 6 & 7 we only use the extension part.

GetExtensionVersion

This function is used for extension version initialization with the IIS server. It is not used for any Axis2/C related initializations.

HttpExtensionProc

When a request comes to the extension IIS calls this method with the appropriate information.  All the actions in the extension flow diagrams are done inside this method.  IIS passes information about the request inside the EXTENSION_CONTROL_BLOCK structure to this function.

EXTENSION_CONTROL_BLOCK is a fairly large data structure with all the things that are needed by an extension writer. It has

1. Data fields that contain information about the HTTP request and the server.
2. Functions that can be used to retrieve information. This includes functions for reading the incoming request and accessing the various server variables.
3. Functions that can be used to send information to the client.

Here I’m not going to explain all these things in details as it is not covered in the scope of this article.

The module doesn’t have to be built separately for different versions of IIS. It figures out the IIS version dynamically and acts accordingly. Also we use the same extension with all the versions of IIS.

Now we know how Axis2/C and IIS talks to each other internally. So let’s take a look at how we can configure Axis2/C and IIS to work together. 

Configurations

The module is written to read configurations from the Windows Registry. So the user has to enter some values in to the registry. The easiest way to do this is to use the Jscript file provided with the distribution. Name of this file is axis2_iis_regedit.js and it can be found in the root directory of the binary distribution or in the source directory of the IIS module. If this file is in the root directory of the binary distribution double clicking it will set up the registry entries to the default values. If you want to change the default values there are two options. One is to edit the js file which is very easy and the other one is to give the values as command line arguments to the JSCript file. You can use the command $:\cscript axis2_iis_regedit.js to execute the file from the command line.

Following table lists the registry values needed for configuring the Axis2/C IIS Module. All these are string values. The registry location should be HKEY_LOCAL_MACHINE\Software\Apache Axis2C\IIS ISAPI Redirector.

These configuration values are common to all the supported IIS Versions.

Now lest look at how to set up Axis2/C in different versions of IIS. All these configurations are done through the IIS management console. The name of the ISAPI module it mod_axis2_iis.dll and when you build the module the DLL file is in the %AXIS2C_HOME%\lib folder.

IIS 5.1

We need to add a virtual directory to the Web Site that we are going to host Axis2/C. The name of the directory should be “axis2” and it is not configurable. Physical path of the virtual directory should be the directory in which you placed mod_axis2_IIS.dll. When creating this new virtual directory, make sure to assign execute access to it. This is the constant place (extension DLL is here) that we are going to redirect from the filter.

Now we need to add the mod_axis2_iis.dll as a filter to the IIS. Name of the filter can be any meaningful name. After all the configurations restart the IIS Admin Service.

IIS 6 & 7

The configuration is simple in IIS 6 and 7. All you need to do is to add the mod_axis2_iis.dll as a Wildcard Script Map to the IIS.

If the configuration is correct, typing http://localhost/axis2/services in the browser should display the list of services deployed.

Summary

In this article I have looked at the internals of how Axis2/C and IIS connects to create a rich Web services platform. I have also explained the configurations that are required to make that work.

The sole purpose of writing this module was to create new opportunities for the IIS user willing to use open source software, to create their Web services. So, if you want to create fast and robust Web services at no cost, you have the recepy to get started.

References

• Apache Axis2/C
• IIS Web Devepment Technologies
• ISAPI Extensions
• ISAPI Filters
• Apache Axis2/C Manaul

Author

Supun Kamburugamuva, Software Engineer, WSO2 Inc. supun AT wso2 DOT com