Installation and setup of Eclipse IDE

Introduction

This article is a step-by-step guide to install and setup Eclipse Integrated Development Environment (IDE) for Openbravo ERP development.

"Eclipse is an open source community whose projects are focused on building an open development platform comprised of extensible frameworks, tools and runtimes for building, deploying and managing software across the life cycle. A large and vibrant ecosystem of major technology vendors, innovative start-ups, universities, research institutions and individuals extend, complement and support the Eclipse platform.", according to Eclipse's community. For more general or technical information concerning Eclipse IDE, please visit:

• Eclipse's introduction and documentation
  • Eclipse Newcomers Frequently Asked Questions (FAQ).
  • Eclipse's documentation and help.
• Eclipse's community
  • Eclipse's community.
  • Eclipse Zone: community for Eclipse users and developers.
  • Eclipse Plugin Central: Eclipse plug-in resource center.
• Eclipse's resources and tutorials
  • Eclipse's Getting Started resources.
  • Eclipse's resources.
  • Getting started using Eclipse.
  • Eclipse and Java video tutorials.
  • An introduction to Eclipse for Visual Studio users.
  • Eclipse IDE keyboard shortcuts.
  • Eclipse shortcut keys.

Some of the major advantages of using Eclipse IDE for Openbravo ERP development are:

• Code completion of all Openbravo ERP Java classes.
• Error and warning detection before actual Ant build.
• Quick and easy navigation between packages and methods.
• Real-time debugging.
• Java compilation on individual class level.
• With a little effort, a lightning fast deployment of changes to Tomcat without any builds or restarts.

Openbravo ERP's source code is ready to work with Eclipse's IDE projects schema.

• src-core, src-trl and src-wad are now folders that contain complete Eclipse subprojects, with a compilation output (build), source code (src) folders and necessary libraries for each one.
• The build of source root for the ERP compilation.
• WebContent. A new folder named WebContent in the root source which contains all necessary files for the Apache Tomcat context (everything but the compiled classes).
• *.launch files. These new files link Ant tasks to Eclipse IDE and allows them to be executed within the IDE.

Minimum requirements

First, it is important to set up the environment in which Openbravo ERP works correctly, i.e.:

• PostgreSQL or Oracle database
• Sun Java Development Kit (JDK)
• Apache Tomcat
• Apache Ant

In addition a system with a minimum of 1GB of memory is required.

Subversion client

Install Subversion 1.5 (SVN 1.5) version control system client. Select the specific project package for your operating system.

XML processors

Download stax-api-1.0.1.jar (StAX) and wstx-asl-3.0.2.jar (Woodstox) XML processors. Then, copy these two files to lib folder inside your Ant folder.

Eclipse IDE

Download Eclipse Ganymede IDE for Java EE Developers (Eclipse 3.4).

Installing Eclipse IDE amounts to uncompressing the files into a folder of your choosing.

Open Eclipse IDE and create a new workspace by typing where in your hard-drive you want this workspace to be created.

• When clicking on OK button, a new workspace is created. Close the Welcome tab (get this tab back again by clicking Help > Welcome) and you will see your workspace layout.

Subversive

Current version of Subversive plug-in (0.7.2) is not full Subversion 1.5 capable so you will not be able to commit Openbravo repositories with it. Please use Subclipse plug-in instead.

If you had install Subversive plug-in, Please follow these steps to uninstall it or watch it on-line: go to Help > Software Updates directly.

You will have to uninstall (in this order):

• JDT Ignore extensions
• SVNKit 1.x
• Subversive SVN Connectors
• SVN Team Provider

Additional Plugins

Next to the standard Eclipse IDE two additional plugins are required for developing Openbravo:

• subclipse (subversion integration), Subclipse help.
• openarchitectureware (for model-driven development)

These can be installed as follows: Help > Software Updates and then the Available Software tab. Here you can add a so-called update site from which the new plugins can be installed. Add the new site for subclipse (the one for openarchitectureware is already there), click add site and enter the following url: http://subclipse.tigris.org/update_1.4.x

Then select the subclipse tree and the openarchitectureware tree:

and click the install button. Eclipse should now be downloading the required plugins, choose the default options (next, accept license etc.). After downloading restart Eclipse.

Before getting started

Before getting started, please follow these few tips to configure properly Eclipse IDE for Openbravo ERP development.

First of all, tune Eclipse IDE performance and avoid OutOfMemoryExceptions problems by editing and overwriting eclipse.ini file (inside Eclipse installation directory) with the following lines:

• For a 1024 MB RAM machine:

-showsplash
org.eclipse.platform
-framework
plugins/org.eclipse.osgi_3.4.2.R34x_v20080826-1230.jar
-vmargs
-Dosgi.requiredJavaVersion=1.5
-Xms40m
-Xmx512m
-XX:MaxPermSize=128m

• For a 2048 MB RAM machine:

-showsplash
org.eclipse.platform
-framework
plugins/org.eclipse.osgi_3.4.2.R34x_v20080826-1230.jar
-vmargs
-Dosgi.requiredJavaVersion=1.5
-Xms40m
-Xmx1024m
-XX:MaxPermSize=256m 

• This step is only required once since it affects your Eclipse IDE installation, hence, all your workspaces.
• More information about this issue:
  • Tuning Eclipse IDE performance and avoid OutOfMemoryExceptions problems.
  • Faster Eclipse on slower machine.
  • Linux, launchers and the PermGenSpace issue.

Eclipse workbench

Secondly, download workbench.xml file and copy it inside your_worspace_path/.metadata/.plugins/org.eclipse.ui.workbench folder, overwriting existing one (please notice that .metadata folder could be hidden, and that you have to change the name Workbench.xml to lowercase workbench.xml).

This step will configure your Eclipse IDE workbench, that is, the set of editors and views used during a development.

Eclipse workspace

The next step is to set the standard preferences used in developing Openbravo. Open Eclipse IDE and access your workspace.

Download openbravo-eclipse-prefs.epf file.

• Import workspace preferences by clicking on File > Import, selecting General > Preferences and clicking on Next button.

• Browse to openbravo-eclipse-prefs.epf file, select Import all radio button and click on Finish button.

This step will configure some preferences for effective Openbravo ERP development using Eclipse IDE. You can also set the preferences manually, see Eclipse Preferences section below.

Copy stax-api-1.0.1.jar and wstx-asl-3.0.2.jar files from Ant lib folder to Eclipse IDE lib folder (usually eclipse/plugins/org.apache.ant/lib/). Then, go to Eclipse IDE Window > Preferences... menu element and select Ant > Runtime > Ant Home Entries (Default). Click on Add External JARs... button and add stax-api-1.0.1.jar and wstx-asl-3.0.2.jar.

Click on Window > Preferences... then on Validation. Un-check Allow projects to override these preference settings and check Suspend all validators check boxes.

Click on Window > Preferences.... Click on Team > SVN then select SVN Kit as SVN Connector (if you do not see SVN item in the menu you probably did not install Subclipse plug-in).

Click on Window > Preferences... then on Team > SVN > Label Decorations. In Text Decorations tab you can append useful information such as Revision and Author to files, folders and projects.

Click on Window > Preferences... then on Java > Compiler. Please make sure that 1.6 is selected in Compiler compliance level drop-down list.

Associate special file types to a XML editor. Click on General > Content Types then select Text > XML. Then click on Add... button (bottom right) and type *.xsql in File type text box.

Repeat these steps to associate *.jrxml and *.fo files to the default XML editor.

More information on Eclipse IDE workspace configuration:

• Eclipse's workbenches and workspaces.
• Effective Eclipse: setup your environment.
• Create New Eclipse Workspace - With All Your Old Settings.
• Effective Eclipse: Custom Templates.

Checking out Openbravo ERP source code

Here we go! By checking out trunk source code from Openbravo Subversion (SVN) repository you will be able to:

• Work with the last Openbravo ERP development source code and update it easily.
• Commit your bug fixes or new developments to Openbravo SVN repository. See how to obtain write access to Openbravo SVN repository.

To download Openbravo ERP trunk files into your empty workspace:

• Click on File > New > Other.... In New pop-up window, select SVN > Projects from SVN and click on Next button.

• Create a new repository location. In General tab, type https://dev.openbravo.com/svn/openbravo/ in URL text box and check Validate Repository Location on finish check box. If you want to check out the last stable source code tag of Openbravo ERP, type https://dev.openbravo.com/svn/openbravo/tags/.

• In Advanced tab, uncheck Enable Structure Detection check box and click on Next button.

• When repository location validation finishes, select trunk folder then click on Finish button. If you want to check out the last stable source code tag of Openbravo ERP, select tag folder then r2.40 folder.

• In Check Out As window, select Check out as a project with the name specified radio button, type openbravo as project name, check Checkout recursively check box then click on Next button. Do not use a project name different from openbravo otherwise you will experience odd behaviours. A bug has been reported at this subject.

• Check Use default workspace location check box then click on Finish button.

• Openbravo ERP source code check out starts. This process may take a while, depending on the speed of your Internet connection.

• Once check out finishes, you will see in your Project Explorer tab a new project named openbravo followed by a revision number.

Openbravo.properties file

Values of Openbravo environment variables need to be configured within Openbravo.properties file.

• If you checked out trunk source code, please read Openbravo.properties article in order to properly configure this file.

ant -f build.xml.template setup

• Once the assistant has finished, come back to Eclipse IDE, right click on openbravo project and select Refresh option.

• Once the project has been refreshed, notice that, in config folder, Openbravo.properties file has been created with all the previously set up information.

Importing Openbravo ERP projects

The following projects are needed into your workspace before compiling: openbravo, OpenbravoCore, OpenbravoWAD and OpenbravoTrl. Please note that the order of importing projects must follow the sequence below.

openbravo

openbravo project contains Openbravo ERP itself: forms, reports, call-outs, combos, processes and so on.

Please notice that, in the case that you checked out the source code from the Subversion repository using Eclipse IDE, openbravo project does not need to be imported.

Otherwise, if you obtained Openbravo ERP source code checking it out via command line SVN or Tortoise SVN or via the Bitrock installer, follow the same steps as in OpenbravoCore to import openbravo project from openbravo folder.

OpenbravoCore

OpenbravoCore project contains the core components: XmlEngine (View), SQLC (Model), HttpBaseServlet (Controller) and ConnectionPool.

• Go to File > Import... menu item.
• In Import pop-window, select General > Existing Projects into Workspace then click on Next button.

• Browse to src-core folder in your project's folder then click on OK button. Check that OpenbravoCore project is selected then click on Finish button.

• Notice that OpenbravoCore project has been added to your Project Explorer tab.

OpenbravoWAD

OpenbravoWAD project contains the source code of the Wizard of Application Dictionary (WAD).

Follow the same steps as in OpenbravoCore to import OpenbravoWAD project from src-wad folder.

OpenbravoTrl

OpenbravoTrl project contains the source code of the translator.

Follow the same steps as in OpenbravoCore to import OpenbravoTrl project from src-trl folder.

Defining Tomcat server

Once all projects have been properly imported, it is time to define an Apache Tomcat server within Eclipse IDE.

Handling Tomcat through Eclipse IDE is a much more comfortable and rapid way of seeing changes made during development. In fact, there is no need to deploy openbravo context to the typical Tomcat webapps folder. Following these simple steps, a folder named tomcat containing configuration, logs and context files will be created inside your workspace.

• In Servers tab, right click then select New > Server.

• In New Server pop-up window, select Apache > Tomcat v6.0 Server then click on Next button.

• Browse to your Tomcat installation directory to fill the corresponding text box.

• Select openbravo from Available projects list then click on Add button.

• Once openbravo project is moved to Configured projects list, click on Finish button.

• Tomcat v6.0 Server is now available in Servers tab.

• Right click on it then select Open.

• Overview file opens.

• Under Server Locations, select Use custom location (does not modify Tomcat installation) radio button. Then type tomcat in Server path text box and webapps in Deploy path text box.
• Under Ports, you can change port numbers if required.
• Under Server Options, select Serve modules without publishing check box if you want to see file modifications very quickly. By doing this, necessary files for Openbravo ERP to run are taken directly from WebContent folder inside Project Explorer tab. If you do not check this option, an openbravo context will be deployed (published) inside your_worskpace_name/tomcat/webapps folder. Anyway, this option can be checked or unchecked at any time and openbravo context will disappear and appear from your_worskpace_name/tomcat/webapps folder.
• Save Overview file.
• Outside Eclipse IDE, browse to your workspace path and notice that there are three folders: openbravo, Servers and tomcat.
• tomcat folder contains:
  • conf folder with necessary files to configure Tomcat.
  • logs folder with a log file of the context.
  • webapps folder with default ROOT context and openbravo context (if published).

More information and common issues on Tomcat integration within Eclipse IDE can be found at Eclipse's Wiki.

Compiling and building Openbravo ERP

It is time to compile and build Openbravo ERP using Eclipse IDE! :)

Checks before the compilation and build

Before starting the compilation and building of Openbravo ERP, please make the following checks:

• In order to avoid problems with character sets, select openbravo, OpenbravoCore, OpenbravoTrl and OpenbravoWAD projects and click on Project > Properties. Then, in Properties pop-up window, click on Resource and select UTF-8 in Text file encoding panel in case Inherited from container (UTF-8) option is not selected.

• Make sure that you have inside your Project Explorer tab:
  • openbravo project
  • OpenbravoCore project
  • OpenbravoTrl project
  • OpenbravoWAD project
  • Servers folder

• Check also that the following Ant tasks are inside Run > External Tools list:
  • eclipse.install.source
  • create.database
  • eclipse.trl.lib
  • eclipse.wad.lib
  • eclipse.compile.complete

• If any Ant task is missing from Run > External Tools list, select Run > External Tools > Organize Favorites... and Add them to the list.
• If you were not able to add the missing Ant tasks to Run > External Tools list, open Ant tab by selecting Window > Show View > Other... > Ant then drag build.xml file (inside general folder) to Ant tab. You will be able to execute Ant tasks by selecting them and click on Run the Selected Target icon .

{{Fancydancy|Important note: when running an Ant task from the Eclipse external tools menu then the following error can occur: The environment variable JAVA_HOME is not set. To solve this, check out this page Environment Installation and follow the guidelines for setting JAVA_HOME in your specific environment. Restart Eclipse after setting JAVA_HOME.

Eclipse IDE compilation and build specifics

Openbravo ERP compilation using Eclipse IDE differs from command line method in one major aspect. Using Eclipse IDE, projects need:

1. First to be compiled, obtaining *.java files inside build/javasqlc folder.
2. Then built, obtaining *.class files inside build/classes folder.

Using command line, compilation and build happen in a single step.

There are two ways to compile and build Openbravo ERP using Eclipse IDE:

1. In a single step by using eclipse.install.source Ant task.
2. Component by component in the following order:
   1. The database.
   2. OpenbravoCore project.
   3. OpenbravoWAD project.
   4. OpenbravoTrl project.
   5. openbravo project.

eclipse.install.source

By launching eclipse.install.source Ant task, the database will be created and OpenbravoCore, OpenbravoWAD, OpenbravoTrl and openbravo projects will be built.

• Select Run > External Tools > eclipse.install.source Ant task.
• In Console tab, see the progress of this process. Check that it ends with a BUILD SUCCESSFUL message.
• Once built, check that, inside Project Explorer tab, error icons on the left side of OpenbravoWAD, OpenbravoTrl and openbravo projects have disappeared.
• If you find any error, please take a look at Compilation and build issues section.

Database

First step of Openbravo ERP building is the creation of the database from *.xml files.

• Go to Run > External Tools menu item then click on create.database Ant task.
• See the progress of this process in Console tab.
• If database parameters have been well configured inside Openbravo.properties file, create.database process should end with a BUILD SUCCESSFUL message.
• If you find any error, please take a look at Compilation and build issues section.

OpenbravoCore

• In Project Explorer tab, select OpenbravoCore project then select Project > Build Project menu item (see compilation errors in Problems tab).
• If you find any error, please take a look at Compilation and build issues section.

OpenbravoWAD

• Select Run > External Tools > eclipse.wad.lib Ant task.
• In Console tab, see the progress of this process. Check that it ends with a BUILD SUCCESSFUL message.
• Once built, check that, inside Project Explorer tab, error icon on the left side of OpenbravoWAD project has disappeared.
• If you find any error, please take a look at Compilation and build issues section.

OpenbravoTrl

• Select Run > External Tools > eclipse.trl.lib Ant task.
• In Console tab, see the evolution of this process. Check that it ends with a BUILD SUCCESSFUL message.
• Once built, check that, inside Project Explorer tab, error icon on the left side of OpenbravoTrl project has disappeared.
• If you find any error, please take a look at Compilation and build issues section.

openbravo

• Select Run > External Tools > eclipse.compile.complete Ant task.
• In Console tab, see the evolution of this process. Check that it ends with a BUILD SUCCESSFUL message.
• Once built, check that, inside Project Explorer tab, error icon on the left side of openbravo project has disappeared.
• If you find any error, please take a look at Compilation and build issues section.

Compilation and build issues

Issue 1

Openbravo ERP compilation tasks for Eclipse IDE have been changed recently. If you are using a source code prior to revision 6192 (e.g., Openbravo ERP 2.35 MP5 or Openbravo ERP 2.40 beta), perform after each compilation tasks:

• Inside Project Explorer tab, right click on the project that fails and Refresh it.
• Then select Project > Build Project menu item (see build errors in Problems tab).

Issue 2

Before going on, please make sure that no errors remain in Problems tab.

• If errors persist, go to Project > Clean... menu item, select Clean all projects radio button, check Start a build immediately check-box then click on OK button. By cleaning a project, all the content inside build folder (i.e., *.class files) is deleted.

• If you still see a lot of errors inside Problems tab (more than 1.000), please check the dependency between openbravo and OpenbravoCore projects. For this purpose, select openbravo project then right click and select Properties. Inside Java EE Module Dependencies section, make sure that OpenbravoCore check-box is ticked (if it is not, select it) then click on OK button. Finally, go to Project > Clean... menu item, select openbravo project, check Start a build immediately check-box then click on OK button.

Issue 3

If errors still remain (do not care about warnings), you will have to delete and import the project in error, compile and build Openbravo ERP or define Tomcat server again depending on the error message.

Issue 4

If you put your development environment ID inside Openbravo.properties file, please check that all is right by running the following SQL script in your database administration tool (e.g., pgAdmin III or phpPgAdmin for PostgreSQL and Oracle SQL Developer or Toad for Oracle):

SELECT CURRENTNEXTSYS FROM AD_SEQUENCE WHERE NAME='AD_Column';

Result must equal your development environment ID multiplied by 100.000 (one hundred thousands). If it does not, correct development.environment.id variable value inside Openbravo.properties file and run create.database Ant task again.

Running Openbravo ERP

Once Openbravo ERP has been properly compiled and built, it is ready to be used via your web browser.

• Inside Eclipse IDE, start Tomcat server by clicking on Start the server icon in Servers tab.
• Once it starts, open your web browser and type your URL in the form http://hostname:port/context_name/ (e.g., http://localhost:8080/openbravo/).

• Type Openbravo in Username text box and openbravo in Password text box then click on Login button. Congratulations! You are done with Openbravo ERP installation using Eclipse IDE :-)

• To stop Tomcat server, click on Stop the server icon in Servers tab inside Eclipse IDE.

Debugging Openbravo ERP

With the Eclipse IDE, one can easily debug the Java code within Openbravo ERP. A brief introduction is presented in this guide:

• Inside Eclipse IDE, start Tomcat server in debug mode by clicking on Start the server in debug mode icon in Servers tab.
• Once it starts, open your web browser and type your URL in the form http://hostname:port/context_name/ (e.g., http://localhost:8080/openbravo/).
• Access Debug view automatically or by clicking on Debug perspective icon.

• General Debug view (or perspective) opens and presents several tabs.
• The main tab is the one showing files to be debugged. Breakpoints can be added and deleted by double-clicking in the left side rose colored part of the file.

• Breakpoints tab shows all breakpoints defined all over the code. This tab also allows to delete or skip desired ones.

• Navigate Openbravo ERP as usual via your web browser. Once the application reaches an active breakpoint, execution stops and the control is handed over to you.
  • Move to the next code line by clicking on Step Over icon or by pressing F6 key.
  • Jump inside a method by clicking on Step Into icon or by pressing F5 key.

• • Return from a method by clicking on Step Return icon or by pressing F7 key.
  • Jump to the next breakpoint or finish debugging by clicking on Resume icon or by pressing F8 key.
  • Stop debug server by clicking on Terminate icon or by pressing Ctrl+F2 keys.

• Track the values of variables inside the Variables tab.

Please find more information on how to debug *.java files within Eclipse IDE following:

• Eclipse and Java: using the debugger.
• Tips and tricks for debugging in Eclipse.
• How to debug a remote Java application.

Eclipse Preferences

This section describes which preferences to set in eclipse to get maximum performance/productivity and to ensure that you as a developer conform to Openbravo standards. These preferences can be set by downloading and importing this file openbravo-eclipse-prefs.epf, or can be set manually (as described in this section).

To set the Eclipse preferences go to Window > Preferences

Formatting: Java Conventions

This is a must-do. Set the code formatter to use the Java conventions.

Editor Save Actions

Eclipse is able to perform automatic actions when saving source files. One of the actions is formatting the source code and organizing imports. This is an important Must-Do. Set the save action as outlined below:

So check "perform the selected actions..." and then Format Source Code, Organize Imports and Additional Actions. Then in additional actions click configure and go to code style tab and change the variable declarations section to set the modifier final for local variables (and uncheck private fields).

Disable Validation

Eclipse automatically validates xml, jsp and html files. Although this can be a usefull feature it is very resource intensive. The Openbravo development project has many xml and html files which makes it impossible to use this feature in automatic build mode. Disabling this feature makes it possible to work with Openbravo in automatic build mode. The validation can be disabled in the Validation preferences (in the bottom of the preferences view). Disable all automatic validation by unchecking the relevant checkbox.

Compiler settings

Eclipse can automatically detect and flag potential programming problems. This is defined in the Java > Compiler > Errors/Warnings section. The standard settings are mostly okay but set the following errors/warning condition to Warning (from Ignore):

• Code Style
  • Undocumented empty block
  • Parameter Assignment
• Potential programming problems
  • Possible accidental boolean assignment
  • Empty Statement
  • Enum type constant not covered in switch
  • Switch case fall-through
  • Potential null pointer access
• Name shadowing and conflicts
  • Field declaration hides another field or variable
  • Local variable declaration hides another field (but keep include Constructor and setter method parameters unchecked)
• Deprecated and restricted API
  • Deprecated API: check the Signal overriding or implementing deprecated method

Developing Openbravo ERP

Development using Eclipse IDE follows the same principles as command line development of Openbravo ERP. Please find more information about Openbravo ERP development at:

• Openbravo Development Environment (ODE) tasks.
• Openbravo ERP development process management.
• Openbravo ERP developer's manual.
• Other tools for Openbravo ERP development.

Tips and Shortcuts

Build Problems

Eclipse will display compile and other problems in the Problems view. There is one problem which is important to keep in mind when working with eclipse, that's the build path problem. A build path problem is made visible in the Problem view but has as consequence that eclipse will not compile the classes. So any change you make is not visible in the runnable code. This is not directly obvious when you change your code and debug and then notice that the debugger is not insync with your source code. So if you encounter the situation that your source changes are not reflected when running eclipse then check

Search Type: Shift-Ctrl T

A very handy feature is to search for a type using its name. Open the search window by pressing the keys shift-ctrl-t at the same time. Note that this feature is available in the java and java EE perspectives.

Breadcrumb

The breadcrumb feature (enabled through the breadcrumb button in the top) allows you to see where a file is located in the project. This is very handy when you open a file as part of a search action (so not by browsing the explorer tree).

Breakpoint expressions

You can set breakpoints by right-clicking in the left of the source (when opened in the editor). A nice feature is that you can make the breakpoint conditional by entering a boolean expression in the breakpoint properties. The expression editor is context aware and has support for code completion. Note that setting the breakpoint condition has a fair amount of impact on the performance of the debug session.

Open type (f3)

You can open a type (a class) or go to its declaration by setting the cursor on the variable or the declaration and pressing f3 or ctrl-left-mouseclick.

Call Hierarchy, type hierarchy etc.

Right clicking on a declaration or class allows you to see the call and type hierarchy and other usefull information.

Known issues

Here is a list of known issues with Openbravo ERP and Eclipse IDE:

• Openbravo's Frequently Asked Questions (FAQ).
• Eclipse's IDE known issues.
• Subversion checksum mismatch.

Support

For any question or doubt regarding Eclipse IDE installation and setup, post them in Openbravo Developers forum or join #openbravo IRC channel in Freenode.