Developing OpenCms with Eclipse

Developing OpenCms with Eclipse

This entry is made for OpenCms users who want to enhance OpenCms for their own requirements. The target is to enhance the OpenCms core and/or build new OpenCms modules. For that you have to setup the complete OpenCms development environment and you have to know how to build new OpenCms installation. Eclipse is the OpenCms development environment. In the first subchapter is described how to checkout the OpenCms core, and how to build an OpenCms installation in Eclipse. The second subchapter will describe how to create and build own OpenCms modules.

OpenCms Core

The OpenCms core provides the main OpenCms functionality. You can install the OpenCms core source code in your Eclipse in order to analyze it and learn how OpenCms works internally. It should not be necessary to modify anything in the OpenCms core for your project. We strongly recommend staying with the unmodified public core distribution. Creating a modified OpenCms core version will only lead to a dead end for your project since you will not be able to install important updates without incorporating your changes to the standard core. In the first subchapter is described how to checkout OpenCms Core project. How to configure OpenCms Core project in Eclipse is described in the second subchapter. In the third subchapter it is described how to check OpenCms Core code. How to build OpenCms Core project with Ant is described in the fourth subchapter.

Check Out the Project

OpenCms Core is accessible for free. The code is in a CVS repository. Following it is described how to checkout this code to your local computer.

Please Note: You can checkout all stable OpenCms Core Versions which were ever published. That means you can checkout the last stable version and also special numbered public OpenCms Core Versions, for example 7_0_5. In order for Eclipse to know which Branches or CVS Tags exists, you need to configure a file that has these information available. We usually use the Ant build file build.xml from the OpenCms core project to get this information. To check out the project from the CVS repository, you should create a new project, using the "New Project" wizard of Eclipse. For this go to the "File > New > Project..." menu option of Eclipse, and select the "CVS > Projects from CVS" option.

After clicking the "Next" button, a dialog for entering the repository information is displayed, enter the following information:

• Host: cvs.opencms.org
• Repository Path: /usr/local/cvs
• User: anon
• Password: anon
• Connection Type: pserver
• Use Default Port: true (leave it checked, as default)
• Save Password: check it if you do not want to enter the CVS password anytime Eclipse needs to connect to the server.

Click the "Next" button, to select the module name. Set it to opencms

Then, click the "Next" button, and select to "Checkout as a project configured using the New Project Wizard".

Click the "Next" button, to select the version to check out. Click the "Refresh Tags" button to get a list of possibilities, the most used is HEAD which is the last stable version. In choice "Branches" you can get another last version, for example dev_7_0_5 is OpenCms Version 7.0.5. When no branch versions are listed you have to select file build.xml in mask opened with button "Configure Tags".

Click the "Finish" button and the "New Project" wizard appears again. Now select "Java Project". Click the "Next" button and the "Create new Java Project" dialog is shown. Here enter the following information:

• Project Name: OpenCms
• Contents: Create a new project in the workplace
• Project Layout: Create a separate source and output folders. Click on "Configure Default...", and configure the "Source and output folder" checking folders, leaving the defaults: src for the Source folder and bin for the output Folder.

Link "Configure default" in section "Project layout" should have the following settings.

Click the "Finish" button. Now the source code should be downloaded from the CVS repository. This can take some minutes, depending on your Internet connection.

Configuring the OpenCms Project

After importing code from OpenCms Core you have to configure project to be able to compile it in Eclipse and to build OpenCms Core with your personal enhancements. You have to configure project classpath and project source folder. How to configure project classpath is described in the first subchapter. In the second subchapter the project source folder is described.

Configuring the Project’s Classpath

After the checkout, Eclipse will try to immediately compile the project, and you will have several errors, this is because you have to add the needed external libraries to the classpath. For this, go to the "Project > Properties" menu option of Eclipse, opening the "Project Properties" dialog. Select the "Java Build Path" option on the left, and the "Libraries" tab on the right, there click the "Add Jars..." button and add all jars in folders:

• OpenCms/lib/compile/
• OpenCms/lib/runtime/
• OpenCms/modules/org.opencms.frontend.templateone.form/resources/system/modules/org.opencms.frontend.templateone.form/lib/
• OpenCms/webapp/setup/database/oracle/
• OpenCms/modules/org.opencms.frontend.layoutpage/resources/system/modules/org.opencms.frontend.layoutpage/lib/freemarker-2.3.6.jar
• OpenCms/webapp/setup/database/ and sub folder with jar-archive to belonging DB-driver

Now click the "Ok" button, and Eclipse should automatically build the project again. So, every compile error should disappear.

Configuring the Project’s Source Folders

In addition to the default src folder OpenCms has 4 source folders:

• OpenCms/src: Here you find the OpenCms core classes (all classes found in opencms.jar)
• OpenCms/src-components: Here you find the source code for some libraries used by OpenCms, like the Upload Applet, or the Ant extensions.
• OpenCms/src-modules: Here is the source code of all modules located.
• OpenCms/src-setup: Setup source code.
• OpenCms/test: Here are the JUnit test cases located.

To set up these source folders, open the properties dialog for the project, select the "Java Build Path" on the left side, and then the "Source" tab on the right side.

Do not forget to set two exclusion filters to the OpenCms/test source folder:

• data/**
• org/opencms/util/ant/

Therefore you have to select in source OpenCms/test "Excluded" and press the "Edit" button. Then you have to put in the two exclusion filters separately.

Building OpenCms with Ant

To build OpenCms Core you should use Ant. Using Ant allows changing Java classes and automatically building jar files, without manual copying these jar files into running OpenCms installation. That means, if you change Java classes and build OpenCms in Eclipse you have nothing to do else, because Eclipse builds a jar file and this file is automatically updated for the OpenCms installation, too. If you do not use Ant you have more complexity to do, to bring your enhancements into your running OpenCms installation. In the first subchapter is described how to configure Ant. In the second subchapter is described how to use Ant to build OpenCms Core project.

Configuring Ant

To be able to compile the project, you will need to configure Ant. For this, go to the "Window > Preferences..." menu option of Eclipse, select the ‘Ant > Runtime’ node on the left and the "Classpath" tab on the right, and add the following jar files to the "Global Entries":

• OpenCms/lib/compile/ant-contrib-1.0b1.jar
• OpenCms/lib/compile/ant-opencms-1.1.jar
• OpenCms/lib/runtime/commons-beanutils-1.8.0.jar
• OpenCms/lib/runtime/commons-collections-3.2.jar
• OpenCms/lib/runtime/commons-digester-1.8.jar
• OpenCms/lib/runtime/commons-logging-1.1.1.jar

Then select the "Properties" tab and add the following "Global properties" by clicking the "Add property..." button:

• tomcat.home: Indicates the servlet container location
• app.name: indicates the context name of the OpenCms instance to update (see next section)
• opencms.output: indicates where to store compilation files

After that select build.xml in the Eclipse Explorer View with mouse, press right mouse key and choose "Run As" and "External Tool Configuration". In the tab "Target" you can select the following often needed options:

• OpenCms > bindist: Use this target to get a distribution zip file with all modules. The zip file is stored at ${opencms.output}/zip/opencms_${opencms.version}.zip
• OpenCms > clean: Use this target to purge the output folder, do not use the "OpenCms Common Modules > clean" target that only cleans the output files of the selected modules.
• OpenCms > tomcat.update: Updates a previous installed OpenCms instance. It copies a new compiled opencms.jar in the ${tomcat.home}/${app.name}/WEBINF/ lib (or ${jboss.home}/${app.name}.war/WEB-INF/lib) folder.
• OpenCms Common Modules > war: This target generates a new war file with the selected modules. You can find the generated file under ${opencms.output}/build/opencms.war

Compiling OpenCms with Ant

To execute a build target select the Ant build menu and select the build.xml to build. Make sure, that console in Eclipse is opened. You can open that with "Window" > "Show View" > "Console".

OpenCms Modules

We do not advise to make changes in OpenCms Core. One reason is that your private OpenCms Core enhancements are overwritten with an OpenCms Core Update. But we want to say again that good OpenCms Core enhancements are always welcome, but not every external developed OpenCms Core enhancement can become a part from public OpenCms Core. That’s why we advise to create own modules for your OpenCms needs. In the first subchapter is described how to create own OpenCms modules. In the second subchapter is described how to compile these modules to use them in the OpenCms Installation.

Create OpenCms Modules

Analogue to other OpenCms Modules is to create a new package in OpenCms/src-modules/ folder. Here new Java classes have to come in. To create such new package in Eclipse you have to select the OpenCms/src-modules/ directory and in the menu "File" > "New" > "Package". Other new module resources like JSP pages are directly created in OpenCms. After OpenCms Module export, these resources have to become imported into Eclipse into the OpenCms/modules/<new package>/resources/ directory. To import these resources into Eclipse create with any file explorer in Eclipse workspace directory OpenCms/modules/<new package>/resources/ directory and copy system directory and manifest.xml from exported OpenCms Module into here.

Building OpenCms Modules with Ant

To build OpenCms Modules you have to use Ant. Using Ant allows changing Java classes and building jar files automatically, without manually copying these jar files into running OpenCms installation. Administration resources like JSP pages are controlled with module manifest.xml file. Manifest file only changes when OpenCms resources for module are new created. Only with Ant the jar file belongs to module and if a jar file is new built in Eclipse, it automatically is updated in module and therefore directly in OpenCms. In the first subchapter is described how to configure Ant. How to use Ant to build OpenCms Modules is described in the second subchapter.

Configure Ant to compile OpenCms Modules

To be able to compile the project, you will need to configure Ant additional to the configuration for OpenCms Core. For this, go to the "Window > Preferences..." menu option of Eclipse, select the "Ant > Runtime" node on the left, and the ‘Classpath’ tab on the right and select the "Properties" tab and add following "Global properties" by clicking the "Add property..." button:

• modules.selection.mode: This optional property controls how to select the modules to build/update, the following values are possible:

 + interactive: interactive GUI based module selection, this is the default.
 + selection: module selection based on modules.common.selection property
 + all: module selection based on modules.common.all property defined in the file: all-modules.properties

• modules.common.selection: set this property to a comma separated list of module names if you set the modules.selection.mode to selection. After that select src-modules/build.xml in the Eclipse Explorer View with mouse, press right mouse key and choose "Run As" and "External Tool Configuration". In the tab "Target" you can select the following often needed options:

• OpenCms > bindist: Use this target to get a distribution zip file with all modules. The zip file is stored at ${opencms.output}/zip/opencms_${opencms.version}.zip
• OpenCms > clean: Use this target to purge the output folder, do not use the "OpenCms Common Modules > clean" target which only cleans the output files of the selected modules.
• OpenCms > tomcat.update: Updates a previous installed OpenCms instance. It copies a new compiled opencms.jar in the ${tomcat.home}/${app.name}/WEBINF/ lib (or ${jboss.home}/${app.name}.war/WEB-INF/lib) folder.

Additionally you have to enhance OpenCms/modules/all-modules.properties. Here are listed all OpenCms modules. You have to write a comma and a backslash after the last module name entry. Then you have to write your module name in a new line.

Compiling OpenCms Modules with Ant

To execute a build target select the Ant build menu and select the build.xml to build. Make sure, that console in Eclipse is opened. You can open that with "Window" > "Show View" > "Console".

During building modules in Eclipse appears a window where you can select modules to build new. If you press button “None” and you select your module, only your new module will become created.