Stepping through the TomEE source code is a must-to-follow step if you want to understand how TomEE works and later contribute. This is a guide to quickly start your debugging session with TomEE as a TomEE developer.
This guide assumes that:
For beginners it is recommended not to start with the trunk, because it is common to have some blockers or non-stable functionality which could bring your learning to a halt. So first start with the latest stable released source code. Move to trunk once you are ready to do some code modification on TomEE.
First extract the zip file named openejb-4.7.1-source-release.zip to any location. Lets assume it is your home folder.
unzip openejb-4.7.1-source-release -d ~
The above command will create the openejb-4.7.1 directory in your home directory.
Even though you can do a full build, We will run the following command to do a quick build so that you can have your meal before your hunger kills you.
mvn -Pquick -Dsurefire.useFile=false -DdisableXmlReport=true -DuniqueVersion=false -ff -Dassemble -DskipTests -DfailIfNoTests=false clean install
More details about building the product from the source can be found here.
The TomEE build builds several distributions (zip & war files) to cater the different needs of different users. Here we discuss about the tomee plus distribution & TomEE war distribution only. TomEE+ is the full feature packed distribution from TomEE.
TomEE+ zip location:
Unzip the zip into your home directory (or any other location)
unzip ~/openejb-4.7.1/tomee/apache-tomee/target/apache-tomee-plus-1.7.1.zip -d ~
You will find the directory apache-tomee-plus-1.7.1 in your home folder. Lets run the TomEE.
"INFO: Server startup in xxxx ms" is the Green light!
Lets prepare our IntelliJ IDEA for the debugging session.
Start IntelliJ IDEA and Click the Import Project link
Select the ~/openejb-4.7.1 directory and press OK
Select import project from external model & Maven as the external model.
Press Next on this screen.
Select the main profile.
Select the org.apache.openejb:openejb:4.7.1
Select the JDK you want to use with.
Give the project a name and press Finish.
Now your IDE will load the project.
Next step is to put a breakpoint at the place where the code is triggered. Lets understand how the code is triggered.
TomEE+ is created on top of Tomcat. TomEE registers a Tomcat Lifecycle Listener "org.apache.tomee.catalina.ServerListener" on server.xml file.
All the Tomcat lifecycle events i.e. before_init, after_init, start, before_stop etc... are received by the lifecycleEvent method of the ServerListener.
The execution of TomEE code starts in this lifecycleEvent method. So the first breakpoint should be on the lifecycleEvent method.
If you simply run catalina.sh jpda run in the bin folder of tomee deployment, the server starts in the debug mode but it will quckly pass your breakpoint before you attach your IDE to the server process.
So we set** JPDA_SUSPEND="y"** before we start our debugging. This will tell the server "Do not proceed until the Debugger tool is attached to the process"
The convenient way of doing this is adding this line to catalina.sh file right after the #!/bin/sh line.
Now to time to run TomEE+ on debug mode.
~/apache-tomee-plus-1.7.1/bin/catalina.sh jpda run
The terminal should hang with the message "Listening for transport dt_socket at address: 8000"
To start debugging your TomEE+
Main Menu > Run > Debug TomEE DEBUG
Congratulations! You hit the break point you put at the startup of the TomEE code. Carry on with your debugging session to learn more.
All edits are reviewed before going live, so feel free to do much more than fix typos or links. If you see a page that could benefit from an entire rewrite, we'd be thrilled to review it. Don't be surprised if we like it so much we ask you for help with other pages :)NOTICE: unless indicated otherwise on the pages in question, all editable content available from apache.org is presumed to be licensed under the Apache License (AL) version 2.0 and hence all submissions to apache.org treated as formal Contributions under the license terms.