### Create and Start Iso8583Server

Source: https://context7.com/kpavlov/jreactive-8583/llms.txt

Demonstrates the setup and initialization of an Iso8583Server. Requires configuration for message factory, server settings, and listener registration.

```java
import com.github.kpavlov.jreactive8583.server.*;
import com.github.kpavlov.jreactive8583.iso.*;
import com.solab.iso8583.IsoMessage;
import com.solab.iso8583.IsoType;
import com.solab.iso8583.parse.ConfigParser;
import java.nio.charset.StandardCharsets;

// 1. Create message factory
var rawFactory = ConfigParser.createDefault();
rawFactory.setCharacterEncoding(StandardCharsets.US_ASCII.name());
rawFactory.setUseBinaryMessages(false);
rawFactory.setAssignDate(true);
MessageFactory<IsoMessage> serverFactory =
    new J8583MessageFactory<>(rawFactory, ISO8583Version.V1987, MessageOrigin.ACQUIRER);

// 2. Build configuration
ServerConfiguration config = ServerConfiguration.newBuilder()
    .addLoggingHandler(true)
    .logSensitiveData(false)
    .addEchoMessageListener(true) // auto-answer 0x0800 echo/heartbeat messages
    .replyOnError(true)
    .workerThreadsCount(4)
    .build();

// 3. Create the server
Iso8583Server<IsoMessage> server = new Iso8583Server<>(9876, config, serverFactory);

// 4. Register a listener for financial requests (0x0200)
server.addMessageListener(new com.github.kpavlov.jreactive8583.IsoMessageListener<IsoMessage>() {
    @Override
    public boolean applies(IsoMessage msg) {
        return msg.getType() == 0x0200;
    }
    @Override
    public boolean onMessage(io.netty.channel.ChannelHandlerContext ctx, IsoMessage request) {
        // Build and send response
        IsoMessage response = server.getIsoMessageFactory().createResponse(request);
        response.setField(39, IsoType.ALPHA.value("00", 2));   // approval code
        response.setField(60, IsoType.LLLVAR.value("OK", 3));
        ctx.writeAndFlush(response);
        return false; // stop listener chain
    }
});

// 5. Initialize and start
server.init();
server.start();

if (server.isStarted()) {
    System.out.println("Server listening on port 9876");
}

// 6. Stop gracefully
server.stop();
server.shutdown();
```

--------------------------------

### Initialize and Start ISO8583 Server

Source: https://github.com/kpavlov/jreactive-8583/wiki/FAQ

Initialize the server's resources and then start it to begin accepting client connections.

```java
server.init();
server.start();
```

--------------------------------

### Iso8583Client Usage Example

Source: https://context7.com/kpavlov/jreactive-8583/llms.txt

Demonstrates initializing, connecting, sending messages (sync, async, with timeout), and shutting down an `Iso8583Client`. Requires configuration, a message factory, and a listener for responses.

```java
import com.github.kpavlov.jreactive8583.client.*;
import com.github.kpavlov.jreactive8583.iso.*;
import com.solab.iso8583.IsoMessage;
import com.solab.iso8583.IsoType;
import java.net.InetSocketAddress;
import java.util.concurrent.TimeUnit;

// 1. Build configuration
ClientConfiguration config = ClientConfiguration.newBuilder()
    .addLoggingHandler(true)
    .logSensitiveData(false)
    .reconnectInterval(200)
    .build();

// 2. Create message factory
MessageFactory<IsoMessage> factory = 
    new J8583MessageFactory<>(ISO8583Version.V1987, MessageOrigin.OTHER);

// 3. Create the client
Iso8583Client<IsoMessage> client = 
    new Iso8583Client<>(new InetSocketAddress("10.0.0.1", 9876), config, factory);

// 4. Register message listener for responses
client.addMessageListener(new com.github.kpavlov.jreactive8583.IsoMessageListener<IsoMessage>() {
    @Override
    public boolean applies(IsoMessage msg) {
        return msg.getType() == 0x0210; // financial response
    }
    @Override
    public boolean onMessage(io.netty.channel.ChannelHandlerContext ctx, IsoMessage msg) {
        String responseCode = msg.getObjectValue(39).toString(); // field 39: response code
        System.out.println("Response code: " + responseCode);   // e.g. "00" = approved
        return false; // stop processing chain
    }
});

// 5. Initialize and connect
client.init();
client.connect("10.0.0.1", 9876); // synchronous; auto-reconnects on drop

if (client.isConnected()) {
    // 6a. Build and send a financial request asynchronously
    IsoMessage finRequest = factory.newMessage(0x0200);
    finRequest.setField(60, IsoType.LLLVAR.value("foo", 3));
    client.sendAsync(finRequest); // returns ChannelFuture

    // 6b. Send synchronously
    client.send(finRequest);

    // 6c. Send with timeout
    client.send(finRequest, 5, TimeUnit.SECONDS);
}

// 7. Disconnect cleanly
client.disconnect();
client.shutdown();
```

--------------------------------

### ISO-8583 Server Logging Example

Source: https://github.com/kpavlov/jreactive-8583/blob/main/README.md

Shows an example of the output generated by the default IsoMessageLoggingHandler, illustrating how ISO-8583 messages are logged. Sensitive information like PAN can be masked.

```text
312 [nioEventLoopGroup-5-1] DEBUG IsoMessageLoggingHandler - [id: 0xa72cc005, /127.0.0.1:50853 => /127.0.0.1:9876] MTI: 0x0200
  2: [Primary account number (PAN):NUMERIC(19)] = '000400*********0002'
  3: [Processing code:NUMERIC(6)] = '650000'
  7: [Transmission date & time:DATE10(10)] = '0720233443'
  11: [System trace audit number:NUMERIC(6)] = '483248'
  32: [Acquiring institution identification code:LLVAR(3)] = '456'
  35: [Track 2 data:LLVAR(17)] = '***'
  43: [Card acceptor name/location (1-23 address 24-36 city 37-38 state 39-40 country):ALPHA(40)] = 'SOLABTEST TEST-3 DF MX                  '
  49: [Currency code, transaction:ALPHA(3)] = '484'
  60: [Reserved national:LLLVAR(3)] = 'foo'
  61: [Reserved private:LLLVAR(5)] = '1234P'
  100: [Receiving institution identification code:LLVAR(3)] = '999'
  102: [Account identification 1:LLVAR(4)] = 'ABCD'
```

--------------------------------

### Create and Use ISO-8583 Server

Source: https://github.com/kpavlov/jreactive-8583/blob/main/README.md

Demonstrates the typical workflow for creating, configuring, and starting an ISO-8583 server. Ensure the correct MessageOrigin is specified for originated messages.

```java
var messageFactory = new J8583MessageFactory<>(ConfigParser.createDefault(), ISO8583Version.V1987, MessageOrigin.ACQUIRER);
Iso8583Server<IsoMessage> server = new Iso8583Server<>(port, messageFactory);

server.addMessageListener(new IsoMessageListener<IsoMessage>() {
    ...
});
server.getConfiguration().replyOnError(true);
server.init();

server.start();
if (server.isStarted()) {
    ...
}

...
server.shutdown();
```

--------------------------------

### Initialize and Connect ISO8583 Client

Source: https://github.com/kpavlov/jreactive-8583/blob/main/README.md

Basic workflow for setting up an ISO8583 client, including message factory creation, listener registration, configuration, initialization, and connection.

```java
var messageFactory = new J8583MessageFactory<>(ISO8583Version.V1987, MessageOrigin.OTHER);// [1]
Iso8583Client<IsoMessage> client = new Iso8583Client<>(messageFactory);// [2]

client.addMessageListener(new IsoMessageListener<IsoMessage>() { // [3]
    ...
});
client.getConfiguration().replyOnError(true);// [4]
client.init();// [5]

client.connect(host, port);// [6]
if (client.isConnected()) { // [7]

    IsoMessage message = messageFactory.newMessage(...);
    ...
    client.sendAsync(message);// [8]
    // or
    client.send(message);// [9]
    // or
    client.send(message, 1, TimeUnit.SECONDS);// [10]
}

...
client.shutdown();// [11]
```

--------------------------------

### Instantiate Iso8583Server

Source: https://github.com/kpavlov/jreactive-8583/wiki/FAQ

Create an instance of Iso8583Server, providing the port and the configured MessageFactory.

```java
Iso8583Server server = new Iso8583Server<>(port, messageFactory);
```

--------------------------------

### ServerConfiguration Builder

Source: https://context7.com/kpavlov/jreactive-8583/llms.txt

Configures the Netty server bootstrap, sharing a similar builder base with `ClientConfiguration`.

```APIDOC
## ServerConfiguration — Building Server Configuration

`ServerConfiguration` shares the same builder base as `ClientConfiguration` (minus the reconnect interval) and configures the Netty server bootstrap.

### Methods

- `newBuilder()`: Creates a new `ServerConfiguration` builder.
- `getDefault()`: Returns the default `ServerConfiguration`.

### Builder Methods

- `addLoggingHandler(boolean enable)`: Enable or disable IsoMessageLoggingHandler in pipeline.
- `logSensitiveData(boolean log)`: Enable or disable logging of sensitive data (PCI DSS).
- `addEchoMessageListener(boolean enable)`: Enable or disable auto-response to 0x0800 echo requests.
- `replyOnError(boolean enable)`: Enable or disable sending admin message on parse error.
- `idleTimeout(long timeout)`: Set the idle timeout in seconds to send an echo message.
- `maxFrameLength(int length)`: Set the maximum TCP frame length in bytes.
- `workerThreadsCount(int count)`: Set the Netty worker thread pool size.
- `build()`: Builds the `ServerConfiguration` object.
```

--------------------------------

### Build ServerConfiguration

Source: https://context7.com/kpavlov/jreactive-8583/llms.txt

Configure Netty server bootstrap aspects using a fluent builder, similar to `ClientConfiguration` but without reconnect interval. Use `ServerConfiguration.getDefault()` for default settings.

```java
import com.github.kpavlov.jreactive8583.server.ServerConfiguration;

ServerConfiguration config = ServerConfiguration.newBuilder()
    .addLoggingHandler(true)
    .logSensitiveData(false)
    .addEchoMessageListener(true)
    .replyOnError(true)
    .idleTimeout(60)
    .maxFrameLength(8192)
    .workerThreadsCount(4)
    .build();

// Default configuration
ServerConfiguration defaults = ServerConfiguration.getDefault();
```

--------------------------------

### Build ClientConfiguration

Source: https://context7.com/kpavlov/jreactive-8583/llms.txt

Configure client connector aspects like timeouts, logging, and worker threads using a fluent builder. Use `ClientConfiguration.getDefault()` for default settings.

```java
import com.github.kpavlov.jreactive8583.client.ClientConfiguration;

ClientConfiguration config = ClientConfiguration.newBuilder()
    .addLoggingHandler(true)           // enable IsoMessageLoggingHandler in pipeline
    .logSensitiveData(false)           // mask PAN and track data in logs (PCI DSS)
    .describeFieldsInLog(true)         // print ISO field descriptions alongside values
    .sensitiveDataFields(2, 35, 45)    // additionally mask fields 2 (PAN), 35, 45
    .addEchoMessageListener(true)      // auto-respond to 0x0800 echo requests
    .replyOnError(true)                // send admin message on parse error
    .idleTimeout(30)                   // send echo after 30 s of idle
    .reconnectInterval(500)            // retry connection every 500 ms
    .maxFrameLength(8192)              // max TCP frame length in bytes
    .frameLengthFieldLength(2)         // 2-byte length header (default)
    .frameLengthFieldOffset(0)         // length header starts at byte 0
    .frameLengthFieldAdjust(0)         // no adjustment to the length value
    .encodeFrameLengthAsString(false)  // binary-encoded length header
    .workerThreadsCount(4)             // Netty worker thread pool size
    .build();

// Use the default configuration without customisation
ClientConfiguration defaults = ClientConfiguration.getDefault();
```

--------------------------------

### Customize Netty Bootstrap and Pipeline

Source: https://context7.com/kpavlov/jreactive-8583/llms.txt

Use ConnectorConfigurer to modify Netty's Bootstrap options or add custom ChannelHandlers to the pipeline during initialization. This allows for fine-grained control over connection timeouts and pipeline behavior.

```java
import com.github.kpavlov.jreactive8583.ConnectorConfigurer;
import com.github.kpavlov.jreactive8583.client.ClientConfiguration;
import io.netty.bootstrap.Bootstrap;
import io.netty.channel.ChannelOption;
import io.netty.channel.ChannelPipeline;
import io.netty.handler.timeout.ReadTimeoutHandler;
import java.util.concurrent.TimeUnit;

ConnectorConfigurer<ClientConfiguration, Bootstrap> configurer = 
    new ConnectorConfigurer<>() {
        @Override
        public void configureBootstrap(Bootstrap bootstrap, ClientConfiguration cfg) {
            // Set a custom socket connect timeout
            bootstrap.option(ChannelOption.CONNECT_TIMEOUT_MILLIS, 5000);
        }

        @Override
        public void configurePipeline(ChannelPipeline pipeline, ClientConfiguration cfg) {
            // Insert a hard read-timeout handler before the ISO8583 decoder
            pipeline.addFirst("readTimeout",
                new ReadTimeoutHandler(cfg.getIdleTimeout() * 2L, TimeUnit.SECONDS));
        }
    };

// Attach before calling init()
client.setConfigurer(configurer);
client.init();
```

--------------------------------

### J8583MessageFactory - Creating ISO 8583 Message Factories

Source: https://context7.com/kpavlov/jreactive-8583/llms.txt

Demonstrates how to create and use J8583MessageFactory for constructing and parsing ISO 8583 messages, including minimal and full configurations, and semantic API usage.

```APIDOC
## J8583MessageFactory - Creating ISO 8583 Message Factories

`J8583MessageFactory<T>` wraps the j8583 `MessageFactory` and adds typed helpers for constructing MTIs from semantic enumerations (`MessageClass`, `MessageFunction`, `MessageOrigin`) and a configured ISO version. It is the entry point for creating and parsing all ISO 8583 messages.

```java
import com.github.kpavlov.jreactive8583.iso.*;
import com.solab.iso8583.IsoMessage;
import com.solab.iso8583.parse.ConfigParser;
import java.nio.charset.StandardCharsets;

// Minimal factory (uses ConfigParser.createDefault() internally)
MessageFactory<IsoMessage> simpleFactory =
    new J8583MessageFactory<>(ISO8583Version.V1987, MessageOrigin.ACQUIRER);

// Full factory with custom j8583 MessageFactory
var rawFactory = ConfigParser.createDefault();
rawFactory.setCharacterEncoding(StandardCharsets.US_ASCII.name());
rawFactory.setUseBinaryMessages(false);
rawFactory.setAssignDate(true);
rawFactory.setTraceNumberGenerator(
    new com.solab.iso8583.impl.SimpleTraceGenerator(
        (int)(System.currentTimeMillis() % 1_000_000)));

MessageFactory<IsoMessage> factory =
    new J8583MessageFactory<>(rawFactory, ISO8583Version.V1987, MessageOrigin.OTHER);

// Create a financial request (MTI 0x0200) by raw type
IsoMessage request = factory.newMessage(0x0200);

// Create using semantic API — produces same 0x0200 for an ACQUIRER
IsoMessage semanticRequest = factory.newMessage(
    MessageClass.FINANCIAL,
    MessageFunction.REQUEST,
    MessageOrigin.ACQUIRER);

// Create response from a received request (copies MTI fields)
IsoMessage response = factory.createResponse(request);

// Parse a raw byte buffer received from the network
byte[] rawBytes = /* received from socket */ new byte[0];
IsoMessage parsed = factory.parseMessage(rawBytes, 0);
```
```

--------------------------------

### ClientConfiguration Builder

Source: https://context7.com/kpavlov/jreactive-8583/llms.txt

Configures all aspects of the client connector, including timeouts, logging, worker threads, and TCP frame parameters.

```APIDOC
## ClientConfiguration — Building Client Configuration

`ClientConfiguration` is built via a fluent builder and configures all aspects of the client connector: idle timeout, logging, sensitive-data masking, worker threads, TCP frame parameters, and automatic reconnect interval.

### Methods

- `newBuilder()`: Creates a new `ClientConfiguration` builder.
- `getDefault()`: Returns the default `ClientConfiguration`.

### Builder Methods

- `addLoggingHandler(boolean enable)`: Enable or disable IsoMessageLoggingHandler in pipeline.
- `logSensitiveData(boolean log)`: Enable or disable logging of sensitive data (PCI DSS).
- `describeFieldsInLog(boolean describe)`: Print ISO field descriptions alongside values in logs.
- `sensitiveDataFields(int... fields)`: Additionally mask specified fields.
- `addEchoMessageListener(boolean enable)`: Enable or disable auto-response to 0x0800 echo requests.
- `replyOnError(boolean enable)`: Enable or disable sending admin message on parse error.
- `idleTimeout(long timeout)`: Set the idle timeout in seconds to send an echo message.
- `reconnectInterval(long interval)`: Set the reconnect interval in milliseconds.
- `maxFrameLength(int length)`: Set the maximum TCP frame length in bytes.
- `frameLengthFieldLength(int length)`: Set the length of the length header.
- `frameLengthFieldOffset(int offset)`: Set the offset of the length header.
- `frameLengthFieldAdjust(int adjust)`: Set the adjustment to the length value.
- `encodeFrameLengthAsString(boolean encode)`: Set whether the length header is binary-encoded.
- `workerThreadsCount(int count)`: Set the Netty worker thread pool size.
- `build()`: Builds the `ClientConfiguration` object.
```

--------------------------------

### Creating and Using J8583MessageFactory

Source: https://context7.com/kpavlov/jreactive-8583/llms.txt

Instantiate `J8583MessageFactory` for creating and parsing ISO 8583 messages. It supports minimal configuration or a fully custom j8583 `MessageFactory`. Use the semantic API for creating messages based on message class, function, and origin.

```java
import com.github.kpavlov.jreactive8583.iso.*;
import com.solab.iso8583.IsoMessage;
import com.solab.iso8583.parse.ConfigParser;
import java.nio.charset.StandardCharsets;

// Minimal factory (uses ConfigParser.createDefault() internally)
MessageFactory<IsoMessage> simpleFactory =
    new J8583MessageFactory<>(ISO8583Version.V1987, MessageOrigin.ACQUIRER);

// Full factory with custom j8583 MessageFactory
var rawFactory = ConfigParser.createDefault();
rawFactory.setCharacterEncoding(StandardCharsets.US_ASCII.name());
rawFactory.setUseBinaryMessages(false);
rawFactory.setAssignDate(true);
rawFactory.setTraceNumberGenerator(
    new com.solab.iso8583.impl.SimpleTraceGenerator(
        (int)(System.currentTimeMillis() % 1_000_000)));

MessageFactory<IsoMessage> factory =
    new J8583MessageFactory<>(rawFactory, ISO8583Version.V1987, MessageOrigin.OTHER);

// Create a financial request (MTI 0x0200) by raw type
IsoMessage request = factory.newMessage(0x0200);

// Create using semantic API — produces same 0x0200 for an ACQUIRER
IsoMessage semanticRequest = factory.newMessage(
    MessageClass.FINANCIAL,
    MessageFunction.REQUEST,
    MessageOrigin.ACQUIRER);

// Create response from a received request (copies MTI fields)
IsoMessage response = factory.createResponse(request);

// Parse a raw byte buffer received from the network
byte[] rawBytes = /* received from socket */ new byte[0];
IsoMessage parsed = factory.parseMessage(rawBytes, 0);
```

--------------------------------

### Create ISO8583 Server Message Factory

Source: https://github.com/kpavlov/jreactive-8583/wiki/FAQ

Instantiate a MessageFactory for creating j8583 messages. Ensure character encoding and binary message settings are configured.

```java
MessageFactory<IsoMessage> messageFactory = ConfigParser.createDefault();
messageFactory.setCharacterEncoding(StandardCharsets.US_ASCII.name());
messageFactory.setUseBinaryMessages(false);
messageFactory.setAssignDate(true);
```

--------------------------------

### Implement IsoMessageListener for Message Handling

Source: https://context7.com/kpavlov/jreactive-8583/llms.txt

Shows how to create custom message listeners by implementing the IsoMessageListener interface. Listeners can filter messages using 'applies' and process them in 'onMessage'.

```java
import com.github.kpavlov.jreactive8583.IsoMessageListener;
import com.solab.iso8583.IsoMessage;
import io.netty.channel.ChannelHandlerContext;
import java.util.concurrent.ConcurrentHashMap;
import java.util.Map;

// Listener 1: log all messages with STAN (field 11)
IsoMessageListener<IsoMessage> auditListener = new IsoMessageListener<>() {
    private final Map<Integer, IsoMessage> log = new ConcurrentHashMap<>();

    @Override
    public boolean applies(IsoMessage msg) {
        return msg.hasField(11); // has System Trace Audit Number
    }

    @Override
    public boolean onMessage(ChannelHandlerContext ctx, IsoMessage msg) {
        int stan = Integer.parseInt(msg.getObjectValue(11).toString());
        log.put(stan, msg);
        System.out.printf("Logged STAN %d, MTI 0x%04X%n", stan, msg.getType());
        return true; // continue to next listener
    }
};

// Listener 2: handle only reversal messages (0x0400)
IsoMessageListener<IsoMessage> reversalListener = new IsoMessageListener<>() {
    @Override
    public boolean applies(IsoMessage msg) {
        return msg.getType() == 0x0400;
    }

    @Override
    public boolean onMessage(ChannelHandlerContext ctx, IsoMessage msg) {
        System.out.println("Reversal received: " + msg.debugString());
        return false; // stop — no further processing needed
    }
};

// Register both on a server
server.addMessageListener(auditListener);
server.addMessageListener(reversalListener);

// Remove a listener when no longer needed
server.removeMessageListener(auditListener);
```

--------------------------------

### j8583 XML Configuration for Message Templates and Parse Rules

Source: https://context7.com/kpavlov/jreactive-8583/llms.txt

Define message templates for outbound messages and parse rules for inbound messages in an XML file. This configuration is loaded by ConfigParser.createDefault() from the classpath.

```xml
<!-- src/test/resources/j8583.xml -->
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE j8583-config PUBLIC "-//J8583//DTD CONFIG 1.0//EN"
        "http://j8583.sourceforge.net/j8583.dtd">
<j8583-config>

    <!-- Outbound financial request template (0200) -->
    <template type="0200">
        <field num="3"   type="NUMERIC" length="6">650000</field>
        <field num="32"  type="LLVAR">456</field>
        <field num="35"  type="LLVAR">4591700012340000=</field>
        <field num="43"  type="ALPHA"   length="40">SOLABTEST TEST-3 DF MX</field>
        <field num="49"  type="ALPHA"   length="3">484</field>
        <field num="60"  type="LLLVAR">B456PRO1+000</field>
        <field num="100" type="LLVAR">999</field>
        <field num="102" type="LLVAR">ABCD</field>
    </template>

    <!-- Response template (0210) — only fields not copied from request -->
    <template type="0210">
        <field num="60"  type="LLLVAR">Fixed data from template</field>
        <field num="70"  type="ALPHA" length="3">ABC</field>
    </template>

    <!-- Echo request / response templates -->
    <template type="0800">
        <field num="70" type="NUMERIC" length="3">301</field>
    </template>
    <template type="0810">
        <field num="39" type="ALPHA" length="2">-1</field>
        <field num="70" type="NUMERIC" length="3">301</field>
    </template>

    <!-- Parse rules: define field types for inbound 0200 messages -->
    <parse type="0200">
        <field num="3"   type="NUMERIC" length="6"/>
        <field num="4"   type="AMOUNT"/>
        <field num="7"   type="DATE10"/>
        <field num="11"  type="NUMERIC" length="6"/>
        <field num="35"  type="LLVAR"/>
        <field num="43"  type="ALPHA"   length="40"/>
        <field num="49"  type="ALPHA"   length="3"/>
        <field num="60"  type="LLLVAR"/>
        <field num="100" type="LLVAR"/>
        <field num="102" type="LLVAR"/>
    </parse>

</j8583-config>
```

--------------------------------

### Configure Automatic Client Reconnection

Source: https://context7.com/kpavlov/jreactive-8583/llms.txt

Set up an Iso8583Client with a custom reconnect interval. The client automatically attempts to reconnect when the TCP connection is dropped. To disable reconnection, call disconnect() and shutdown().

```java
import com.github.kpavlov.jreactive8583.client.ClientConfiguration;
import com.github.kpavlov.jreactive8583.client.Iso8583Client;
import com.github.kpavlov.jreactive8583.iso.*;
import com.solab.iso8583.IsoMessage;
import static org.awaitility.Awaitility.await;

ClientConfiguration config = ClientConfiguration.newBuilder()
    .reconnectInterval(500)  // retry every 500 ms
    .build();

MessageFactory<IsoMessage> factory =
    new J8583MessageFactory<>(ISO8583Version.V1987, MessageOrigin.OTHER);

Iso8583Client<IsoMessage> client =
    new Iso8583Client<>("10.0.0.1", 9876, config, factory);
client.init();
client.connect();

// Simulate server restart — client reconnects automatically
server.shutdown();
await().until(() -> !client.isConnected());

server.init();
server.start();
await().until(client::isConnected); // client reconnects without any code change

// To disconnect permanently (disable reconnect)
client.disconnect();  // calls requestDisconnect() internally
client.shutdown();
```

--------------------------------

### Configure JReactive-8583 Client and Server in Spring

Source: https://context7.com/kpavlov/jreactive-8583/llms.txt

Defines prototype-scoped beans for Iso8583Client and Iso8583Server using Spring's @Configuration and @Bean annotations. Properties for host, port, and idle timeout are injected from application.properties. The J8583MessageFactory is configured with specific ISO 8583 version and message origin.

```properties
// application.properties
// iso8583.connection.host=127.0.0.1
// iso8583.connection.port=9876
// iso8583.connection.idleTimeout=30
```

```java
@Configuration
public class Iso8583Config {

    @Value("${iso8583.connection.host}") private String host;
    @Value("${iso8583.connection.port}") private int port;
    @Value("${iso8583.connection.idleTimeout}") private int idleTimeout;

    @Bean
    @Scope(SCOPE_PROTOTYPE)
    public Iso8583Client<IsoMessage> iso8583Client() throws IOException {
        var config = ClientConfiguration.newBuilder()
            .addLoggingHandler(true)
            .logSensitiveData(false)
            .idleTimeout(idleTimeout)
            .reconnectInterval(200)
            .workerThreadsCount(2)
            .build();

        var rawFactory = ConfigParser.createDefault();
        rawFactory.setCharacterEncoding("US-ASCII");
        rawFactory.setUseBinaryMessages(false);
        rawFactory.setAssignDate(true);
        rawFactory.setTraceNumberGenerator(
            new SimpleTraceGenerator((int)(System.currentTimeMillis() % 1_000_000)));
        MessageFactory<IsoMessage> factory = 
            new J8583MessageFactory<>(rawFactory, ISO8583Version.V1987, MessageOrigin.OTHER);

        return new Iso8583Client<>(new InetSocketAddress(host, port), config, factory);
    }

    @Bean
    @Scope(SCOPE_PROTOTYPE)
    public Iso8583Server<IsoMessage> iso8583Server() throws IOException {
        var config = ServerConfiguration.newBuilder()
            .workerThreadsCount(4)
            .addEchoMessageListener(true)
            .build();

        var rawFactory = ConfigParser.createDefault();
        rawFactory.setCharacterEncoding("US-ASCII");
        rawFactory.setUseBinaryMessages(false);
        rawFactory.setAssignDate(true);
        MessageFactory<IsoMessage> factory = 
            new J8583MessageFactory<>(rawFactory, ISO8583Version.V1987, MessageOrigin.ACQUIRER);

        return new Iso8583Server<>(port, config, factory);
    }
}
```

--------------------------------

### Add JReactive-8583 Dependency

Source: https://github.com/kpavlov/jreactive-8583/blob/main/README.md

Include this dependency in your project's pom.xml to use the JReactive-8583 library.

```xml
<dependencies>
        <dependency>
            <groupId>com.github.kpavlov.jreactive8583</groupId>
            <artifactId>netty-iso8583</artifactId>
            <version>${LATEST_VERSION}</version>
        </dependency>
    </dependencies>
```

--------------------------------

### Iso8583Client Usage

Source: https://context7.com/kpavlov/jreactive-8583/llms.txt

Manages connection lifecycle, message sending (sync and async), and automatic reconnection for an ISO 8583 network client.

```APIDOC
## Iso8583Client — ISO 8583 Network Client

`Iso8583Client<T>` is the main client class. It manages connection lifecycle, message sending (sync and async), and automatic reconnection. Call `init()` before connecting, and `shutdown()` when done.

### Initialization and Configuration

1. **Build Configuration**: Use `ClientConfiguration.newBuilder()` to customize client settings.
2. **Create Message Factory**: Instantiate a `MessageFactory` (e.g., `J8583MessageFactory`) for creating ISO messages.
3. **Create Client**: Instantiate `Iso8583Client` with server address, configuration, and message factory.
4. **Register Message Listener**: Add a listener to handle specific message types (e.g., responses).
5. **Initialize**: Call `client.init()` to prepare the client.
6. **Connect**: Call `client.connect(host, port)` to establish a connection.

### Sending Messages

- **Asynchronously**: `client.sendAsync(message)` returns a `ChannelFuture`.
- **Synchronously**: `client.send(message)` blocks until the message is sent.
- **With Timeout**: `client.send(message, timeout, timeUnit)` blocks with a specified timeout.

### Lifecycle Management

- **Disconnect**: `client.disconnect()` to close the connection gracefully.
- **Shutdown**: `client.shutdown()` to release resources.
```

--------------------------------

### MTI.mtiValue() - Computing Message Type Indicator Values

Source: https://context7.com/kpavlov/jreactive-8583/llms.txt

Explains how to use the `MTI.mtiValue()` method to compute the integer MTI by combining ISO version, message class, function, and origin.

```APIDOC
## MTI.mtiValue() - Computing Message Type Indicator Values

`MTI.mtiValue()` computes the integer MTI by combining the ISO version digit, message class, message function, and message origin into a single 4-digit hex value suitable for use with j8583's `newMessage(int)`.

```java
import com.github.kpavlov.jreactive8583.iso.*;

// 0x0200 — ISO 1987, Financial, Request, Acquirer
int mti = MTI.mtiValue(
    ISO8583Version.V1987,   // first digit  → 0x0000
    MessageClass.FINANCIAL, // second digit → 0x0200
    MessageFunction.REQUEST,// third digit  → 0x0000
    MessageOrigin.ACQUIRER  // fourth digit → 0x0000
);
// mti == 0x0200

// 0x0210 — ISO 1987, Financial, Request Response, Acquirer
int responseMti = MTI.mtiValue(
    ISO8583Version.V1987,
    MessageClass.FINANCIAL,
    MessageFunction.REQUEST_RESPONSE,
    MessageOrigin.ACQUIRER
);
// responseMti == 0x0210

// 0x0800 — Network management echo request
int echoMti = MTI.mtiValue(
    ISO8583Version.V1987,
    MessageClass.NETWORK_MANAGEMENT,
    MessageFunction.REQUEST,
    MessageOrigin.ACQUIRER
);
// echoMti == 0x0800
```
```

--------------------------------

### Configure Secure IsoMessageLoggingHandler

Source: https://context7.com/kpavlov/jreactive-8583/llms.txt

Enable IsoMessageLoggingHandler to mask sensitive data like PAN and track fields for PCI-DSS compliance. Configure sensitive fields and choose whether to mask sensitive data or display field names in logs.

```java
// Produced log output (logSensitiveData = false, describeFieldsInLog = true):
//
// [id: 0xa72cc005, /127.0.0.1:50853 => /127.0.0.1:9876] MTI: 0x0200
//   2: [Primary account number (PAN):NUMERIC(19)] = '000400*********0002'
//   3: [Processing code:NUMERIC(6)] = '650000'
//   7: [Transmission date & time:DATE10(10)] = '0720233443'
//  11: [System trace audit number:NUMERIC(6)] = '483248'
//  32: [Acquiring institution identification code:LLVAR(3)] = '456'
//  35: [Track 2 data:LLVAR(17)] = '***'
//  43: [Card acceptor name/location:ALPHA(40)] = 'SOLABTEST TEST-3 DF MX'
//  49: [Currency code, transaction:ALPHA(3)] = '484'

// Enable with production-safe settings:
ClientConfiguration config = ClientConfiguration.newBuilder()
    .addLoggingHandler(true)
    .logSensitiveData(false)           // mask PAN and tracks
    .describeFieldsInLog(true)         // show field names
    .sensitiveDataFields(2, 34, 35, 36, 45, 55) // custom sensitive set
    .build();

// Enable with sensitive data visible (development only):
ClientConfiguration devConfig = ClientConfiguration.newBuilder()
    .addLoggingHandler(true)
    .logSensitiveData(true)            // ⚠ DO NOT use in production
    .build();

```

--------------------------------

### Enable Automatic Echo Message Listener

Source: https://context7.com/kpavlov/jreactive-8583/llms.txt

Configure EchoMessageListener to automatically respond to network management messages (MTI 0x08xx) with a predefined response. This prevents idle-timeout disconnects by keeping the connection active.

```java
// Enable automatic echo handling on both sides
ClientConfiguration clientConfig = ClientConfiguration.newBuilder()
    .addEchoMessageListener(true)
    .idleTimeout(30)   // send echo request after 30 s idle
    .build();

ServerConfiguration serverConfig = ServerConfiguration.newBuilder()
    .addEchoMessageListener(true)
    .idleTimeout(30)
    .build();

// j8583.xml echo templates used by the default factory:
// Request  (0x0800): field 70 = NUMERIC(3) "301"
// Response (0x0810): field 39 = ALPHA(2) "-1", field 70 = NUMERIC(3) "301"

```

--------------------------------

### Gradle Dependency for JReactive-8583

Source: https://context7.com/kpavlov/jreactive-8583/llms.txt

Add this line to your Gradle build file (Kotlin DSL) to include the JReactive-8583 library.

```kotlin
implementation("com.github.kpavlov.jreactive8583:netty-iso8583:LATEST_VERSION")
```

--------------------------------

### Register ISO8583 Message Listener

Source: https://github.com/kpavlov/jreactive-8583/wiki/FAQ

Add a message listener to the server to handle incoming client messages. The listener determines which messages to process and how to respond.

```java
server.addMessageListener(new IsoMessageListener<IsoMessage>() {

            @Override
            public boolean applies(IsoMessage isoMessage) {
                return isoMessage.getType() ==  0x200;
            }

            @Override
            public boolean onMessage(ChannelHandlerContext ctx, IsoMessage isoMessage) {
                capturedRequest = isoMessage;
                final IsoMessage response = server.getIsoMessageFactory().createResponse(isoMessage);
                response.setField(39, IsoType.ALPHA.value("00", 2));
                response.setField(60, IsoType.LLLVAR.value("XXX", 3));
                ctx.writeAndFlush(response);
                return false;
            }
        });
```

--------------------------------

### Computing MTI Values with MTI.mtiValue()

Source: https://context7.com/kpavlov/jreactive-8583/llms.txt

Use `MTI.mtiValue()` to compute the integer Message Type Indicator (MTI) by combining ISO version, message class, function, and origin. This is useful for j8583's `newMessage(int)` method.

```java
import com.github.kpavlov.jreactive8583.iso.*;

// 0x0200 — ISO 1987, Financial, Request, Acquirer
int mti = MTI.mtiValue(
    ISO8583Version.V1987,   // first digit  → 0x0000
    MessageClass.FINANCIAL, // second digit → 0x0200
    MessageFunction.REQUEST,// third digit  → 0x0000
    MessageOrigin.ACQUIRER  // fourth digit → 0x0000
);
// mti == 0x0200

// 0x0210 — ISO 1987, Financial, Request Response, Acquirer
int responseMti = MTI.mtiValue(
    ISO8583Version.V1987,
    MessageClass.FINANCIAL,
    MessageFunction.REQUEST_RESPONSE,
    MessageOrigin.ACQUIRER
);
// responseMti == 0x0210

// 0x0800 — Network management echo request
int echoMti = MTI.mtiValue(
    ISO8583Version.V1987,
    MessageClass.NETWORK_MANAGEMENT,
    MessageFunction.REQUEST,
    MessageOrigin.ACQUIRER
);
// echoMti == 0x0800
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.