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 HCL Commerce. It replaces the legacy IBM Rational Application Developer (RAD) based development environment for HCL Commerce Search with a lightweight stack based on Maven, Open Liberty, and Eclipse. This toolkit only supports HCL Commerce Solr v9.10.1 Search environment. The existing HCL 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 instead of WebSphere Liberty.
Enables hot deployment (changes are reflected without server restarts).
Ability to build and test customizaton with Java 17.

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 HCL 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.