How to launch the Liferay/Tomcat bundle and debug it from Eclipse.

With Liferay IDE #

Using Liferay IDE, the official set of Eclipse plugins for Liferay Portal development.

• Menu: Window > Open Perspective > Other...
• Select: Liferay
• View: Servers
• Select the server you have previously created, e.g. Liferay v6.2 CE Server (Tomcat 7) at localhost
• Deploy any Portlets and Plugins you wish to debug.
• On the view toolbar, click the button: Start the server in debug mode

With Eclipse JEE alone #

Using Eclipse JEE Edition by itself, without Liferay IDE.

• Menu: Window > Open Perspective > Other...
• Select: Java EE
• View: Servers
• Select the server you have previously created, e.g. Apache Tomcat v7.0 at localhost
• Outside Eclipse, manually deploy the Portlets and Plugins you wish to debug.
• On the view toolbar, click the button: Start the server in debug mode

(Older versions) With a straightforward launch configuration #

Using a Launch Configuration specifically created to run Tomcat directly, bypassing Eclipse.

1. Open "Run Configurations..." under the Run button
2. Under Java Applications node in the tree, right click and "New"
3. On Main tab, select the portal source code project or your EXT project
4. In the Main class put org.apache.catalina.startup.Bootstrap, don't check any check boxes
5. Go to Arguments tab, in the Program arguments type: start
6. In VM arguments put like:

-Xmx512m
-XX:PermSize=32m
-XX:MaxPermSize=160m
-Dfile.encoding=UTF8
-Duser.timezone=GMT
-Djava.security.auth.login.config=${tomcat-root-folder}/conf/jaas.config
-Dcatalina.base=${tomcat-root-folder}
-Dcatalina.home=${tomcat-root-folder}  
-Djava.io.tmpdir=${tomcat-root-folder}/temp

Optional If you want to retain the tomcat logging settings include the following arguments.

-Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager
-Djava.util.logging.config.file=${tomcat-root-folder}/conf/logging.properties

Change ${tomcat-root-folder} to point at your tomcat deployment root folder

1. In the Working directory, make it: Other: ${tomcat-root-folder}/bin. Again, change ${tomcat-root-folder} accordingly
2. In Classpath tab, remove ALL User entries, do NOT remove the JRE System library
3. Select User Entries and "Add External JArs", find the bootstrap.jar file from the ${tomcat-root-folder}/bin folder and add only that one
4. In the Source tab, select any related project, but also the main project. For example, if you want to also debug a plugin, add it's source path here
5. Under Common tab check Run and Debug
6. Apply all changes
7. Now whenever you want to debug, just go to the debug button/drop down and click. The server should startup on console.

Eclipse Remote Debugging #

Remote debugging means you can debug an Application Server that is running on a different computer. This setup is very convenient because there's no need to run Eclipse at the remote server.

There are two basic concepts behind remote debugging:

• First you should enable remote debugging at your application server of choice. Each AS has it's own special way to enable remote debugging.
• Secondly, you should setup Eclipse to debug the AS.

An example with Tomcat:

The way to enable debugging in Tomcat 5.5 in a Windows environment is to copy this line into $TOMCAT_HOME/bin/setenv.bat before you set any CATALINA_OPTS:

set CATALINA_OPTS=-Xdebug -Xrunjdwp:transport=dt_socket,address=8000,server=y,suspend=n 

Now you should debug this Tomcat with Eclipse:

• Open the Debug Dialog setup window.
• Create a new "Remote Java Application".
• Specify the ip address and port number. If you are debugging on the same machine you can use 'localhost' as the ip address. The port number should be the same number as the 'address=' value that you set for the JAVA_OPTS above (in this example the port number is 8000).
• Next you should go to the 'Source' tab and attach code to debug against.
• Hit Debug and you're done!

HotSwap, or Hot Code Replace #

Using Eclipse HotSwap during Debug-Session could melt down your development cycle down to seconds.

With Eclipse HotSwap alone #

Every class you modify and save in debug mode will be automatically redeployed into the running server. This works for Remote Debugging too.

However, the standard HotSwap doesn't work for all kinds of changes. For instance, you cannot change method signatures.

Also, if you stop the server, your source code will remain modified but the changes at class bytecode level will be lost. You will need to save the source code files again in the next session.

Finally, changes in JSP files will be ignored by the standard HotSwap.

With JRebel #

JRebel is a commercial tool that implements a HotSwap mechanism without any of the aforementioned limitations, making it very attractive for professional Liferay developers that often work on complex debugging sessions requiring several redeploys. In this wiki you'll find information on Optimal Liferay Core Development with JRebel.

(Older versions) With the Eclipse JDT Compiler #

To use HotSwap with older versions of Liferay/Tomcat, you should compile java-source you want to debug/change with Eclipse JDT Compiler:

• copy $ECLIPSE_HOME/plugins/org.eclipse.jdt.core_3.2.1.v_671.jar to $ANT_HOME/lib
• extract jdtCompilerAdapter.jar from org.eclipse.jdt.core_3.2.1.v_671.jar to $ANT_HOME/lib
• in ext/build.${user.name}.properties set javac.compiler=org.eclipse.jdt.core.JDTCompilerAdapter