machine501

It’s warming up in Los Angeles. Yay! So, before I take off for a nice walk along the beach I bring to you the second part in my series of flex+tomcat posts.

In this post I’ll create an Eclipse project for a simple web app and then hookup the Eclipse debugger to a possibly remote instance of Tomcat. The files are somewhat long so I’ve created a zip file that you can download and use. You’ll have to modify the paths to match your system paths.

I’m using Eclipse 3.1.2 on Windows XP with Java JDK 1.5.0.10 and the Tomcat from the previous post. My tomcat installation resides at “c:\java\tomcat\”
Startup Eclipse and create a new Java Project and call it “flex-auth-webapp”. Accept the default options.

Eclipse projects will output .class files either to the source directories or to a “bin” directory that is created during the project creation phase. When you modify a .java file in Eclipse it will recompile the file into the destination build directory. I want the class files to be generated in my webapp directory so that Tomcat can see the class file changes and then reload the webapp. This cuts down my write-test cycle because I don’t have to perform any manual or extra steps when I make a source modification. That’s the motivation for the following step: Create a webapp directory in the tomcat/webapps directory and then have Eclipse output class files into this folder.
In Eclipse, right-click on your new project’s folder and select New > Folder.

Click on the “Advanced >>” at the bottom of the dialog.

Check the checkbox that says “Link to folder in the file system”

Click the “Browse …” button.

Navigate to the tomcat webapps directory. Should should end up in c:\java\tomcat\webapps\ or whatever your path is.

Create a new directory called “flex-auth-webapp”. Then navigate into this directory, and create another directory, call it “WEB-INF”. Navigate into this directory and call it “classes”. You should end up with the following path:

c:\java\tomcat\webapps\flex-auth-webapp\WEB-INF\classes

If you don’t like clicking all these buttons it’s easier to just use the command line window and navigate to the path and then mkdir the path.

In the “Folder Name” text field enter “tomcat-classes”.

When you’re done, click “Finish”

You’ll see the folder inside the path with a little arrow that means this is a linked folder, outside of the project’s workspace directory.

Now we have to tell Eclipse to use this new folder, tomcat-classes, as the output folder. So, right click on the project’s folder and select “Java Build Path”. Select the “Source” tab. At the bottom, in the “Default output folder:” section click on “Browse…”. Pick “tomcat-classes” from the list and click OK. Click “OK” again on the project properties window.

Copy the files in the archive into your project. You should end up with the following project structure:

Let’s test that the project can be accessed over the web. I use ant for making my build process easier. It’s a great tool and if you don’t use it then first get familiar with it: http://ant.apache.org/
Open up the ant.properties file and change the path as appropriate for your system. You’ll probably only have to change the tomcat.home property. Be careful of extra spaces at the end of these paths because ant won’t take off trailing spaces.
After you’ve properly setup your paths, right click on “build.xml”, select “Run As > Ant Build …”. From the dialog, make sure that the target “deploy” is checked. It probably is because it’s the default target. Hit “Run”. Watch the Console for any errors. If you see errors, it’s very easy to click on the error message and jump to the line in the build.xml that threw the error. If everything went well there should be a success message at the end, and if you go to the c:\java\tomcat\webapps\ directory you should see a directory called flex-auth-webapps with the following directory structure:

If you haven’t already, startup tomcat and the go to the following location:

http://localhost:8080/flex-auth-webapp/

You should see the following page:

This is just a simple jsp page that creates a new class DebutTest and calls a method in it. I did this just so we could test the debugger in the next section.

Debugging With Eclipse.

There are several plugins available for eclipse that let you star and stop an instance of Tomcat from inside eclipse. One of these lets you debug jsps. You can find them on google. It’s not that hard to hook up Eclipse, however, so, why not do it manually. So, here goes:

Shut down tomcat if it’s still running. Then open up setenv.bat (or setenv.sh if you’re on a unix machine). Add the following lines:

SET JPDA_TRANSPORT=dt_socket
SET JPDA_ADDRESS=localhost:8000

This tells the JVM that will run Tomcat to use the socket transport during debugging and to listen to connections on port 8000 at the localhost address.

Now startup tomcat with the following command line:

catalina.bat jpda run

This tells tomcat to start in debug mode and to run on the same window. The first line of the console should say something like this:

“Listening for transport dt_socket at address: 8000″

This means Tomcat is now waiting for any debugger connections on port 8000.

Go over to Eclipse and select: “Run > Debug …”

In the dialog, look for the Configuration titled “Remote Java Application. Select it and click on the ‘New’ button.

Select the Project to “flex-auth-webapp”, select the Connection Type to “Standard (Socket Attach)”. In the connection properties make sure the Host is “localhost” and the Port is “8000″.

Click Debug. It will look like nothing will happen but if you go over to the Debug perspective you should see an instance of the Java HostSpot hooked to localhost:8000.

Let’s go put a breakpoint in a file and have Tomcat stop at that breakpoint. Open up the file test/DebugTest.java. Add a breakpoint on line 8. In a browser, navigate to http://localhost:8080/flex-auth-webapp/. Go back to Eclipse and the debugger should now be stopped at line 8 of DebugTest.java. You can now step through the lines and do whatever you’re used to doing while debugging java apps, including inspecting the variables, changing their values, adding watches.

Next Steps

In the next post I’m going to create a service and a flex app that accesses this service. This will be the app we’ll use to explore authentication and security in a Tomcat+flex application.

Ok, I’m off for a walk.

Code

flex-auth-webapp.zip

Tom at tombray.com and I will be heading to the 360 Flex Conference in March. I’m excited about going, partly because I’ll get to see what’s happening with Flex, but mainly because I’ll be close enough to Zachary’s in Berkeley to be able to drop by. Delicious deep dish pizza and a Fat Tire. One has to have priorities in life.

Anyway, in these series of posts I will be setting up a project that handles service authentication on RemoteObjects using FDS2 and Tomcat as our stand-alone j2ee server. The server setup will include the following:

• Tomcat 5.5 - http://tomcat.apache.org/
• Flex Data Services 2 - http://www.adobe.com/products/flex/
• and the file based user authentication that comes built in with Tomcat.

I’ll be doing all this on a windows machine so make sure to change the paths used here to the paths appropriate for your system.

Let’s get started:

Installing Tomcat 5.5

Download the Core Tomcat 5.5.X. I like downloading the Core zip file and installing Tomcat manually, but you can use the windows installer, just take note of the path where tomcat was installed. I installed Tomcat into the following path:

c:\java\tomcat\

Make sure tomcat works by running startup.bat (or startup.sh):

cd c:\java\tomcat
bin\startup.bat

Open up your browser and go to:

http://localhost:8080/

You should see the tomcat welcome page. Shutdown Tomcat for now by issuing this command:

bin\shutdown.bat

Additional Tomcat Requirements

You’ll need to install several 3rd party libraries to get Tomcat to run Flex, so let’s get those now:

Install JOTM, the Java Open Source Transaction Manager from this site:

http://jotm.objectweb.org/

Download the latest version. For this tutorial I used version 2.0.10. Open the archive to a temporary directory and copy all the files in the jotm/lib directory into tomcat’s common/lib directory:

c:\java\tomcat\common\lib

If you’re running java 1.4.x then you will have to install a Java Management Extensions (JMX) library. Go here:

http://mx4j.sourceforge.net/

And download the latest binary release version and extract the archive to a temporary directory. Copy all the files in the mx4j/lib directory into tomcat’s common/lib directory.

Increase the maximum memory for Tomcat to at least 512. On windows you should create a file called “setenv.bat” in tomcat/bin directory.

c:\java\tomcat\bin\setenv.bat

catalina.bat runs this file if it exists. We’ll use it to setup the memory requirements for the environment. If you do not increase the memory then Tomcat will run out of memory when it is trying to compile mxml files upon request. Open up setenv.bat in your favorite text editor and add the following line:

SET JAVA_OPTS=-Xms512m -Xmx512m

Installing Flex Data Services 2
Download and run the Flex Data Services 2 Express installer. When it asks you if you want to install with integrated jrun or with J2EE container I picked integrated JRun because I wanted to have a reference installation against which I could test the Tomcat installation. Regardless of which one you pick, the files that we are interested in for now, that is the samples.war file, will reside in the same location.
I installed FDS2 into c:\fds2\

Testing Flex on Tomcat

Ok, it’s time to get the flex sample files to run on our Tomcat installation. Copy the file

c:\fds2\samples.war

Into the tomcat webapps directory:

c:\java\tomcat\webapps

Startup tomcat:

bin\startup.bat

Open up your browser to the following location:

http://localhost:8080/samples/

You should see the Flex samples index page:

Run the Dashboard example. The first time you hit any example you’ll notice that the browser takes a long time to respond. This is because the container is compiling the mxml file on the first request. Subsequent requests should return the pre-compiled version.

UserTransaction

If you run the Flex Cab Dispatcher you’ll get a “Service Error: Unable to access UserTransaction in DataService.” This happens because we didn’t tell Tomcat what factory to use for the UserTransaction service.

Go to the directory:

c:\java\tomcat\conf\Catalina\localhost

create and edit a new file called “samples.xml”. The name of the file must match the name of your webapp. Add the following code to the file:

<Context docBase="${catalina.home}/webapps/samples"
             privileged="true"
             antiResourceLocking="false"
             antiJARLocking="false">
     <Transaction factory="org.objectweb.jotm.UserTransactionFactory" jotm.timeout="60" />
</Context>

If the file already exists, then just add the Transaction element.

Restart tomcat and go back to the Flex Cab Dispatcher. Check that the Service Error no longer appears. Run the FlexCab Driver and connect. Then make sure that the Dispatcher and the Driver can talk to each other.

More Error Info in the Tomcat Console
Keep an eye on Tomcat’s console output for useful information about possible errors. For example, the first time I ran the Cab Dispatcher sample I got an exception in the browser window telling me that it had “failed to grab pixels for image: …”. When I looked in the console I saw that there was a java.lang.OutOfMemoryError: Java heap space. This happened because I didn’t increase Tomcat’s heap space in setenv.bat, as I specified earlier.
Installing on OS X

I tried installing FDS2 into my OS X Tomcat development environment. There prpocess is the same, except when it comes to downloading and running the FDS2 installer; there is no installer for FDS2. So, I just copied the samples.war files from my windows installation to the tomcat install and followed the rest of the process above and it worked.

Next Steps

On the next part of this series I will create a small flex application that we’ll use as the foundation for the authentication application. In the process I’ll setup tomcat to debug via eclipse and create an ant file that will help us in building and deploying the application.