How to Run and Debug EJBs using jBoss 2.0 inside of Visual Age for Java version 3.5

Authors: Craig Doremus <cdoremus@vianow.com> and Lorin Blumenfeld <lorin@quick-soft.com>

Contributions by: Ron Gavlin <gavlin@rdacustomsoftware.com>

Importing jBoss into Visual Age for Java (VAJ) allows you to develop and debug EJBs using the latest Enterprise Java Beans standard (version 1.1). The Enterprise version of Visual Age has built-in EJB debugging, but that edition of the IDE only supports version 1.0 of the EJB spec.

We created a jBoss Test Environment by manually importing jBoss source into Visual Age for Java. This import also involved a few code hacks to remove JDK 1.3 code and allow EJBs to be visible outside of a jar in addition to modification of paths inside of configuration files. See below for detailed directions on the process.

Our jBoss import does not include an integrated Jakarta-Tomcat servlet engine. IBM provides a Test Environment for Tomcat version 3.1 on their web site (see below) that allows debugging of JSP and servlets inside of VAJ. Both Tomcat and jBoss can be run inside of VAJ to provide the ability to debug EJBs called by servlets.

Requirements

Note:

<vaj.home> refers to the directory where Visual Age is installed.

<jboss.home> refers to the directory where jBoss is installed in the Visual Age directory tree.

The jBoss Test Environment Package

The jBoss Test Environment is a Visual Age add-in that installs jBoss into Visual Age.

The jBoss Test Environment includes:

  • jBoss 2.0 -- the EJB server

  • Hypersonic SQL -- a Java-based RDBMS (see http://sourceforge.net/projects/hsql/)

  • InstantDB -- a Java-based RDBMS (see http://instantdb.enhydra.org/)

  • JAAS -- Java Authentication and Authorization Service

  • JAF -- JavaBeans Activation Framework

  • JavaMail -- Java Mail

  • JMS -- Java Messaging Service

  • JMX -- Java Management Extension

  • Sun XML Parser

  • IBM Enterprise Extension Libraries (updated EJB 1.1 - javax.ejb package)

  • Java class libraries (updated JTA - javax.transaction package)

Download jBoss Test Environment

Installing the jBoss Test Environment

WARNING:

Installing jBoss Test Environment may break the Websphere Test Environment (WTE) of Visual Age for Java Enterprise Edition.

Install process:

  1. Install the Test Environment using the installer or unzip the archive to your Visual Age directory (<vaj.home>).

  2. Go to File/Quick Start(or press F2), select Add Feature and pick the jBoss Test Environment to add the jBoss 2.0 feature. This will install a jBoss 2.0 project in addition to a few other projects with related files that have jBoss 2.0 appended to their name.

  3. If an Add Failed dialog box appears, delete the package mentioned in the dialog and re-add the Test Environment to VAJ.

  4. Check the org.jboss.Main properties (right click on the class and choose properties) and adjust the command line arguments and properties to point to the right directories of your VAJ install. You should also check the classpath directories.

  5. Run the org.jboss.Main class. You should then see the test beans deployed.

Running and debugging EJBs inside of Visual Age

  1. Create META-INF subdirectory in the deploy directory of <jboss.home>.

    a. Add ejb-jar.xml and both jboss.xml and jaws.xml (if needed) to the directory.

  2. Run org.jboss.Main using VAJ run command to start jBoss.

  3. Make sure any projects that contain EJBs that you are developing are in the classpath of org.jboss.Main.

  4. If running EJBs from servlets/JSPs, make sure that jBoss's project is in Tomcat's classpath (the com.ibm.ivj.tomcat.TomcatRunner class). If you are calling EJBs from a client class with a main() method, make sure the jBoss project is in its classpath in addition to all jars from the <jboss.home>/client directory.

  5. Make sure configuration-name tag in jboss.xml points to the JDK 1.2 (NOT JDK 1.3) info in standardjboss.xml as this example shows:

    <configuration-name>jdk1.2.2 CMP EntityBean</configuration-name>

  6. To debug, set breakpoints inside of EJB bean class.

  7. To allow changes to EJBs to take effect in VAJ, either restart jBoss or touch one of the XML files in the <jboss.home>/deploy/META-INF directory.

Manually Importing jBoss 2.0 Source into Visual Age for Java 3.5

This section details how to manually import jBoss 2.0 source into Visual Age for Java 3.5. For the lazy programmer (which we all should be), please see above on importing jBoss into Visual Age, which details how to import jBoss using a pre-packaged repository. This repository was created using the manual import process detailed below.

Prerequisite

In addition to the above requirements:

  • jBoss-2.0-FINAL.zip downloaded (NOT the one with integrated Tomcat) Download it here

Importing jBoss source code into Visual Age

  1. Unzip jBoss-2.0-FINAL.zip into a temporary directory.

  2. Create a jboss project in VAJ.

  3. Import source, jar and class files into VAJ from temp dir:

    1. All jBoss source (src subdirectory).

    2. In lib directory import:

              
              jaas.jar -- Java's Security API
              jmxri.jar -- Java Management Extension API
              xml.jar -- XML parsing classes
              jdbc2_0-stdext.jar -- JDBC 2.0 Extensions
              
    3. In lib/ext directory import:

              activation.jar -- Java Activation Frameworks
              awt.jar -- some GUI classes used by the EJX editor
              dynaserver.jar -- a small web server
              ejb.jar -- EJB 1.1 API
              ejxejb.jar -- optional EJX visual XML editor
              ejxeditor.jar -- optional EJX visual XML editor
              ejxjaws.jar -- optional EJX visual XML editor
              ejxboss.jar  -- optional EJX visual XML editor
              hsql.jar -- optional HSQL database
              idb.jar        -- optional InstantDB database
              ejboss.jar -- add ONLY non-HTML resources
              jms.jar -- JMS API
              jmxtools.jar
              jndi.jar -- if not already in VAJ
              jnpserver.jar -- a JNDI implementation
              jpl-util-0_5b.jar
              jta-spec1_0_1.jar -- (javax.transaction package updated elsewhere)
              mail.jar -- JavaMail API
              spydermq.jar -- jBoss's JMS implementation
              
  4. Directories to be added to VAJ's <vaj.home>/ide/program_resources/jboss directory from jBoss zip archive:

            bin
            client
            conf/default
            db -- for InstantDB and Hypersonic
            deploy -- EJB autodeploy directory
            lib (with ext subdir) -- all the jars
            log
            tmp
    
  5. org.jboss.Main -- this is the jBoss runner class, whose main() is executed to start jBoss.

    a. Commented out shutdown hook code in Main() since this only works for JDK 1.3 and prevents it from being compiled in VAJ which uses JDK 1.2.2.

    Here's the commented out code:

                      // Add shutdown hook
                      /* 
                      Removed by Craig since VAJ will
                      not compile this because addShutdownHook()
                      only works with JDK 1.3.
                      
                      try
                      {
                             Runtime.getRuntime().addShutdownHook(new Thread()
                             {
                                    public void run()
                                    {
                                            manager.stopMBeans(server);
    
                                       err.println("Shutdown");
                                       Set mBeans = server.queryNames(null, null);
                                       Iterator names = mBeans.iterator();
                                       err.println("Shutting down "+mBeans.size() +" MBeans");
                                       while (names.hasNext())
                                       {
                                              ObjectName name = (ObjectName)names.next();
                                              try
                                              {
                                                     server.invoke(name, "destroy", new Object[0], new String[0]);
                                              } catch (Throwable e)
                                              {
                                                    //err.println(e);
                                              }
                                       }
                                       err.println("Shutting done");
    
                                    }
                             });
                             System.out.println ("Shutdown hook added");
                      } catch (Throwable e)
    
                      {
                             System.out.println("Could not add shutdown hook");
                             // JDK 1.2.. ignore!
                      }
                      */
            

    b. Modified the following in org.jboss.Main.Main():

             //URL confDirectory = new File("../conf/"+confName).getCanonicalFile().toURL();
            //CHANGED TO:
             URL confDirectory = new URL(confName);
            

    c. Properties to change in org.jboss.Main (right click on class and bring up Properties dialog) (NOTE -- please adjust the path to point to your Visual Age install directory):

    1. Program tab:

      1. Command line: added full path to jboss.conf here ("file:///E:/Program Files/IBM/VisualAge for Java/ide/project_resources/jboss/conf/default" ) Note that this command line should be quoted if there are spaces in the command line (like Program Files).

      2. Properties: (as listed)

                                      
              jboss.home="E:/Program Files/IBM/VisualAge for Java/ide/project_resources/jboss"
              org.xml.sax.parser=com.sun.xml.parser.Parser
      
    2. Classpath tab:

      1. Project Path: Add any other projects that jBoss needs if they are not in the jBoss project.

      2. Extra Directories Path:

      1. Add all jar files in <jboss.home>/lib and <jboss.home>/lib/ext

      2. Add the following directories: "./conf/default;./db;./deploy;./log"

  6. For org.jboss.jmx.server.RMIConnectorImpl, org.jboss.jmx.JMXAdaptorImpl, and org.jboss.ejb.plugins.jrmp.server.JRMPContainerInvoker.

    a. Manually generate RMI stub/skeleton using VAJ's built-in RMI tool or import stub classes from the jBoss binary distribution (use for JRMPContainerInvoker).

  7. In org.jboss.deployment.J2eeDeployer.InstallEJB(), commented out the following:

              // download libraries we depend on
              /*Commented out by Craig to prevent exceptions from being
              thrown when deployed from VAJ without a jar or zip file
              Manifest mf = new JarFile (localUrl.getFile ()).getManifest ();
              if (mf != null)
                      addCommonLibs (_d, mf, _source);
              else
                      log.debug(m.name+" doesn't contain MANIFEST.MF");
            */
              

    a. This routine gets classpath info from the jar's Manifest file and throws an exception since there is no jar file when you are running jBoss inside of VAJ.

  8. In jboss.conf (in <jboss.home>/conf/default directory):

    • Change all references to ../../ in file to ./ using search and replace

    • Change single reference to ../deploy to ./deploy

    • Change references to ../xml.jar to ./xml.jar

    • Change single reference to ../tmp/deploy to ./tmp/deploy

  9. In jboss.jcml (in <jboss.home>/conf/default directory):

    a. Change single reference to ../conf/default/instantdb.properties to ./conf/default/instantdb.properties

  10. In instantdb.properties (in <jboss.home>/conf/default directory):

    a. Change line: traceFile=../log/trace.log to traceFile=./log/trace.log

  11. Adjust the following jboss.conf records to point to your jBoss install path:

    <MLET CODE = "org.jboss.ejb.AutoDeployer" ARCHIVE="jboss.jar">
    <ARG TYPE="java.lang.String" VALUE="E:/Program Files/IBM/VisualAge for
    Java/ide/project_resources/jBoss/deploy/">
    </MLET>
    
    <MLET CODE = "org.jboss.deployment.J2eeDeployer"
    ARCHIVE="jboss.jar,../xml.jar" CODEBASE="./lib/ext/">
    <ARG TYPE="java.lang.String" VALUE="E:/Program Files/IBM/VisualAge for
    Java/ide/project_resources/jBoss/tmp/deploy">
    <ARG TYPE="java.lang.String" VALUE="EJB:service=ContainerFactory">
    <ARG TYPE="java.lang.String" VALUE=":service=EmbeddedTomcat">
    </MLET>