Monday, March 17, 2008

Jboss Eclipse and BlueDragon

With the recent news of BlueDragon JEE edition releasing a new focus has been put on this type of environment. This is a GOOD thing in my eyes, I am a firm believer in knowing the underlying implementation of what you are working on. I'm not saying you should be a Java expert but if i say something like context path or context root I'd like folks to understand what that is, maybe even the different between and EAR and WAR. Enough of my soap box lets get into the nitty gritty there are whole bunches tutorials and FAQs out there about JBOSS and JEE servers and the like but few from a ColdFusion perspective consider this the first of many entries on this topic. Today I am going to focus on getting BlueDragon installed in Jboss and eclipse configured to start and stop jboss! By the way MOST of the below directions are perfect for ColdFusion as well. OK things you will need:

  • Jboss (preferable 4.2.2GA) - if sourceforge intimidates you or you just want the download use this link.
  • Eclipse w/ WTP - This can be a bit intimidating the all in one package is here For those do it yourselfers WTP info can be found here
  • BlueDragon (J2EE edition) - you will need and account, they don't bug you (at this point you could also download the ColdFusion installer).
  • Java SDK (or JDK), I like Java 5 - It will be the 3rd link JDK 5.0 Update 15 (at the time of this writting).

Now that we have this all downloaded lets get to setting everything up.

Installing the Necessary Software
1) Install the JDK, the defaults are fine.
2) Creat a directory somewhere free of spaces, I like c:\tools or c:\IDE or /usr/tools/
If you already have eclipse installed you can skip this step if you'd rather not move eclpse
3) Extract Eclipse into the tools directory, at this point eclipse is ready to run. If you already have eclipse you will want to get the WTP project installed into eclipse at this point*.
4) Extract the Jboss directory into the tools directory, or else where. I like putting all my developement tools in the same place as siblings. In reality so long as all these pieces are installed into paths that are devoid of spaces you can put them all anywhere you want
5) Extract the BlueDragon Zip into its own directorty on the desktop. At this point if you are wanting to use ColdFusion you would run the CF8 installer and choose an WAR deploy (if you are using updater 1 an EAR deploy would be a better option).
6) Inside the extracted directory you should find a directory named something like BlueDragon_webapp_701_352 rename it to bluedragon.war
7) Take that newly renamed directory and place it into this path: {jboss folder}/server/default/deploy , if you used tools and jboss 4.2.2 it would be C:\tools\jboss-4.2.2.GA\server\default\deploy\.
8)Take a breath, at this point we have installed Java, Eclipse (with WTP), Jboss and deployed bluedragon to Jboss.

Spot Check: you should now have c:\tools\eclipse-3.3.0, C:\tools\jboss-4.2.1.GA,C:\tools\jboss-4.2.1.GA\server\default\deploy\bluedragon.war\ , and C:\Program Files\Java\jdk1.5.0_14 (like I said earlier the space in program files is OK for the java install). Inside the the jboss directory (C:\tools\jboss-4.2.1.GA) there is a bin folder and you should find in there a run.bat if you double click it you should see jboss start up, feel free to do so to see if its all working. Before you move on be sure to ctrl-c and close the run.bat window!!

Setting Up Eclipse.
To Configure Eclipse to run Jboss you will need to setup a few things this includes setting up elcipse to know about the JDK5 and then configuring WTP's server control to run your instance of JBoss.

1) Start eclipse (there should an eclipse.exe in the eclipse directory)
2) At this point you will probably want to install all the goodies you might enjoy inside eclipse. If I might suggest a few plugins, first the DUH one cfEclipse, Aptana, mxUnit, and QuantmDB
3) Next we'll setup the JDK, go to Windows -> Preferences... Java -> Installed JREs (click on this option)
4) Assuming you are current you will probably have a JRE 1.6 or JRE 1.5 selected, this is FINE. What you want to do is choose ADD (the button is on the Right of the window)
5) You will be greated by a new the JRE Home Directory input box enter: C:\Program Files\Java\jdk1.5.0_15 (if you downloaded something other than updater 15 the final _## might be different but you get the idea). At this point eclipse will "freeze" for a second or 2 and then all the other fields will be filled out, nice ehh??. All these values are fine and click OK until all the preference windows are closed. Now on to Configuring the Eclipse to run Jboss!
6) First we need to get the correct panel showing, Select Window -> Show View -> Other...
7) You'll want to Scroll down and find "Servers" expand that and select Server.
8) A new panel should now be available in the lower grouping of Panels.
9) Select this panel as focus and then right click -> new -> server...
10) TaDa a magically list of servers you can configure Eclipse to manage, out of the box. Select Jboss -> 4.2 , then Next
11) On this screen select the just recently added JDK 5 in the drop down and put C:/tools/jboss-4.2.2.GA in the Application Server Directory input box. If you placed Jboss somewhere else you will want to specify the folder that CONTAINS the /bin/ directory. Click Next.
12) If you rather not type in 8080 while on localhost you can configure jboss (more or less) to listen on a different port like 80 on this screen, I just take the defaults.
13) Click Finish. You will now see JBOSS 4.2 in the Server panel.
14) Highlight it and click the Play Icon, alternately you can right click it and choose start.

There you have it Eclipse Jboss and BlueDragon running and happy. Assuming all goes well you can now browse to http://localhost:8080/bluedragon/index.cfm.

Notes about JEE environment:
  • Paths are case sensitive even on windows, ColdFusion variables are still not case sensative.
  • In a simple install (like the one above) your context root is the name of the .war file/directory
  • when using cfinclude the path root is the directories in bluedragon.war
  • When access files in the root of bluegradon.war you must navigate to http://localhost/bluedragon/file.cfm
  • If you want BlueDragon (or any WAR) to redeploy jut touch (change the mod date) of the {war}/WEB-INF/web.xml file

In my next entry I will attempt to explain portions of the technology used to make this all happen. For now be happy it is running and enjoy BlueDragon on Jboss (or ColdFusion on Jboss).

* The reason you want to install WTP is WTP offers a server configuration that allows you to control a JEE server from inside eclipse. previously the only way to do this was with a commerical product like myEclipse but the WTP project now offers a similar feature for start stopping and managing deploys to JEE servers all from inside eclipse.


Larry C. Lyons said...

One thing you may want to include in your instructions.

Once you've installed jboss and put your bluedragon.war directory in the {jboss install directory}/servers/default directory you need to determine how JBoss is going to serve your apps. This is done by creating a jboss-web.xml file inside the bluedragon.war\WEB-INF directory. If you're going to be serving your apps off the context root the jboss-web file should contain something like this:


Then you put your various apps underneath this context root.
So the url being served would be http://localhost:8080/myCoolApp/index.cfm

While I would not use this setup in a production environment, it works very well for a development environment.

Also if you're going to be deploying and redeploying apps its a good idea to change your permGen space, there's a good section on this here - specifically section 2.1:

To quote from the article,
JBoss has sophisticated support for hot re-deployment of WARs and EARs. Unfortunately, due to bugs in the JVM, repeated redeployment of an EAR—which is common during development—eventually causes the JVM to run out of perm gen space. For this reason, we recommend running JBoss in a JVM with a large perm gen space at development time. If you're running JBoss from JBoss IDE, you can configure this in the server launch configuration, under "VM arguments". We suggest the following values:

-Xms512m -Xmx1024m -XX:PermSize=256m -XX:MaxPermSize=512

If you don't have so much memory available, the following is our minimum recommendation:

-Xms256m -Xmx512m -XX:PermSize=128m -XX:MaxPermSize=256

If you're running JBoss from the commandline, you can configure the JVM options in bin/run.conf.

If you don't want to bother with this stuff now, you don't have to—come back to it later, when you get your first OutOfMemoryException.



Larry C. Lyons
Web Analyst
American Type Culture Collection

Adam Haskell said...

Here's how I see it. I do not like changing the context root to / . Many enterprise environments run multiple instances/wars in the same App server and there are countless frameworks that do not take context roots into consideration. Changing the context root in a development environment to / exposes developers to the potential of messing something up.

I completely agree on the memory management settings and have been meaning to add directions on changing that to the tutorial.
The JVM params I use are:
-Xms128M -Xmx512M -XX:PermSize=64M -XX:MaxPermSize=128M -Djava.compiler=NONE -Xnoagent -Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=8000-Dcoldfusion.disablejsafe=truue

The addition params are for running ColdFusion's line debugger (not really applicable to BD right now).

I'm also working on an eclipse monkey script to help ease our community into this environment. With eclipse moneky you can fire off server startups or config changes with hot keys.

Great feedback Larry!

Anonymous said...

Just thought I'd mention that there is now a specific website for the open source version of Blue Dragon: . I don't think there is much difference between the versions, but there are some.

Thanks for the great walkthrough! I just got the open source version of BD going with JBoss 4.2.2. One thing of note was that I had some xml api issues using JDK 1.5. Moved to JDK 6 (I realize it's unsupported on JBoss 4.2.2) and it works like a charm. Cheers, Rich