I needed to set up a simple distributed system consisting of an outward facing, secured IIS 6 web server and an internal, dedicated Flex server running under Tomcat 5.  There is a lot of documentation out there but that in itself is a problem.  It is difficult to know what really applies and what is out of date.  I just successfully set up several such systems using the Tomcat <==> IIS connector.  Following are the steps I took, and comments and tips about what I have learned.

Here is a link to the connector documentation index, if you want to do this the hard way:

http://jakarta.apache.org/tomcat/connectors-doc/

First the problem in a nutshell:

You can happily call your Flex applications from an IIS application (like ASP.NET) on an internal development system by using the host name (or IP address) and the port number.  For example, in a custom wrapper this will work: http://myFlexServer:8080/flex/myApp/myFile.mxml.  However, if you try to use that custom wrapper from outside the firewall, in other words, from the internet, you will find that port 8080, and most others, are blocked, and you cannot access your Flex application.

One solution is a "Jakarta Tomcat Connector", which directs calls to your Flex app through the IIS web server to the Flex/Tomcat server.  You can do the same this with JRUN, and, I suspect, other J2EE servers as well.  This connector allows you to use the IIS web server in the URL  to the Flex app, without requiring any port specifications to gag the firewall.  So the URL  to a Flex app like in the example above becomes: http://www.myIISWebServer.com/flex/myApp/myFile.mxml.

How does a “connector” work?  There are IIS and Tomcat parts.  The Tomcat side is already set up for you in ...\Tomcat 5.0\conf\server.xml, whose job it is to create Tomcat "listeners" on specified ports.  It sets up the normal listener on, for example, port 8080, but it also sets up a special listener on port 8009.  In fact, if you have the Tomcat log level set to "Info" (the "Monitor Tomcat" menu/dialog, logging tab), you can look in the log: ...\Tomcat 5.0\logs\stdout.log, and see the line: "INFO: JK2: ajp13 listening on /0.0.0.0:8009"

But you can really just trust me, it is there.

On the IIS side, the connector works by using an "ISAPI" filter. This "filter" watches URL s for certain "contexts", and passes those contexts on to the specified handler dll.  The simplest "context" is one of the folders under the Tomcat "webapps" folder.  For example, /flex/, and /samples/ (yes, these are the folders you think) are Tomcat contexts in a default flex install.

Setting up IIS to use Tomcat connector

You actually have to do some work now, but not as much as you would think by reading the documentation.

Note:  You want to be working with the “JK” connector, NOT the JK2 connector, which has been deprecated.  Never mind that the log shows JK2, or that there is a jk2.properties file in the Tomcat\conf folder, and that a google search will turn up a lot of people still using JK2.

First, obtain the connector installer: isapi_redirect-1.2.14.exe  It is available from several locations including:

http://www.devlib.org/apache/jakarta/tomcat-connectors/jk/binaries/win32/jk-1.2.14/

Now run the install. There does not appear to be any documentation for the installer, but here is a link to a document that describes the manual method of what the installer does, plus troubleshooting and general info, just FYI.

            http://jakarta.apache.org/tomcat/connectors-doc/howto/iis.html

Briefly, the install creates a folder structure and adds a few files to it, sets some registry entries, creates an IIS virtual directory, adds the isapi_redirect.dll to the IIS website ISAPI filters tab.  It should take care of all the steps listed in the above howto document under "Configuring the ISAPI Redirector".

Next add a Web Service Extension.  This needs to be done manually because the install works for IIS 5 and 6, but “Web Service Extension” only applies to IIS 6.

• Open the … Administrative Tools, Internet Information Services console.
• In the tree on the left, click ” Web Service Extensions”
• In the right hand pane, click “Add a new Web Service Extension”
• For the Extension Name, enter: Jakarta Tomcat
• Click the “Add” button.
• Browse and select C:\Program Files\Apache Software Foundation\Jakarta Isapi Redirector\bin\isapi_redirector.dll
• Click the “Allow” button.  DO NOT MISS THIS STEP!
• From the “Services”  MMC, restart “IIS Admin”

Now, the install defaults to looking for a Tomcat listener on localhost.  If your Tomcat is on a different server, as mine was, you will need to make a simple edit.

On the IIS web server, edit:

C:\Program Files\Apache Software Foundation\Jakarta Isapi Redirector\conf\workers.properties.minimal

Change the line that says:

            worker.ajp13w.host=localhost

To:

            worker.ajp13w.host= www.myIISWebServer.com

You can also use an IP address.  I do not know if a machine name will work.

Restart IIS.

At this stage we can test the tomcat examples, using this URL :

            http://www.myIISWebServer.com/jsp-examples/index.html

If it loads we are good to continue.  If not, you will need to look at the troubleshooting section of the howto/iis.html document.

If we are good to continue, we will next add the flex “context”.  The following assumes a default Flex install, with your application in:

...\Tomcat 5.0\webapps\flex

Adding the "flex" context:

On the IIS web server, edit:

C:\Program Files\Apache Software Foundation\Jakarta Isapi Redirector\conf\uriworkermap.properties

In the # [URL ]=[Worker name] section, add this line:

            /flex/*=wlb

Save the file.

Restart IIS.

Finally, test the connector with Flex using an URL  like this:

            http://www.myIISWebServer.com/flex/myApp/myFile.mxml.

Security caveat:

In our setup, where the flex app was called from a custom wrapper in a tightly secured ASP.NET application, adding the connector / isapi redirector had the consequence of breaking the security on the Flex app because it can be called directly from the web.

The ideal solution would have been for the Tomcat container’s authorization module to read the ASP.NET forms security token to permit access.  Regretfully, I have not been able to make this work yet.

Tracy Spratt