Builder Design and DataContent Processing Chains

This page describes the builder-driven pipeline architecture in ZeroEcho. It focuses on how modular components, known as DataContent, are linked together to form transformation chains, and how internal metadata (such as cryptographic parameters) is exchanged between these components.

The builder model supports constructing layered content processors, where each component either transforms the data, emits metadata, or reacts to upstream information. This is the foundation for more advanced ZeroEcho capabilities such as encryption layering, parameter binding, and stream-based metadata propagation.

Chain Construction

A chain is constructed using a fluent builder API. Each DataContent instance can receive input from the previous component using setInput(…). This allows data to be streamed sequentially through the chain, with optional parameter exchange.

final class DefaultDataContentChainBuilder implements DataContentChainBuilder {
    private DataContent tail;

    private DefaultDataContentChainBuilder() {
        this.tail = null;
    }

    @Override
    public DataContentChainBuilder add(final DataContentBuilder<? extends DataContent> builder) {
        final DataContent previous = tail;
        tail = builder.build();

        if (previous != null) {
            tail.setInput(previous);
        }

        return this;
    }

    @Override
    public DataContent build() {
        return tail;
    }
}

Data Flow Semantics

The stream of content flows forward (from input to output), but parameter propagation may occur backward through the chain. This allows for behavior such as:

• Key derivation from metadata
• Metadata-based encryption and decryption
• Header serialization and deserialization

Only earlier chunks can provide input to later ones. The reverse (backward data flow) is not supported.

Practical Example: Encrypted Processing Pipeline

This example demonstrates a full processing chain from plaintext input, through encryption, metadata extraction, decryption, and output recovery.

DataContent output = DataContentChainBuilder.builder()
        // input string
        .add(PlainStringBuilder.builder().value(originalText))

        // AES encryptor
        .add(AesBuilder.builder().encrypt())

        // serialize and extract AES parameters
        .add(DerivedAesParametersBuilder.builder().password(userPassword))

        // reclassify encrypted data as plain
        .add(ReclassifiedPlainBuilder.builder())

        // read parameters for decryption
        .add(DerivedAesParametersBuilder.builder().password(userPassword))

        // AES decryptor using derived values
        .add(AesBuilder.builder().decrypt())

        // output = original plaintext
        .build();

This chain encodes the encryption metadata (salt, iterations, etc.) into the stream, then recovers it during decryption. Both DerivedAesParametersBuilder instances cooperate to serialize and then deserialize the same information.

Metadata Sharing Between Chunks

Chunks that participate in parameter handling use the SecretContent interface, which provides two key methods:

@Override
public void collectParameters(final Map<String, Object> collector) {
    collector.put(AesCommon.PARAM_KEY, params.key().getKey());
    collector.put(AesCommon.PARAM_IV, params.iv());
    collector.put(AesCommon.PARAM_MODE, params.mode().toString());
    collector.put(PARAM_SALT, params.salt());
    collector.put(PARAM_ITERATIONS, params.iterations());
}

@Override
public void applyParameters(final Map<String, Object> params) {
    // Reconstruct encryption parameters
    …
}

The upstream chunk calls collectParameters(…), and the downstream chunk reads from the same parameter map via applyParameters(…). This mechanism enables tightly coupled encryption/decryption workflows.

Design Guidelines

• Chain order matters: later chunks can access data or metadata from earlier ones, but not the reverse.
• All metadata propagation is done explicitly through parameter maps.
• Intermediate chunks that transform content should preserve parameter integrity if participating in the flow.
• Avoid inserting non-cooperative or opaque chunks between chunks that need to exchange metadata.

See Also

• Parameter Handling
• ZeroEcho Project Overview