Introduction to iDempiere Development

Level: Intermediate Module: General Foundation 10 min read Lesson 16 of 47

Overview

  • What you’ll learn: How to set up a complete iDempiere development environment with Eclipse IDE, clone and build the source code, run iDempiere from the IDE, and make your first code change.
  • Prerequisites: Lessons 1-12 (Beginner level), Java programming fundamentals
  • Estimated reading time: 30 minutes

Introduction

Up to this point in the curriculum, you have been configuring iDempiere through the Application Dictionary, callouts, and workflows — all powerful tools that do not require modifying iDempiere’s source code. But to build plugins, create custom model classes, implement complex business logic, or contribute to the core project, you need a proper development environment.

This lesson walks you through the complete setup: installing prerequisites, cloning the source, importing into Eclipse, configuring the target platform, and running iDempiere from the IDE with full debugging support.

Prerequisites

Before you begin, ensure you have the following installed on your development machine:

Java 17 JDK

iDempiere requires Java 17 (LTS). Download and install OpenJDK 17 from Eclipse Temurin or your preferred JDK distribution.

# Verify Java installation
java -version
# Expected output: openjdk version "17.x.x" ...

# Verify JAVA_HOME is set
echo $JAVA_HOME
# Should point to your JDK 17 installation directory

Eclipse IDE for RCP and RAP Developers

iDempiere is built on the Eclipse RCP (Rich Client Platform) and uses the OSGi framework extensively. You must use the Eclipse IDE for RCP and RAP Developers edition — the standard Java edition lacks the PDE (Plugin Development Environment) tools required for iDempiere development.

Download from eclipse.org/downloads/packages. Look for “Eclipse IDE for RCP and RAP Developers”.

PostgreSQL

You need a PostgreSQL database (version 14 or later) with an iDempiere database loaded. If you completed the installation lesson (Lesson 3), you already have this. For development, a local PostgreSQL instance is recommended.

Git

Git must be installed for cloning the source repository.

# Verify Git installation
git --version
# Expected: git version 2.x.x or later

Cloning the iDempiere Source

The iDempiere source code is hosted on GitHub. Clone the repository to your local machine:

# Clone the main repository
git clone https://github.com/idempiere/idempiere.git

# This creates an 'idempiere' directory with the full source
cd idempiere

# Check available branches
git branch -a

# The 'development' branch is the latest active development branch
# The 'master' branch tracks stable releases
git checkout development

The clone is approximately 1-2 GB and includes the complete project history. On a typical broadband connection, this takes a few minutes.

Importing into Eclipse

Follow these steps carefully — the import process is specific to Eclipse PDE projects:

  1. Launch Eclipse and select a new workspace (do not reuse an existing workspace from other projects).
  2. Go to File > Import > General > Existing Projects into Workspace.
  3. Set the Root Directory to the cloned idempiere folder.
  4. Eclipse will detect all projects. Ensure all projects are selected.
  5. Do NOT check “Copy projects into workspace” — leave the projects in their original location.
  6. Click Finish.

Eclipse will import approximately 60-80 projects. You will see build errors initially — this is expected because the Target Platform has not been set yet.

Setting Up the PDE Target Platform

The Target Platform defines the set of plugins (OSGi bundles) that iDempiere runs against. This is the most critical setup step and the one most commonly misconfigured.

  1. In the Eclipse Package Explorer, find the project org.idempiere.p2.targetplatform.
  2. Open the file org.idempiere.p2.targetplatform.target.
  3. Eclipse will open the Target Definition editor. Wait for it to finish resolving (this can take several minutes on the first run as it downloads dependencies).
  4. Once resolved (you should see “x plugins available”), click “Set as Active Target Platform” in the upper right corner.
  5. Eclipse will rebuild all projects. This takes a few minutes. Watch the Progress view (bottom right) for completion.

After the target platform is set and the build completes, most or all errors should disappear. If errors persist, try:

# From Eclipse menu:
Project > Clean > Clean All Projects
# Then wait for the rebuild to complete

Project Structure Overview

The iDempiere codebase is organized as a collection of OSGi bundles (Eclipse plugins). Understanding the key projects is essential for navigating the code:

Core Projects

  • org.adempiere.base — The core business logic. Contains model classes (MOrder, MInvoice, MPayment, etc.), the persistence layer (PO class), document processing, and utility classes. This is the project you will work with most frequently.
  • org.compiere.model — Generated model interfaces and X_ classes. When you use the model generator, output goes here.
  • org.adempiere.base.process — Standard processes (reports, imports, document processing utilities).

Server Projects

  • org.adempiere.server — Application server functionality, including the scheduler, workflow processor, and alert processor.
  • org.idempiere.webservices — SOAP and REST web service endpoints.

UI Projects

  • org.adempiere.ui.zk — The ZK-based web user interface. Contains all window rendering, grid views, form implementations, and UI-specific logic.
  • org.adempiere.webui.theme — Theme resources (CSS, images) for the web UI.

Build and Configuration Projects

  • org.idempiere.p2.targetplatform — Target Platform definition (third-party dependencies).
  • org.adempiere.server.product — Product configuration for building the server.
  • org.adempiere.pde — PDE customizations and build utilities.

Key Package Naming Conventions

org.compiere.model      -- Core model classes (M_ classes, X_ classes)
org.compiere.process    -- Standard process implementations
org.compiere.util       -- Utility classes (Env, DB, CLogger, etc.)
org.compiere.acct       -- Accounting posting classes
org.adempiere.model     -- Extended model classes
org.adempiere.base      -- Base framework extensions
org.idempiere           -- iDempiere-specific additions

Running iDempiere from Eclipse

Running iDempiere from Eclipse gives you the full development experience — hot code replacement, breakpoints, variable inspection, and console output.

Server Setup

  1. Navigate to the org.adempiere.server.product project.
  2. Find the launch configuration file: idempiere-server.launch.
  3. Right-click the file and select Run As > idempiere-server (or Debug As for debugging).

Before the first launch, you need to configure the database connection. Create or edit the idempiereEnv.properties file:

# Key properties for development
ADEMPIERE_DB_TYPE=PostgreSQL
ADEMPIERE_DB_SERVER=localhost
ADEMPIERE_DB_PORT=5432
ADEMPIERE_DB_NAME=idempiere
ADEMPIERE_DB_USER=adempiere
ADEMPIERE_DB_PASSWORD=adempiere
ADEMPIERE_APPS_SERVER=localhost
ADEMPIERE_WEB_PORT=8080
ADEMPIERE_SSL_PORT=8443

Verifying the Launch

Watch the Eclipse Console view for startup messages. A successful startup shows:

===== iDempiere Server Started =====
Web server started at http://0.0.0.0:8080

Open a browser and navigate to http://localhost:8080/webui/ to see the login screen.

Debugging Basics

Eclipse’s debugger is your most powerful tool for understanding iDempiere’s behavior.

Setting Breakpoints

Double-click the left margin (gutter) of any source line to set a breakpoint. When execution reaches that line, the application pauses and Eclipse switches to the Debug perspective.

Common Debugging Locations

// Break on a specific model's save logic
org.compiere.model.MOrder.beforeSave()

// Break on document processing
org.compiere.model.MOrder.completeIt()

// Break on callout execution
org.compiere.model.CalloutOrder.bPartner()

// Break on the persistence layer
org.compiere.model.PO.saveEx()

Debug Operations

  • Step Over (F6): Execute the current line and move to the next line.
  • Step Into (F5): Enter the method called on the current line.
  • Step Return (F7): Execute until the current method returns.
  • Resume (F8): Continue execution until the next breakpoint.
  • Variables View: Inspect all local variables, method parameters, and object fields.
  • Expressions View: Evaluate arbitrary Java expressions in the current context.
  • Conditional Breakpoints: Right-click a breakpoint and add a condition (e.g., C_Order_ID == 1000123) so it only pauses when the condition is true.

Hot Code Replacement

When running in Debug mode, Eclipse can replace code in the running application without restarting. Make a change, save the file, and Eclipse automatically compiles and replaces the class. Limitations: you cannot add new methods, change method signatures, or add class fields via hot replacement. For structural changes, you must restart.

iDempiere Coding Conventions

When contributing code to iDempiere (or building plugins), follow these conventions:

Naming

  • Model classes: M prefix (e.g., MOrder, MInvoice).
  • Generated classes: X_ prefix (e.g., X_C_Order).
  • Interfaces: I_ prefix (e.g., I_C_Order).
  • Callout classes: Callout prefix (e.g., CalloutOrder).
  • Process classes: Name describes the action (e.g., InvoiceGenerate).

Code Style

  • Use tabs for indentation (not spaces).
  • Opening braces on the same line as the statement.
  • Use StringBuilder for string concatenation in loops.
  • Always use saveEx() instead of save() — the Ex variant throws exceptions on failure rather than silently returning false.
  • Use CLogger for logging, not System.out.println().
// Correct iDempiere style
private static final CLogger log = CLogger.getCLogger(MyClass.class);

public String processIt() {
    MOrder order = new MOrder(getCtx(), orderId, get_TrxName());
    if (order.getGrandTotal().compareTo(Env.ZERO) <= 0) {
        log.warning("Order " + order.getDocumentNo() + " has zero total");
        return "Order total must be positive";
    }
    order.setDocStatus(MOrder.DOCSTATUS_Completed);
    order.saveEx();
    return null;
}

Understanding the Build System

iDempiere uses Maven with the Tycho plugin for building. Tycho integrates Maven with Eclipse PDE, enabling Maven to build OSGi bundles and Eclipse plugins.

Building from the Command Line

# Navigate to the iDempiere root directory
cd /path/to/idempiere

# Full build
mvn verify -Didempiere.target=org.idempiere.p2.targetplatform

# Skip tests for a faster build
mvn verify -DskipTests

# Build a specific module
mvn verify -pl org.adempiere.base

Key Build Files

  • pom.xml (root) — Parent POM defining common properties and modules.
  • pom.xml (per project) — Module-level POM with project-specific build configuration.
  • META-INF/MANIFEST.MF — OSGi bundle manifest defining the plugin’s identity, dependencies, and exported packages.
  • build.properties — Eclipse PDE build configuration listing source folders and included resources.

Making Your First Code Change

Let us make a simple, safe change to verify your development environment works end-to-end.

Adding a Log Statement

  1. In the Package Explorer, navigate to org.adempiere.base > src > org.compiere.model > MOrder.java.
  2. Find the beforeSave(boolean newRecord) method.
  3. Add a log statement at the beginning of the method: 
    @Override
protected boolean beforeSave(boolean newRecord) {
    log.info("MOrder.beforeSave called for DocumentNo="
        + getDocumentNo() + " newRecord=" + newRecord);

    // ... rest of existing code
}
  4. Save the file (Ctrl+S). If running in Debug mode, hot code replacement applies the change immediately.
  5. Go to the iDempiere web UI, open a Sales Order, and save it.
  6. Check the Eclipse Console — you should see your log message.

Reverting Your Change

After verifying the change works, revert it so you do not accidentally commit debug logging:

# From the command line
cd /path/to/idempiere
git checkout -- org.adempiere.base/src/org/compiere/model/MOrder.java

Or in Eclipse: right-click the file and select Replace With > HEAD Revision.

Key Takeaways

  • iDempiere development requires Java 17, Eclipse IDE for RCP/RAP Developers, PostgreSQL, and Git.
  • The source is on GitHub — clone the repository and import all projects into Eclipse.
  • The PDE Target Platform setup is critical — without it, the project will not compile.
  • Key projects: org.adempiere.base (core logic), org.adempiere.ui.zk (UI), org.adempiere.server (server).
  • Run iDempiere from Eclipse using the provided launch configuration for full debugging support.
  • Eclipse’s debugger (breakpoints, variable inspection, hot replacement) is essential for productive development.
  • The build system uses Maven with Tycho for OSGi bundle building.
  • Follow iDempiere naming conventions: M_ for model classes, X_ for generated, I_ for interfaces.

What’s Next

In Lesson 17, you will dive into iDempiere’s Model Layer — the X_ and M_ class hierarchy, the PO base class, and how to write business logic using lifecycle methods like beforeSave() and afterSave(). This is where your development environment setup pays off.

You Missed