Alternative Languages: 日本語

Introduction #

This article discusses how to use the Eclipse IDE with Liferay.

Basic Configuration #

Download and install the Eclipse IDE. Then, configure your eclipse with the extension environment: Preformatted

1) To get started for development, following the official documentation to set up a development environment (called the "Extension environment"). Be sure to check also "Development Environment (General)" and the docs page for updates and corrections.

Notes: create <projectdir>/liferay/portal, and unzip the source into that directory. Use <projectdir>/liferay as the "workspace" dir in Eclipse. The "extension environment" directory will be <projectdir>/liferay/ext. Be sure to create an app.server.${user.name}.properties file in your liferay source dir and set the appropriate app.server.type and app.server.${app.server.type}.dir prior to running ant start, this tripped me up the first time.

2) Once the build-ext Ant target has run, the script for mysql is in /ext/sql/create/create-mysql.sql. Other db scripts are also in /ext/sql/create dir.

3) To configure to use mysql:

1. Run the create-mysql.sql script throuh mysql's command line (it may take a while to execute).
2. Change the Tomcat 5.5 config to utilize MySQL database by following directions here: http://content.liferay.com/4.0.0/docs/developers/ch02s02.html#d0e3189

Note: correct entry in config is url="jdbc:mysql://localhost/lportal?useUnicode=true&amp;amp;characterEncoding=UTF-8"

Eclipse Debugger #

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

7) In the Working directory, make it: Other: ${tomcat-root-folder}/bin. Again, change ${tomcat-root-folder} accordingly

8) In Classpath tab, remove ALL User entries, do NOT remove the JRE System library

9) Select User Entries and "Add External JArs", find the bootstrap.jar file from the ${tomcat-root-folder}/bin folder and add only that one

10) 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

11) Under Common tab check Run and Debug

12) Apply all changes

13) Now whenever you want to debug, you just go to the debug button/drop down and click, the server should startup on console

Eclipse Remote Debugging #

Remote debugging means you could debug an application server from a different computer. The setup is very convenient because you don't need to worry about integrating that AS with Eclipse.

There are two basic concepts behind remote debugging. First you should enable remote debugging from 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. I'll give 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!

Hot Code Replacement #

Using Eclipse HotCodeReplacement during Debug-Session could melt down your development-circle down to seconds. This works for Remote-Debugging too. To use HotCodeReplacement you should compile java-source you want to debug/change with EclipseJDTCompiler.

this are the steps to use EclipseJDTCompiler:

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

note: HotCodeReplacement doesnt work for all kind of changes. you can not change method-signatures for instance.

Tips and Tricks #

• While in any Eclipse editor, press Shift+Ctrl+T. This opens up the Eclipse "find type" window. Type in the name of the class you are looking for (for example, type "ThemeDisplay"). Double click, and Eclipse will open the source file for you. Use this whenever you know of a class name, but don't know where its located
• Have a source code file open (found it using above Shift+Ctrl+T) but STILL don't know where it is in the source tree? Right click in the source code's editor window, and select "Show in >" from the right-mouse menu. Select "Navigator" or "Package Explorer" to have that view sync with the file you are now editing.
• With any class name or method name highlighted in the source code, press the F3 key to "Open declaration." For example, if you see a line of code like User user = this.getRealUser(), and you want to examine the "User" class, place the cursor over the "User" class and press F3 (or right click and select "Open declaration" or hold the Ctrl key (Win) or Apple key (Mac) and click). Or - want to see the implementation of the method? Put your cursor over the .getRealUser part and have Eclipse take you to the declaration of the getRealUser() method (which is usually the implementation, unless the method is from an interface).
• Need to track down where a variable, method, or class is used elsewhere in the source code? Place your cursor on the name in any Java file, right click on it, and select "References -> Workspace". All of the Java code in your workspace will be searched, and you will be shown all code that references the object in question.
• Have a Java interface, but want to see any and all implementation code behind it? With the interface declaration code opened in the editor, place your cursor on the interface name and press F4 (or right click on it and select "Open in Type Hierachy"). The "Type Hierarchy" view will open. Highlight any "Impl" class, and the methods it implements will be displayed in the bottom pane of the type hierarchy window. Double click on a method name, and Eclipse will open the source code that implements that method.
• If you see a property in portal.properties and you want to know more about it (i.e. how does it work, where in the code is it used, etc)? You can combine the above features to get to that information quickly. First, almost every property defined in portal.properties has a corresponding Java string type located in the class com.liferay.portal.kernel.util.PropsKeys. So, first thing you should do is use Ctrl+Shift+T to open the type editor, type in PropsKeys, and open that source file. Search that file for the property you are intersted in. Place your cursor over the Java member that the value is assigned to (for example, the "upgrade.process" string is assigned to the static String member PropsKeys.UPGRADE_PROCESS). Next, right click on the member, and select "References -> Workspace." Eclipse will now find all the code where the property is referenced and list it in the "Search" view. Double click on an entry to see the source code.

See Also #

• Eclipse Plugin
• Development in the ext environment