HCL Commerce Developer Solr-based Search environment

The HCL Commerce Developer Solr-based Search environment provides a modern development environment for customizing and debugging search functionality in Commerce+. It replaces the legacy IBM Rational Application Developer (RAD) based development environment for Commerce+ Search with a lightweight stack based on Maven, Open Liberty, and Eclipse. This toolkit only supports Commerce+ Solr v9.10.1 Search environment. The existing Commerce+ toolkit still provides a development environment based on Solr v7.

Key benefits

Uses a standard Maven build (no proprietary scripts).
Runs on Open Liberty 26.0.0.6 instead of WebSphere Liberty.
Enables hot deployment (changes are reflected without server restarts).
Ability to build and test customizaton with Java 21.

For setting up the HCL Commerce Developer Solr-based Search environment, refer Setting up the Developer Solr-based Search environment.

Architecture

The toolkit is organized as a Maven multi-module project that separates configuration, custom logic, and deployment. This structure allows you to develop and test changes independently while maintaining a consistent deployment model.

High-level flow


Developer IDE
     ↓
search-bundle (Maven aggregator)
     ↓
search-ear (EAR package)
     ↓
Open Liberty (searchServer)
     ↓
Solr + Search REST APIs

This flow represents how your changes move from development to runtime.

Toolkit structure


<TOOLKIT_HOME>/
├── liberty/                 (Pre-configured Open Liberty server profile)
├── workspace/
│   └── search-bundle/       (Aggregator project)
│       ├── search-config-ext/
│       ├── search-logic-ext/
│       ├── search-rest-ext/
│       ├── search-ear/
├── setup-liberty.bat/sh

Each module has a specific responsibility:

search-config-ext → Solr schemas and configuration
search-logic-ext → Custom Java logic
search-rest-ext → REST APIs
search-ear → Final deployment package

Maven Multi-Module Structure

The search-ear module packages all components into a deployable EAR file that runs on Open Liberty.


search-bundle (parent POM)
     ↓
 ├── search-config-ext (JAR)
 ├── search-logic-ext (JAR)
 ├── search-rest-ext (WAR)
     ↓
search-ear (EAR)
     ↓
EarContent/
 ├── META-INF/application.xml
 ├── lib/ (shared JARs)
 ├── search-solr.war (/solr)
 ├── search-rest.war (/search/resources)
 ├── other OOTB WARs

How it works at runtime:

The EAR file is deployed to the Liberty searchServer.
Shared libraries are loaded from the lib/directory
WAR files expose application endpoints:
- /solr → Solr search engine
- /search/resources → Search REST APIs
Custom logic and configuration are picked up from extension modules.

Dependency Strategy

OOTB libraries are referenced using the Maven system pointing to EarContent/lib/ and resolved from search-ear/EarContent/lib/

This ensures compatibility with the runtime environment provided by Commerce+.

Running and Debugging

After completing the setup, you can start and debug the Search server directly from Eclipse.

Table 1.
Action	Method
Start	Right-click server → Start
Debug	Right-click server → Debug (enables breakpoints)
Hot Swap	Simply save a Java file; Eclipse republishes automatically

Where:

Start launches the Liberty server and deploys the search application.
Debug allows you to pause execution and inspect code using breakpoints.
Hot swap automatically applies code changes without restarting the server.

This enables a fast development cycle when working with search customizations.

Creation of WCBD Package

To deploy your search customizations to higher environments (such as staging or production), you must generate a WCBD package.

Step 1: Navigate to the project directory: cd <TOOLKIT_HOME>/workspace/search-bundle
Step 2: Build the package: Run the Maven packaging command: mvn clean package
Step 3: Locate the generated package: The WCBD package ZIP file is created in: search-ear/target/search-ear-*.zip; For more information on customization package structure for search server, refer Repository structure for building Search server (search) packages.

Refresh the toolkit

Including the Search Bundle inside of the container allows the Solr 9 search-app binaries and configurations to be in sync with the Search bundle at all times. This bundle can be refreshed manually by running /SETUP/bin/createSearchBundle.sh script file. This bundle will also be automatically refreshed after a patch has been applied using /SETUP/bin/patch.sh script.

After the search bundle has been updated, exit out of your Solr Toolkit if you have the Eclipse workbench still running. Extract the content of this newly updated search bundle to your current <TOOLKIT_HOME>, for example, C:\HCL\SearchToolkit. Restart your Solr Toolkit and refresh your workspace.

Search Bundle types

The createSearchBundle.sh script creates two types of bundles from the expanded search-ear.ear inside the container.

Table 2.
Bundle type	Included contents	When to use
Full Bundle (`--full`)	The complete toolkit archive containing all workspace and setup binaries.	Use when you want to completely reset or re-initialize your local toolkit (for example, if an initial setup failed, or you want to wipe out local experimental changes and start fresh).
Delta Bundle (`--delta`)	Lightweight archive containing only `workspace/search-bundle/search-ear/EarContent` (`lib/` and `*.war` files).	Use when you want to sync patches or dependency updates from the container into an existing development environment without overwriting your local extension code or project configurations.

Script usage

Run the script inside the container using one of the following command options:


# Generate the full toolkit bundle (default behavior)
/SETUP/bin/createSearchBundle.sh
                        
# Display command usage and option details
/SETUP/bin/createSearchBundle.sh --help
                        
# Explicitly generate a full toolkit bundle
/SETUP/bin/createSearchBundle.sh --full
                        
# Generate a delta bundle for local toolkit sync
/SETUP/bin/createSearchBundle.sh --delta

Applying updated bundles to your local toolkit

Before applying any update, exit your Solr Toolkit if the Eclipse workbench is currently running.

Option A: Refresh using a Full Bundle

Warning: Extracting a full bundle completely overwrites your existing <TOOLKIT_HOME> directory. Any uncommitted local changes, configurations, or custom work inside <TOOLKIT_HOME> will be lost.

Copy the generated full bundle ZIP file from the container to your local environment.
Extract the entire ZIP file directly into your <TOOLKIT_HOME> directory (for example, C:\HCL\SearchToolkit), replacing all existing files.
Start your Solr Toolkit and refresh your Eclipse workspace.

Option B: Apply a Delta Bundle

The delta bundle (for example, /SETUP/bundles/search-delta-bundle-YYYYMMDD-HHMMSS.zip) matches the workspace structure and contains only workspace/search-bundle/search-ear/EarContent.

Copy the generated delta ZIP file from /SETUP/bundles/ in the container to your local system.
Extract the delta ZIP directly into your <TOOLKIT_HOME> directory, or extract and replace the lib/ directory and *.war files directly under <TOOLKIT_HOME>\workspace\search-bundle\search-ear\EarContent\.
Start your Solr Toolkit and refresh your Eclipse workspace to pick up the updated dependencies.