Write Operations

/**
 * Write request interface for sending data to PLC tags
 */
public interface PlcWriteRequest extends PlcTagRequest {
    /**
     * Execute the write request asynchronously
     * @return CompletableFuture containing the write response
     */
    CompletableFuture<? extends PlcWriteResponse> execute();
    
    /**
     * Get number of values for a specific tag
     * @param name Tag name from request
     * @return Number of values to write
     */
    int getNumberOfValues(String name);
    
    /**
     * Get PlcValue for a specific tag
     * @param name Tag name from request
     * @return PlcValue containing the data to write
     */
    PlcValue getPlcValue(String name);
    
    /**
     * Builder interface for constructing write requests
     */
    interface Builder extends PlcRequestBuilder {
        /**
         * Add a tag by address string with values to write
         * @param name Logical name for the tag
         * @param tagAddress PLC-specific tag address string
         * @param values Values to write (varargs for arrays)
         * @return Builder instance for method chaining
         */
        Builder addTagAddress(String name, String tagAddress, Object... values);
        
        /**
         * Add a pre-parsed tag object with values to write
         * @param name Logical name for the tag
         * @param tag PlcTag instance
         * @param values Values to write (varargs for arrays)
         * @return Builder instance for method chaining
         */
        Builder addTag(String name, PlcTag tag, Object... values);
        
        /**
         * Build the write request
         * @return PlcWriteRequest instance ready for execution
         */
        PlcWriteRequest build();
    }
}

/**
 * Write response interface providing status information for write operations
 */
public interface PlcWriteResponse extends PlcTagResponse {
    /**
     * Get the originating write request
     * @return PlcWriteRequest that generated this response
     */
    PlcWriteRequest getRequest();
}

import org.apache.plc4x.java.DefaultPlcDriverManager;
import org.apache.plc4x.java.api.PlcConnection;
import org.apache.plc4x.java.api.messages.PlcWriteRequest;
import org.apache.plc4x.java.api.messages.PlcWriteResponse;
import org.apache.plc4x.java.api.types.PlcResponseCode;

// Basic write operation
PlcDriverManager driverManager = new DefaultPlcDriverManager();
try (PlcConnection connection = driverManager.getConnection("modbus-tcp://192.168.1.100:502")) {
    connection.connect();
    
    // Build write request with single values
    PlcWriteRequest writeRequest = connection.writeRequestBuilder()
        .addTagAddress("setpoint", "holding-register:1", 25.5f)
        .addTagAddress("enable", "coil:10", true)
        .addTagAddress("counter", "holding-register:5", 1234)
        .build();
    
    // Execute asynchronously
    CompletableFuture<? extends PlcWriteResponse> future = writeRequest.execute();
    PlcWriteResponse response = future.get(); // Or use async callbacks
    
    // Check response codes
    if (response.getResponseCode("setpoint") == PlcResponseCode.OK) {
        System.out.println("Setpoint written successfully");
    }
    
    if (response.getResponseCode("enable") == PlcResponseCode.OK) {
        System.out.println("Enable flag written successfully");
    }
    
    if (response.getResponseCode("counter") == PlcResponseCode.OK) {
        System.out.println("Counter written successfully");
    }
}

// Array write operation
try (PlcConnection connection = driverManager.getConnection("s7://192.168.1.200/0/1")) {
    connection.connect();
    
    // Write array of values
    float[] sensorValues = {12.5f, 13.2f, 14.1f, 15.0f, 16.8f};
    
    PlcWriteRequest writeRequest = connection.writeRequestBuilder()
        .addTagAddress("sensors", "DB1.DBD0:REAL[5]", (Object[]) sensorValues)
        .build();
    
    PlcWriteResponse response = writeRequest.execute().get();
    
    if (response.getResponseCode("sensors") == PlcResponseCode.OK) {
        System.out.println("Sensor array written successfully");
    }
}

// Mixed data types write
try (PlcConnection connection = driverManager.getConnection("modbus-tcp://192.168.1.100:502")) {
    connection.connect();
    
    PlcWriteRequest writeRequest = connection.writeRequestBuilder()
        .addTagAddress("temperature", "holding-register:100", 23.5)
        .addTagAddress("humidity", "holding-register:101", 65)
        .addTagAddress("alarm_status", "coil:1", false)
        .addTagAddress("device_id", "holding-register:200", "DEV001")
        .build();
    
    PlcWriteResponse response = writeRequest.execute().get();
    
    // Check all response codes
    for (String tagName : response.getTagNames()) {
        PlcResponseCode code = response.getResponseCode(tagName);
        if (code == PlcResponseCode.OK) {
            System.out.println("Tag '" + tagName + "' written successfully");
        } else {
            System.out.println("Failed to write tag '" + tagName + "': " + code);
        }
    }
}

// Error handling and validation
try (PlcConnection connection = driverManager.getConnection("modbus-tcp://192.168.1.100:502")) {
    connection.connect();
    
    PlcWriteRequest writeRequest = connection.writeRequestBuilder()
        .addTagAddress("readonly", "input-register:1", 100) // This might fail
        .addTagAddress("outofrange", "holding-register:999", 50) // This might fail
        .build();
    
    PlcWriteResponse response = writeRequest.execute().get();
    
    // Handle different error conditions
    PlcResponseCode readonlyCode = response.getResponseCode("readonly");
    switch (readonlyCode) {
        case OK:
            System.out.println("Write successful");
            break;
        case ACCESS_DENIED:
            System.out.println("Tag is read-only");
            break;
        case INVALID_ADDRESS:
            System.out.println("Invalid tag address");
            break;
        case INVALID_DATATYPE:
            System.out.println("Data type mismatch");
            break;
        case INVALID_DATA:
            System.out.println("Invalid data value");
            break;
        default:
            System.out.println("Write failed: " + readonlyCode);
            break;
    }
}

// Complex data structure write
try (PlcConnection connection = driverManager.getConnection("s7://192.168.1.200/0/1")) {
    connection.connect();
    
    // Write multiple related values as a batch
    PlcWriteRequest writeRequest = connection.writeRequestBuilder()
        .addTagAddress("recipe.temperature", "DB10.DBD0:REAL", 180.5f)
        .addTagAddress("recipe.pressure", "DB10.DBD4:REAL", 2.5f)
        .addTagAddress("recipe.duration", "DB10.DBD8:DINT", 3600)
        .addTagAddress("recipe.active", "DB10.DBX12.0:BOOL", true)
        .build();
    
    PlcWriteResponse response = writeRequest.execute().get();
    
    // Verify all recipe parameters were written
    boolean allSuccess = response.getTagNames().stream()
        .allMatch(tagName -> response.getResponseCode(tagName) == PlcResponseCode.OK);
    
    if (allSuccess) {
        System.out.println("Recipe parameters written successfully");
    } else {
        System.out.println("Some recipe parameters failed to write");
        response.getTagNames().forEach(tagName -> {
            PlcResponseCode code = response.getResponseCode(tagName);
            if (code != PlcResponseCode.OK) {
                System.out.println("Failed: " + tagName + " - " + code);
            }
        });
    }
}

// Async write with callbacks
try (PlcConnection connection = driverManager.getConnection("modbus-tcp://192.168.1.100:502")) {
    connection.connect();
    
    PlcWriteRequest writeRequest = connection.writeRequestBuilder()
        .addTagAddress("status", "coil:1", true)
        .build();
    
    // Use async callbacks instead of blocking
    writeRequest.execute()
        .thenAccept(response -> {
            if (response.getResponseCode("status") == PlcResponseCode.OK) {
                System.out.println("Status updated successfully");
            } else {
                System.out.println("Failed to update status");
            }
        })
        .exceptionally(throwable -> {
            System.err.println("Write operation failed: " + throwable.getMessage());
            return null;
        });
}

public enum PlcResponseCode {
    OK,                    // Write successful
    NOT_FOUND,            // Tag not found
    ACCESS_DENIED,        // Tag is read-only or access denied
    INVALID_ADDRESS,      // Invalid tag address format
    INVALID_DATATYPE,     // Data type mismatch
    INVALID_DATA,         // Invalid data value or out of range
    INTERNAL_ERROR,       // PLC internal error
    REMOTE_BUSY,          // PLC is busy
    REMOTE_ERROR,         // PLC reported an error
    UNSUPPORTED,          // Operation not supported
    RESPONSE_PENDING      // Response still pending
}