User: jwalters
Date: 01/06/04 13:21:57
Modified: src/docs jbossdocs.xml
Added: src/docs howtonetbeansdebug.xml
Log:
First pass at howto on using NetBeans with JBoss for debugging of
EJBs.
Revision Changes Path
1.18 +2 -0 manual/src/docs/jbossdocs.xml
Index: jbossdocs.xml
===================================================================
RCS file: /cvsroot/jboss/manual/src/docs/jbossdocs.xml,v
retrieving revision 1.17
retrieving revision 1.18
diff -u -r1.17 -r1.18
--- jbossdocs.xml 2001/05/21 22:16:21 1.17
+++ jbossdocs.xml 2001/06/04 20:21:57 1.18
@@ -30,6 +30,7 @@
<!ENTITY howtoverifier.xml SYSTEM "howtoverifier.xml">
<!ENTITY howtombeans.xml SYSTEM "howtombeans.xml">
<!ENTITY jbosssx.xml SYSTEM "jbosssx.xml">
+ <!ENTITY howtonetbeansdebug.xml SYSTEM "howtonetbeansdebug.xml">
<!ENTITY howtovisualagedebug.xml SYSTEM "howtovisualagedebug.xml">
<!ENTITY howto_webcontainer.xml SYSTEM "howto_webcontainer.xml">
]>
@@ -67,6 +68,7 @@
&howtojavamail.xml;
&howtojbuilderdebug.xml;
&howtovisualagedebug.xml;
+&howtonetbeansdebug.xml;
&howtoejx.xml;
&howtojca.xml;
&howtojndi_external.xml;
1.1 manual/src/docs/howtonetbeansdebug.xml
Index: howtonetbeansdebug.xml
===================================================================
<?xml version = "1.0" encoding = "UTF-8"?>
<section>
<title>Integrating NetBeans/Forte for Java Community Edition with JBoss
for source level debugging</title>
<para>Author:<author>
<firstname>Jay</firstname>
<surname>Walters</surname>
</author>
<email>[EMAIL PROTECTED]</email>
</para>
<section>
<title>Purpose</title>
<para>This howto is a first pass at illustrating the procedures required to
use NetBeans to develop and debug EJBs running within JBoss. It will also
discuss how to make the JBoss source available so that debugging can include
JBoss code. It is not the purpose of this howto to describe how to develop
and debug the JBoss code.
</para>
</section>
<section>
<title>Install the JBoss Server</title>
<para>
For the purpose of this howto, I installed the JBossTomcat release version
2.2.2 into d:\JBoss-2.2.2_Tomcat-3.2.2. Download it from
http://www.jboss.org and select the binary link from the page. Don't worry
about downloading a binary package, when all you want is the source code;
the binary package also contains the source code used for building.
</para>
</section>
<section>
<title>Create a NetBeans Project</title>
<para>Start NetBeans, I used NetBeans 3.2 while writing this howto. The first
step is to create a new project or open an existing project. You create a new
project from the Project -> Project Manager menu selection. This dialog will
show a list of your projects like:
</para>
<mediaobject><imageobject>
<imagedata fileref = "images/netbeans-project.png"/>
</imageobject></mediaobject>
</section>
<section>
<title>Mount the JBoss client jarfiles</title>
<para>
This is a bit tedious, though it's not too bad. Once you have opened your
project you should go to the explorer window and select the FileSystems tab.
Either right click on the FileSystems entry in the explorer window, or choose
File -> Mount Filesystem and pick mount jar. Use the browser or type in the
path for the following jar files: jboss/lib/jdbc2_0-stdext.jar and
jboss/lib/ext/ejb.jar. If you use bean managed transactions you will need to
add jboss/lib/ext/jta-spec1_0_1.jar. If you are using JBossSX security then
you'll also need to add additional jar files jboss/lib/jaas.jar,
jboss/lib/jboss-jaas.jar and jboss/lib/ext/jbosssx.jar. If you are using JMS from your
client you'll also need to add jboss/lib/ext/jms.jar and
jboss/lib/ext/jbossmq-client.jar. Once you have
added all these jar files if you don't want them to show in the explorer you can
right click on them one by one and from the properties panel select hidden=true.
</para>
<para>
At this point you need to add any other jar files specific to your app which
need to be available to compile your project, e.g. log4j.jar if you are using
the Apache logging framework.
</para>
</section>
<section>
<title>Complete your project and build your jar/war files</title>
<para>
Now you should be able to mount the directory containing your source
code and compile it by right clicking on the root package and selecting compile
all.
</para>
<para>
In order to build a jarfile from which to deploy your EJBs you'll need to add
a new jar packager element to your project. Select File -> New and then
from the Wizard select Jar Packager -> Jar Contents. This will take you
into the Jar Packager wizard. It will allow you to specify the name of the
jarfile, select and filter the contents of mounted filesystems for inclusion
in the jarfile, and the output directory for the jarfile.
</para>
<para>
I have never seen POSIX filters before myself, there is good help available
within NetBeans. The short version is that a filter to include .class files
is \.class$. You could include .class and .xml files with a filter like
(\.class$)|(\.xml$). See the online help for more details.
</para>
<para>You will need to make
sure that you include all required .class files as well as deployment
descriptors in the META-INF directory. You right click on the Jar Contents
and select "compile" to create the jar file.
</para>
<para>
After you have built the deployable jar file or war file you can deploy it into
your JBoss server. If you want NetBeans to deploy the jar/war file for you
then make the output location the jboss/deploy directory and you'll be on your
way. Otherwise you'll need to manually copy it from where NetBeans writes it
to the jboss/deploy directory.
</para>
</section>
<section>
<title>Setup JBoss for debugging</title>
<para>Since these instructions are not for debugging JBoss so much as an
application running in JBoss, at the moment the instructions will start
JBoss from the command line and then attach the debugger. At some point in
the future we can augment these instructions with instructions to launch
JBoss from within NetBeans.
</para>
<para>
Make the following changes to your run.bat/run.sh file, or copy
run.bat/run.sh to a new file debug.bat/debug.sh and paste the text in. This
text is the Windows version, the UNIX version should use $env-var instead of
%env-var%. Change the command line from:
</para>
<para><programlisting>
java %JAXP% -classpath %JBOSS_CLASSPATH% org.jboss.Main ...
</programlisting></para>
<para>to:</para>
<para><programlisting>
java -classic -Dtomcat.home=%TOMCAT_HOME% -Xdebug -Xnoagent
-Djava.compiler=NONE -classpath "%JBOSS_CLASSPATH%"
-Xrunjdwp:transport=dt_socket,server=y,address=12999,suspend=n
org.jboss.Main %1 %2 %3 %4 %5 %6 %7 %8 %9
</programlisting></para>
<para>
You can of course substitute your favorite port for the 12999 in the example.
</para>
<para>
Once you startup JBoss then you can attach to it from NetBeans to do your
debugging. Select the Debug -> Attach menu selection in NetBeans and then
the debugger type should be default debugger JPDA. Select the SocketAttach
in the connector dropdown and then enter the port number you selected when you
edited the debug.bat/debug.sh file. The hostname should default to your local
hostname when you select SocketAttach. After you complete filling in the
debug "Attach to VM" dialog it should look something like:
</para>
<mediaobject><imageobject>
<imagedata fileref = "images/netbeans-debug.png"/>
</imageobject></mediaobject>
</section>
<section>
<title>Sprinkle breakpoints throughout your EJB and or Client Code</title>
<para>
First it is necessary to put breakpoints in your ejb's. As outlined
previously project settings should point to the source of your beans. Open
up a typical bean implementation and place breakpoints whereever desired.
</para>
</section>
<section>
<title>Start the JBoss server</title>
<para>
Start JBoss using the debug script which you previously created. Deploy the
EJBs you'd like to debug. If you want to see
your beans being instantiated by the deployer, place breakpoints on the bean
constructors (if you specified them) You will not need to have a client
running to exercise this functionality.
</para>
</section>
<section>
<title>Deploy the Beans</title>
<para>
Copy of drag/drop (for windoze fans) the ejb jar file containing the
ejb-jar.xml and jboss.xml (optional) to the deploy folder. If you have set
breakpoints in stateless session ejb's these should cause the debugger to
stop in your code! Hurrah!
</para>
</section>
<section>
<title>Start the Client Test Application</title>
<para>
To really debug your beans you will need to start up a client application.
The easiest way to do this is either with a command line client, or else
with a servlet/JSP client running inside any embedded or otherwise servlet
container. One thing though, the timeouts
are somewhat short so if you spend too much time in a method within the EJB
you may find that transactions are rolled back.
</para>
<para>
If anyone has suggestions of feedback please let me know, I can be contacted
via email at [EMAIL PROTECTED]
</para>
</section>
</section>
_______________________________________________
Jboss-development mailing list
[EMAIL PROTECTED]
http://lists.sourceforge.net/lists/listinfo/jboss-development
