DEV Community: Alone Star

LightESB PlatformHttp v1.0.0: DS Data Transform Guide

Alone Star — Fri, 10 Apr 2026 09:16:15 +0000

Metadata

Applicable Version: PlatformHttp@v1.0.0
Related Service: PlatformHttp@v1.0.0@complex-json-transform-route.xml

PlatformHttp v1.0.0 provides a practical DS data transform route for complex order payloads.

The route uses conditionaltransform to decide whether to run the transform and returns the converted JSON directly to the caller.

Background and Goal

For integration scenarios, upstream payloads are often deeply nested and hard to consume directly.

This route targets a stable pattern:

keep a clear HTTP Listener as the request entry
flatten multi-level order JSON into business-friendly fields
prepare transformed data for downstream forwarding
keep response write-back stable with JSON encoding handling

Route and Configuration Breakdown

1) HTTP Listener request entry

From complex-json-transform-route.xml:

<from uri="undertow:http://0.0.0.0:{{server.port}}/api/transform/complex-order?httpMethodRestrict=POST" />

From common.config.properties:

server.port=18081
HTTP.Listener=true
system.components=undertowhttp,streamcache,jsontransform,conditionaltransform

Resulting request endpoint:

POST http://localhost:18081/api/transform/complex-order

2) Conditional transform switch

The route invokes:

<to uri="conditionaltransform:input?skipOnError=true"/>

The transform behavior is controlled by:

input-transform=true
input-transform.file=input-transform-with-import.ds

Meaning:

when input-transform=true, DS transform executes
input-transform-with-import.ds is used as the input transform script
when transform fails and skipOnError=true, the route continues without hard stop

3) DS script and shared function import

Main script:

lightesb-camel-app/PlatformHttp/v1.0.0/input-transform-with-import.ds

Shared function library:

lightesb-camel-app/TransformDS/common-functions.ds

The script imports common functions to keep rules modular:

local lib = import 'lightesb-camel-app/TransformDS/common-functions.ds';

Typical mappings include:

customer name via lib.formatFullName(...)
shipping address via lib.formatAddress(...)
line totals via lib.calculateLineTotal(...)
normalized financial values via lib.formatAmount(...)

4) Response write-back

The route finishes with:

<process ref="jsonResponseProcessor"/>

This helps keep JSON response output stable for UTF-8 and content formatting during response write-back.

Request and Response Examples

Request Example

Run from repository root:

curl -X POST "http://localhost:18081/api/transform/complex-order" \
  -H "Content-Type: application/json" \
  --data-binary "@lightesb-camel-app/PlatformHttp/v1.0.0/test.json"

Response Example (key fields)

A successful response contains transformed fields such as:

{
  "orderId": "ORD-2024-003",
  "customerName": "张明华",
  "items": [
    {
      "productId": "PROD-001",
      "lineTotal": 16198.2
    }
  ],
  "financial": {
    "currency": "CNY"
  }
}

Quick verification with jq:

curl -s -X POST "http://localhost:18081/api/transform/complex-order" \
  -H "Content-Type: application/json" \
  --data-binary "@lightesb-camel-app/PlatformHttp/v1.0.0/test.json" | jq '{orderId, customerName, itemCount: (.items|length), currency: .financial.currency}'

Common Issues and Troubleshooting

1) Port is not reachable

Check:

HTTP.Listener=true
server.port=18081
no process conflicts on port 18081

2) Request method rejected

The route uses httpMethodRestrict=POST; call must be POST.

3) No transform applied

Check:

input-transform=true
input-transform.file=input-transform-with-import.ds
DS file path and syntax are valid

4) Import file not found

input-transform-with-import.ds imports:

lightesb-camel-app/TransformDS/common-functions.ds

Ensure this file exists and path is correct relative to runtime resolution.

Summary

PlatformHttp v1.0.0 offers a clear DS transform baseline:

stable HTTP Listener request entry
configuration-driven transform switch with conditionaltransform
reusable DS function library via import
predictable response write-back through jsonResponseProcessor

This pattern is suitable for complex JSON flattening and can be extended with validation, auth checks, and downstream forwarding policies.

LightESB PlatformHttp v3.0.0: JSONPath Order Transform HTTP Route Guide

Alone Star — Thu, 09 Apr 2026 06:05:58 +0000

Metadata

Applicable Version: PlatformHttp@v3.0.0
Related Service: PlatformHttp@v3.0.0@platform-http-route.xml

PlatformHttp v3.0.0 provides a compact and practical HTTP transform pattern: receive order JSON, extract business fields with JSONPath, and return JSON responses with consistent encoding.

This article walks through how the route is designed and how to validate it quickly.

Background and Goal

In many integration services, the request entry must be strict and observable:

Keep a clear HTTP Listener entry for upstream systems
Extract key fields (orderId) as early as possible
Preserve service-level logs for troubleshooting
Return stable JSON without Chinese encoding issues

PlatformHttp v3.0.0 addresses these goals in one route package.

Route and Configuration Breakdown

1) Runtime listener switch and port

From common.config.properties:

server.port=18080
HTTP.Listener=true
system.components=undertowhttp

Meaning:

HTTP.Listener=true enables Undertow registration
server.port=18080 defines the external listening port
route endpoint resolves with this port at runtime

2) Service identity and URL versioning

From service.config.properties:

service.name=PlatformHttp
service.version=3.0.0

The main request entry uses:

<from uri="undertow:http://0.0.0.0:{{server.port}}/{{service.version}}/transform/order?httpMethodRestrict=POST" />

So the final request path is:

POST /3.0.0/transform/order

This keeps API versioning explicit in URL paths.

3) JSONPath extraction and response write-back

The route extracts orderId in multiple ways, then writes a JSON response:

<log message="orderId (JSONPath): ${jsonpath($.orderId)}"/>
<setProperty name="extractedOrderId"><jsonpath>$.orderId</jsonpath></setProperty>
<setHeader name="OrderId"><jsonpath>$.orderId</jsonpath></setHeader>
...
<transform><simple>{"status": "success", "message": "请求处理完成"}</simple></transform>
<process ref="jsonResponseProcessor"/>
<setHeader name="Content-Type"><constant>application/json</constant></setHeader>

Why this design works:

HTTP Listener: one explicit request entry point
Request entry observability: servicelog captures headers and body
Downstream forwarding ready: extracted fields can be reused for later routing decisions
Response write-back stability: jsonResponseProcessor improves UTF-8 output behavior

Request and Response Validation

API 1: Main transform route

curl -X POST "http://localhost:18080/3.0.0/transform/order" \
  -H "Content-Type: application/json" \
  -d "{\"orderId\":\"ORD-20260409-001\",\"amount\":299.50}"

Expected response:

{"status":"success","message":"请求处理完成"}

API 2: JSONPath-inline response sample

curl -X POST "http://localhost:18080/3.0.0/transform/order1" \
  -H "Content-Type: application/json" \
  -d "{\"orderId\":\"ORD-20260409-002\"}"

Expected response:

{"status":"ORD-20260409-002","message":"请求处理完成"}

Common Issues and Troubleshooting

1) Port not reachable

Check:

HTTP.Listener=true
server.port=18080
no other process occupies 18080

2) Method rejected (405)

the endpoint restricts method with httpMethodRestrict=POST
call must use POST

3) Incorrect path or version

route path includes {{service.version}}
ensure request URL matches /3.0.0/transform/order or /3.0.0/transform/order1

4) Encoding or garbled response text

keep jsonResponseProcessor in the response path
keep Content-Type: application/json response header

Summary

PlatformHttp v3.0.0 demonstrates a practical baseline for API integration routes:

strict HTTP Listener entry
early JSONPath field extraction
service-level request tracing
stable UTF-8 response write-back

This pattern is suitable for order transform gateways and can be extended with validation, auth checks, and downstream forwarding policies.

LightESB HTTP Listener and Request Routing: Undertow + HttpRequestSrv Deep Dive

Alone Star — Wed, 08 Apr 2026 09:36:20 +0000

Metadata

Applicable Version: HttpRequestSrv@v1.0.0
Publish Date: 2026-04-08
Article Type: Technical Deep Dive
Related Service: HttpRequestSrv@v1.0.0@http-request-route.xml

When a service needs to expose HTTP APIs in LightESB, the route XML itself is only half of the picture.

The other half is the runtime listener switch: HTTP.Listener.

This article explains how HTTP.Listener, server.port, and Undertow endpoints work together by using HttpRequestSrv as a concrete example.

Why `HTTP.Listener` Matters

In LightESB, Undertow component registration is controlled by configuration:

HTTP.Listener=true: register Undertow and expose HTTP routes
HTTP.Listener=false: skip Undertow registration
server.port: runtime listening port for route endpoints

From HttpRequestSrv/v1.0.0/common.config.properties:

server.port=18083
HTTP.Listener=true
system.components=undertowhttp

This design lets teams decide whether a service is externally reachable without modifying route XML files.

Route Entry Design in `HttpRequestSrv`

HttpRequestSrv defines two Undertow entries:

<from uri="undertow:http://0.0.0.0:{{server.port}}/api/httprequest/test?httpMethodRestrict=POST" />
...
<from uri="undertow:http://0.0.0.0:{{server.port}}/api/test?httpMethodRestrict=POST"/>

Key points:

0.0.0.0 listens on all NICs
{{server.port}} injects environment-level port
httpMethodRestrict=POST ensures method-level guard at the endpoint

This is a clean pattern for API entry routes: reject invalid methods early and keep business processors focused.

Request Flow: Listener -> Route -> Downstream Call

The first route acts as both inbound listener and outbound requester:

Receive external request on /api/httprequest/test
Log request start with servicelog
Forward to local endpoint http://0.0.0.0:18083/api/test
Log completion and return response

Core segment:

<to uri="servicelog:info?message=开始处理HTTP请求&amp;showBody=true&amp;maxBodyLength=500"/>
<to uri="http://0.0.0.0:18083/api/test?httpMethod=POST&amp;contentType=application/json&amp;bridgeEndpoint=true&amp;connectTimeout=5000&amp;socketTimeout=30000"/>
<to uri="servicelog:info?message=HTTP请求完成&amp;showBody=true&amp;maxBodyLength=5000"/>

The second route handles /api/test and returns a fixed JSON payload for quick verification.

Minimal Validation with cURL

curl -X POST "http://localhost:18083/api/httprequest/test" \
  -H "Content-Type: application/json" \
  -d "{\"orderId\":\"A1001\",\"amount\":199.9}"

Expected behavior:

request enters http-request-route
route forwards to /api/test
response body returns {"message": "HTTP Response Test"}
request logs are visible through servicelog

Common Failures and How to Diagnose

1) API not reachable

Check:

HTTP.Listener is true
server.port is valid and not occupied
startup logs include Undertow registration success

2) Port conflict

another process already binds the same port
release lifecycle did not clean previous context on hot reload

3) 405 or route miss

method is not in httpMethodRestrict
request path does not match route URI exactly

Practical Recommendations

Keep listener behavior configurable through properties, not hard-coded
Start with strict httpMethodRestrict to reduce invalid traffic
Add jsonResponseProcessor when multilingual JSON output is required
Keep one service-level log at route entry for observability and incident triage

LightESB Timer : From Scheduled Triggers to Service-Level Observability

Alone Star — Wed, 08 Apr 2026 02:59:41 +0000

TL;DR

This technical deep dive explains how LightESB uses Apache Camel Timer routes for periodic jobs, structured status checks, and service-level observability with servicelog.

It also shows how jsonResponseProcessor improves UTF-8 response behavior in Chinese output scenarios.

Many integration tasks are time-driven rather than request-driven: health checks, cache refresh, batch processing, and heartbeat jobs.

In LightESB, Apache Camel timer endpoints provide a low-friction way to run those tasks while keeping route logic explicit and versioned.

This post is based on real sample routes in the repository (timer/v1.0.0 and timer/v1.0.1) and focuses on practical production patterns.

Why Timer routes in LightESB

Using Timer routes gives three immediate benefits:

Decentralized scheduling in route definitions (period configured where logic lives)
Easy version evolution (v1.0.0 -> v1.0.1) per service package
Fast observability through log + servicelog with structured payloads

v1.0.0 baseline: minimal but reliable

The baseline sample introduces two periodic routes:

A health-style message every 10 seconds
A structured status payload every 15 seconds

<route id="independent-timer-test-v1.0.0">
    <from uri="timer:independentTest?period=10000"/>
    <setBody>
        <constant>Timer route is alive</constant>
    </setBody>
    <to uri="log:independent-context?level=INFO"/>
</route>

<route id="independent-status-check-v1.0.0">
    <from uri="timer:statusCheck?period=15000"/>
    <setBody>
        <simple>{"file":"timer-test-routes.xml","status":"ACTIVE","timestamp":"${date:now:yyyy-MM-dd HH:mm:ss}"}</simple>
    </setBody>
    <log message="Independent context status: ${body}"/>
</route>

v1.0.1 evolution: service-level diagnostics

1) `servicelog` for independent service logs

servicelog is a LightESB custom logging component designed for independent service-level logging.

Better per-service log isolation
Better control with service-oriented log levels
Safer body visibility through output controls (showBody, maxBodyLength)

2) Structured status with version field

The status payload explicitly includes version, making diagnostics and dashboards version-aware.

3) `jsonResponseProcessor` for encoding quality

jsonResponseProcessor is a LightESB custom component used to improve UTF-8 response handling, especially in Chinese text scenarios.

Period and route design recommendations

period=5000: local validation and fast integration debugging
period=30000: common heartbeat and lightweight periodic tasks
period=1500000: low-frequency summary checks

Use business latency requirements to determine period values, not default habits.

For payloads, keep at least:

status
timestamp
version
file or source identifier

When Timer is a good fit

Good fit:

Fixed-interval tasks (checks, syncs, cleanup, summaries)
Jobs that do not require strict centralized scheduling
Services that benefit from embedded, versioned scheduling logic

Not a good fit:

Strict timing consistency and high-precision scheduling
Complex DAG orchestration with advanced dependency constraints
Workloads that must be controlled by an external scheduling platform

Supplemental reference

For endpoint parameters such as period, delay, repeatCount, and fixedRate, use the official documentation:

Apache Camel Timer Component

DEV Community: Alone Star

LightESB PlatformHttp v1.0.0: DS Data Transform Guide

Metadata

Background and Goal

Route and Configuration Breakdown

1) HTTP Listener request entry

2) Conditional transform switch

3) DS script and shared function import

4) Response write-back

Request and Response Examples

Request Example

Response Example (key fields)

Common Issues and Troubleshooting

1) Port is not reachable

2) Request method rejected

3) No transform applied

4) Import file not found

Summary

Links

LightESB PlatformHttp v3.0.0: JSONPath Order Transform HTTP Route Guide

Metadata

Background and Goal

Route and Configuration Breakdown

1) Runtime listener switch and port

2) Service identity and URL versioning

3) JSONPath extraction and response write-back

Request and Response Validation

API 1: Main transform route

API 2: JSONPath-inline response sample

Common Issues and Troubleshooting

1) Port not reachable

2) Method rejected (405)

3) Incorrect path or version

4) Encoding or garbled response text

Summary

Related Reading

LightESB HTTP Listener and Request Routing: Undertow + HttpRequestSrv Deep Dive

Metadata

Why HTTP.Listener Matters

Route Entry Design in HttpRequestSrv

Request Flow: Listener -> Route -> Downstream Call

Minimal Validation with cURL

Common Failures and How to Diagnose

1) API not reachable

2) Port conflict

3) 405 or route miss

Practical Recommendations

Related Reading

LightESB Timer : From Scheduled Triggers to Service-Level Observability

Why Timer routes in LightESB

v1.0.0 baseline: minimal but reliable

v1.0.1 evolution: service-level diagnostics

1) servicelog for independent service logs

2) Structured status with version field

3) jsonResponseProcessor for encoding quality

Period and route design recommendations

When Timer is a good fit

Supplemental reference

Links

Why `HTTP.Listener` Matters

Route Entry Design in `HttpRequestSrv`

1) `servicelog` for independent service logs

3) `jsonResponseProcessor` for encoding quality