Debugging Liferay in Eclipse

When should you use a debugger during development? At ALL times! At least that's my view.

Isn't that a hassle? Well debugging sure can be, but if you setup your environment in a specific way, it can actually become very fast and almost transaprent. I like transparent!

Here are steps I take to configure my tomcat (I've followed the same steps with JBoss):

  1. Note the deployment path of tomcat (in my case I'll use /bundles/tomcat-6.0.x)
  2. In Eclipse, open the "Run Configurations" manager (Run -> Run Configurations...)
  3. On the "Java Application" node, right click and choose "New".
  4. On the first tab (Main) select the project you are running in tomcat
  5. In the Main Class field enter org.apache.catalina.startup.Bootstrap
  6. On the Arguments tab, in the Program Arguments field enter start
  7. In the VM arguments field enter the following:

    -Xms1024m
    -Xmx1024m
    -XX:PermSize=128m
    -XX:MaxPermSize=256m
    -XX:+CMSClassUnloadingEnabled
    -Dorg.apache.catalina.loader.WebappClassLoader.ENABLE_CLEAR_REFERENCES=true
    -Dcatalina.base=/bundles/tomcat-6.0.x
    -Dcatalina.home=/bundles/tomcat-6.0.x
    -Djava.io.tmpdir=/bundles/tomcat-6.0.x/temp
    -Dexternal-properties=${workspace_loc:<NAME_OF_YOUR_ECLIPSE_PROJECT>}/portal-web/docroot/WEB-INF/src/portal-developer-tomcat.properties
    -Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager
    -Djava.util.logging.config.file=/bundles/tomcat-6.0.x/conf/logging.properties


    You many notice that I included a reference to my portal project's portal-developer-tomcat.properties file. This way I can change portal settings and only need to restart the portal without a redeploy, which is very convenient.

    You may also notice that I included tomcat's juli log manager so that all the normal web app configurations work as expected and in the Eclipse console, which is also very nice.

    Adjust your heap settings as desired, but the above settings have worked for me in 99.999% of cases.
     
  8. In the Working directory field choose "Other" and enter /bundles/tomcat-6.0.x/bin. Notice that this is the tomcat path, plus the /bin folder.
  9. The JRE tab should be already set properly, but you can choose any JRE that is installed that is 1.5+.
  10. On the Classpath tab, remove any entries under User Entries and then choose "Add External JARs...".
  11. Select the 3 jars located in /bundles/tomcat-6.0.x/bin.
  12. On the Source tab make sure that you have both Default, as well as your project in the list.

    Optionally here you can add any plugin projects that you are working on, as well as adding the path to the jsp java classes (typically /bundles/tomcat-6.0.x/work/Catalina/localhost/_)
  13. On the Common tag choose at least Debug and Run under "Display in favorites menu".
  14. Click "Apply" near the bottom of the dialog.
  15. Finally, to start the portal in debug mode, click the Debug menu in the Eclipse toolbar, and choose the run config you jsut created.

    You should see at this point output on the Eclipse console showing that tomcat is starting up.

I've been using this techinque for at least 3 years and I run the portal this way 99.999% of the time. By doing so, I can at any point in time add a breakpoint and start trouble shooting and I don't have to worry about re-connecting to or restarting the portal in debug mode, I know it's already done.

If you want to add any other java apps this way, the simples technique is to first run the app in the traditional way, then observe the process log to see what the full command that was actually used to start it, and from where. Once you know that, you can add any app to Eclipse Run Configuration.
 

 

Blogues
Hey Ray, I use to work in a different and IMO more efficient way. I start my Tomcat in a remote debug mode, just call from command line the command: "catalina.sh jpda run" . Then you can connect your Eclipse to Liferay using the "Debug Configurations > Remote Java Application" menu. By default the host and port points to the correct place. You can also disconnect as you wish and continue the normal testing. Give a try and let me know.

um abraço!
I started this way long ago. I dropped it because it caused me to have to editing the tomcat configurations all the time, setting different VM settings, etc. With the method I use, I can duplicate the run config, and change only a few settins, such as adding JMX, or particular GC settings, etc., all without touching the files in the bundle. I can even switch to different installed JVMs configured in Eclipse without having to edit more config, or change the system PATHs or settings.
@Ray

Can you explain step by step your method?

Thanks,
Denis.
Besides the configuration above, can you explain a little what "method" you'd like me to clarify? I'm not quite sure what you're asking, but I would like to give a good answer.
Hi Ray!

It's good to see this stuff written down. However, for the whole picture it would be nice to hear about hot code replacement. When I debug my code and find something to be fixed I like not having to run any build script to test the new code. So is the above description solves this issue or we need to do some extra work to get the JVM to hot code replace?
You can do hot code replacement using this technique. There is of course the limitation of the (Sun) JVM, which does not allow new|changes to the class's public signature.

Oh, and the project does have to be listed in the sources tab of the run configuration.
How should i hot-code replace classes?
I know there is deploy-fast for jsps and deploy.properties.
Eclipse should do it automatically. Of course you can't add new methods, but changes should be pushed automatically as soon as you save, while in debug.

Just make sure to include their path to the jsp java source in the run configuration (that is in the "work" folder, [tc]/work/Catalina/localhost/*/).
Oh, as I learned the hard way last week, jsp pre-compile breaks the ability to debug them, so don't do that.

They have to be compiled inside the debugged JVM.

I even tried pre-compiling them with debug flags added, but it still didn't work. Anyone with insight in that please let me know.
Hi,

you can combine your ideas. Extend VM arguments to
-Xdebug -Xrunjdwp:transport=dt_socket,address=8000,server=y,suspend=n

So you get the advantages metioned by Ray and you can use "Remote Debugging" as Thiago has described.

Daniel :-)
Since I can't see my portlet on the website, it isn't deployed to the server? How can i do this in eclipse?
I just found out by trial that when in the Servers View you add a Tomcat Server or Liferay Server (IDE/Studio) and point it to your newly build bundle and just under Open launch configuration >> Source >> Add : Java Project >> The portal project.
Start in debug and voila..
Just testing and got an error using helios SR2

Variable references non-exitent resource: ${workspace_loc:portal}
You still seeing this? I wonder if eclipse changed the default variable names!
I updated it to just say ${workspace_loc:<NAME_OF_YOUR_ECLIPSE_PROJECT>}

Replace that token with whatever is the name of your eclipse project. OR just replace that entire variable with the absolute path to your project.
hi sir.
pls tel me how to configure liferay with Jboss to eclips
I would do basically the same thing as above and get the start command used by jboss, and setup the run config something like this:

http://i.imgur.com/Gjqyv.png
http://i.imgur.com/joTTR.png
http://i.imgur.com/m8mY5.png
http://i.imgur.com/6wZTX.png

Note the ${JBOSS_510_DEPLOY} Eclipse variable points to the JBoss install location.
Creating my project of, 'portal', with the, "Create from ant build file", option, all works, see the app, create the run configuration and fire i
t up just fine but I don't see any source to step through, just all the jars. How do you create your project in eclipse?
Does this method of debugging in Eclipse no longer work with 6.1 and IDE 1.52?
For some reason I no longer get output to the console from my portlets and break points are ignored.
this method is debug for portlet, theme, ext, hook project?
when i use liferay. I use web-content and cms script.
my code find service is return nothing. i want debug into serviceLocator.findService.
howto setup enviroment for debug portal code?