InsertField.java

Overview

The `InsertField` class is a JSON message transformation processor designed for use within Apache Camel routes, specifically in Kafka integration pipelines. Its primary purpose is to insert a new field with a specified name and value into a JSON object payload or append a value to a JSON array payload carried in the message body of a Camel `Exchange`.

This processor supports dynamic resolution of the inserted value using Camel's Simple language expressions, enabling flexible and context-aware modifications of the JSON message content at runtime.

Class: InsertField

public class InsertField implements Processor

Purpose

`InsertField` implements the Apache Camel `Processor` interface to manipulate the JSON payload of a message by inserting a new field (for JSON objects) or appending a value (for JSON arrays). This class is typically used in Camel routes to enrich or extend JSON messages before further processing or sending to Kafka topics.

Fields

Constructors

InsertField()

• Description: Default no-argument constructor.

• Usage: Create an instance to set fields later via setters.

InsertField(String field, String value)

• Parameters:

  • field – The name of the JSON field to insert.

  • value – The value to assign to the new field (may be a Simple expression).

• Usage Example:

InsertField insertFieldProcessor = new InsertField("status", "processed");

Methods

void process(Exchange ex) throws InvalidPayloadException

• Description: Main processing method invoked by Camel to process the current message exchange.

• Parameters:

  • ex – The Camel Exchange object containing the message to process.

• Behavior:

  • Retrieves the message body and attempts to convert it to a Jackson JsonNode.

  • Throws InvalidPayloadException if the body is missing or not convertible to JSON.

  • Evaluates the value field:

    • If value contains Camel Simple language syntax (detected via LanguageSupport.hasSimpleFunction), it evaluates the expression against the current exchange context.

    • Otherwise, uses the literal value string.

  • Based on the type of JsonNode:

    • If the body is a JSON array (ArrayNode), appends the resolved value as a new element.

    • If the body is a JSON object (ObjectNode), inserts the new field with the resolved value.

    • For other types (e.g., primitives), treats as an object and inserts the field.

  • Updates the message body with the modified JSON.

• Throws:

  • InvalidPayloadException if the message body is not a JSON node.

• Usage Example:

InsertField processor = new InsertField("newField", "${header.someHeader}");
processor.process(exchange);

void setField(String field)

• Description: Setter for the field property.

• Parameters:

  • field – The name of the JSON field to insert.

• Usage Example:

insertFieldProcessor.setField("newField");

void setValue(String value)

• Description: Setter for the value property.

• Parameters:

  • value – The value to insert, which may include Simple language expressions.

• Usage Example:

insertFieldProcessor.setValue("${header.userId}");

Important Implementation Details

• Dynamic Value Resolution:
  Uses Camel's Simple language to allow dynamic expressions for inserted values, enabling context-aware insertion based on message headers, properties, or other exchange data.

• Jackson JSON Tree Model:
  The processor uses Jackson's JsonNode API to manipulate JSON content. It safely handles different JSON node types (ARRAY, OBJECT, and others), ensuring appropriate mutation logic:

  • Arrays: appends the value as a new element.

  • Objects: adds a new field.

  • Other types: coerces into an object node before insertion.

• Type Handling:
  The inserted value is always added as a string node (put or add with a String argument). This means non-string values should be converted to string representations in the Simple expression or before insertion.

• Error Handling:
  If the body is missing or not JSON-parsable, an InvalidPayloadException is thrown immediately to prevent silent failures.

Interaction with Other Components

• Camel Exchange:
  Operates directly on the Camel Exchange object, modifying the message body in-place.

• Kafka Integration:
  Typically used in routes that process Kafka JSON messages, allowing enrichment of message content before producing or forwarding.

• Other Message Transformation Utilities:
  Can be combined with other processors (e.g., DropField, MaskField) to perform complex JSON transformations as part of a processing pipeline.

• Dynamic Routing:
  By inserting fields dynamically, it can influence routing decisions or downstream processing based on newly added data.

Usage Example in a Camel Route

from("kafka:input-topic")
    .process(new InsertField("processedBy", "${header.CamelId}"))
    .to("kafka:output-topic");

This route reads messages from `input-topic`, inserts a field `"processedBy"` with the current Camel context ID, and sends the enriched message to `output-topic`.

Mermaid Class Diagram for InsertField.java

classDiagram
    class InsertField {
        -String field
        -String value
        +InsertField()
        +InsertField(field: String, value: String)
        +void process(ex: Exchange) throws InvalidPayloadException
        +void setField(field: String)
        +void setValue(value: String)
    }
    InsertField ..|> Processor

Summary

The `InsertField` class is a lightweight yet powerful Camel `Processor` that enriches JSON message payloads by inserting new fields or appending values. Its support for Camel Simple language expressions enables dynamic and context-sensitive enhancements to Kafka messages, making it an essential building block in the **Message Transformation Utilities** suite for JSON content manipulation.

*End of InsertField.java Documentation*