Read Operations

/**
 * Read request interface for retrieving data from PLC tags
 */
public interface PlcReadRequest extends PlcTagRequest {
    /**
     * Execute the read request asynchronously
     * @return CompletableFuture containing the read response
     */
    CompletableFuture<? extends PlcReadResponse> execute();
    
    /**
     * Builder interface for constructing read requests
     */
    interface Builder extends PlcRequestBuilder {
        /**
         * Add a tag by address string
         * @param name Logical name for the tag
         * @param tagAddress PLC-specific tag address string
         * @return Builder instance for method chaining
         */
        Builder addTagAddress(String name, String tagAddress);
        
        /**
         * Add a pre-parsed tag object
         * @param name Logical name for the tag
         * @param tag PlcTag instance
         * @return Builder instance for method chaining
         */
        Builder addTag(String name, PlcTag tag);
        
        /**
         * Build the read request
         * @return PlcReadRequest instance ready for execution
         */
        PlcReadRequest build();
    }
}

/**
 * Read response interface providing type-safe access to read values
 */
public interface PlcReadResponse extends PlcTagResponse {
    /**
     * Get the originating read request
     * @return PlcReadRequest that generated this response
     */
    PlcReadRequest getRequest();
    
    /**
     * Get single PlcValue (experimental - for single-tag requests)
     * @return PlcValue for single-tag responses
     */
    @Experimental
    PlcValue getAsPlcValue();
    
    /**
     * Get PlcValue by tag name
     * @param name Tag name from request
     * @return PlcValue for the specified tag
     */
    PlcValue getPlcValue(String name);
    
    /**
     * Get number of values for a tag (for array tags)
     * @param name Tag name from request
     * @return Number of values available
     */
    int getNumberOfValues(String name);
    
    // Type-specific getters with validation
    /**
     * Check if tag value is a valid boolean
     * @param name Tag name
     * @return true if value can be converted to boolean
     */
    boolean isValidBoolean(String name);
    
    /**
     * Get boolean value for tag
     * @param name Tag name
     * @return boolean value
     * @throws PlcIncompatibleDatatypeException if conversion fails
     */
    boolean getBoolean(String name);
    
    /**
     * Get boolean value at specific index for array tags
     * @param name Tag name
     * @param index Array index
     * @return boolean value at index
     */
    boolean getBoolean(String name, int index);
    
    /**
     * Check if tag value is a valid byte
     * @param name Tag name
     * @return true if value can be converted to byte
     */
    boolean isValidByte(String name);
    
    /**
     * Get byte value for tag
     * @param name Tag name
     * @return byte value
     */
    byte getByte(String name);
    
    /**
     * Get byte value at specific index
     * @param name Tag name
     * @param index Array index
     * @return byte value at index
     */
    byte getByte(String name, int index);
    
    /**
     * Check if tag value is a valid short
     * @param name Tag name
     * @return true if value can be converted to short
     */
    boolean isValidShort(String name);
    
    /**
     * Get short value for tag
     * @param name Tag name
     * @return short value
     */
    short getShort(String name);
    
    /**
     * Get short value at specific index
     * @param name Tag name
     * @param index Array index
     * @return short value at index
     */
    short getShort(String name, int index);
    
    /**
     * Check if tag value is a valid integer
     * @param name Tag name
     * @return true if value can be converted to integer
     */
    boolean isValidInteger(String name);
    
    /**
     * Get integer value for tag
     * @param name Tag name
     * @return integer value
     */
    int getInteger(String name);
    
    /**
     * Get integer value at specific index
     * @param name Tag name
     * @param index Array index
     * @return integer value at index
     */
    int getInteger(String name, int index);
    
    /**
     * Check if tag value is a valid long
     * @param name Tag name
     * @return true if value can be converted to long
     */
    boolean isValidLong(String name);
    
    /**
     * Get long value for tag
     * @param name Tag name
     * @return long value
     */
    long getLong(String name);
    
    /**
     * Get long value at specific index
     * @param name Tag name
     * @param index Array index
     * @return long value at index
     */
    long getLong(String name, int index);
    
    /**
     * Check if tag value is a valid float
     * @param name Tag name
     * @return true if value can be converted to float
     */
    boolean isValidFloat(String name);
    
    /**
     * Get float value for tag
     * @param name Tag name
     * @return float value
     */
    float getFloat(String name);
    
    /**
     * Get float value at specific index
     * @param name Tag name
     * @param index Array index
     * @return float value at index
     */
    float getFloat(String name, int index);
    
    /**
     * Check if tag value is a valid double
     * @param name Tag name
     * @return true if value can be converted to double
     */
    boolean isValidDouble(String name);
    
    /**
     * Get double value for tag
     * @param name Tag name
     * @return double value
     */
    double getDouble(String name);
    
    /**
     * Get double value at specific index
     * @param name Tag name
     * @param index Array index
     * @return double value at index
     */
    double getDouble(String name, int index);
    
    /**
     * Check if tag value is a valid string
     * @param name Tag name
     * @return true if value can be converted to string
     */
    boolean isValidString(String name);
    
    /**
     * Get string value for tag
     * @param name Tag name
     * @return string value
     */
    String getString(String name);
    
    /**
     * Get string value at specific index
     * @param name Tag name
     * @param index Array index
     * @return string value at index
     */
    String getString(String name, int index);
    
    /**
     * Check if tag value is a valid time
     * @param name Tag name
     * @return true if value can be converted to time
     */
    boolean isValidTime(String name);
    
    /**
     * Get time value for tag
     * @param name Tag name
     * @return LocalTime value
     */
    LocalTime getTime(String name);
    
    /**
     * Get time value at specific index
     * @param name Tag name
     * @param index Array index
     * @return LocalTime value at index
     */
    LocalTime getTime(String name, int index);
    
    /**
     * Check if tag value is a valid date
     * @param name Tag name
     * @return true if value can be converted to date
     */
    boolean isValidDate(String name);
    
    /**
     * Get date value for tag
     * @param name Tag name
     * @return LocalDate value
     */
    LocalDate getDate(String name);
    
    /**
     * Get date value at specific index
     * @param name Tag name
     * @param index Array index
     * @return LocalDate value at index
     */
    LocalDate getDate(String name, int index);
    
    /**
     * Check if tag value is a valid datetime
     * @param name Tag name
     * @return true if value can be converted to datetime
     */
    boolean isValidDateTime(String name);
    
    /**
     * Get datetime value for tag
     * @param name Tag name
     * @return LocalDateTime value
     */
    LocalDateTime getDateTime(String name);
    
    /**
     * Get datetime value at specific index
     * @param name Tag name
     * @param index Array index
     * @return LocalDateTime value at index
     */
    LocalDateTime getDateTime(String name, int index);
    
    /**
     * Check if tag value is a valid BigInteger
     * @param name Tag name
     * @return true if value can be converted to BigInteger
     */
    boolean isValidBigInteger(String name);
    
    /**
     * Get BigInteger value for tag
     * @param name Tag name
     * @return BigInteger value
     */
    BigInteger getBigInteger(String name);
    
    /**
     * Get BigInteger value at specific index
     * @param name Tag name
     * @param index Array index
     * @return BigInteger value at index
     */
    BigInteger getBigInteger(String name, int index);
    
    /**
     * Check if tag value is a valid BigDecimal
     * @param name Tag name
     * @return true if value can be converted to BigDecimal
     */
    boolean isValidBigDecimal(String name);
    
    /**
     * Get BigDecimal value for tag
     * @param name Tag name
     * @return BigDecimal value
     */
    BigDecimal getBigDecimal(String name);
    
    /**
     * Get BigDecimal value at specific index
     * @param name Tag name
     * @param index Array index
     * @return BigDecimal value at index
     */
    BigDecimal getBigDecimal(String name, int index);
    
    // Collection getters for array values
    /**
     * Get all boolean values for array tag
     * @param name Tag name
     * @return Collection of boolean values
     */
    Collection<Boolean> getAllBooleans(String name);
    
    /**
     * Get all byte values for array tag
     * @param name Tag name
     * @return Collection of byte values
     */
    Collection<Byte> getAllBytes(String name);
    
    /**
     * Get all short values for array tag
     * @param name Tag name
     * @return Collection of short values
     */
    Collection<Short> getAllShorts(String name);
    
    /**
     * Get all integer values for array tag
     * @param name Tag name
     * @return Collection of integer values
     */
    Collection<Integer> getAllIntegers(String name);
    
    /**
     * Get all long values for array tag
     * @param name Tag name
     * @return Collection of long values
     */
    Collection<Long> getAllLongs(String name);
    
    /**
     * Get all float values for array tag
     * @param name Tag name
     * @return Collection of float values
     */
    Collection<Float> getAllFloats(String name);
    
    /**
     * Get all double values for array tag
     * @param name Tag name
     * @return Collection of double values
     */
    Collection<Double> getAllDoubles(String name);
    
    /**
     * Get all string values for array tag
     * @param name Tag name
     * @return Collection of string values
     */
    Collection<String> getAllStrings(String name);
}

import org.apache.plc4x.java.DefaultPlcDriverManager;
import org.apache.plc4x.java.api.PlcConnection;
import org.apache.plc4x.java.api.messages.PlcReadRequest;
import org.apache.plc4x.java.api.messages.PlcReadResponse;
import org.apache.plc4x.java.api.types.PlcResponseCode;

// Basic read operation
PlcDriverManager driverManager = new DefaultPlcDriverManager();
try (PlcConnection connection = driverManager.getConnection("modbus-tcp://192.168.1.100:502")) {
    connection.connect();
    
    // Build read request
    PlcReadRequest readRequest = connection.readRequestBuilder()
        .addTagAddress("temperature", "holding-register:1")
        .addTagAddress("pressure", "holding-register:2")
        .addTagAddress("status", "coil:10")
        .build();
    
    // Execute asynchronously
    CompletableFuture<? extends PlcReadResponse> future = readRequest.execute();
    PlcReadResponse response = future.get(); // Or use async callbacks
    
    // Check response codes and extract values
    if (response.getResponseCode("temperature") == PlcResponseCode.OK) {
        // Type validation
        if (response.isValidFloat("temperature")) {
            float temp = response.getFloat("temperature");
            System.out.println("Temperature: " + temp + "°C");
        }
        
        if (response.isValidInteger("pressure")) {
            int pressure = response.getInteger("pressure");
            System.out.println("Pressure: " + pressure + " bar");
        }
        
        if (response.isValidBoolean("status")) {
            boolean status = response.getBoolean("status");
            System.out.println("Status: " + (status ? "ON" : "OFF"));
        }
    }
}

// Array tag reading
try (PlcConnection connection = driverManager.getConnection("s7://192.168.1.200/0/1")) {
    connection.connect();
    
    PlcReadRequest readRequest = connection.readRequestBuilder()
        .addTagAddress("sensors", "DB1.DBD0:REAL[10]") // Array of 10 floats
        .build();
    
    PlcReadResponse response = readRequest.execute().get();
    
    if (response.getResponseCode("sensors") == PlcResponseCode.OK) {
        // Get number of values
        int count = response.getNumberOfValues("sensors");
        System.out.println("Array size: " + count);
        
        // Access individual elements
        for (int i = 0; i < count; i++) {
            if (response.isValidFloat("sensors")) {
                float value = response.getFloat("sensors", i);
                System.out.println("Sensor[" + i + "]: " + value);
            }
        }
        
        // Or get all values at once
        Collection<Float> allValues = response.getAllFloats("sensors");
        System.out.println("All sensor values: " + allValues);
    }
}

// Using PlcValue directly for complex types
try (PlcConnection connection = driverManager.getConnection("modbus-tcp://192.168.1.100:502")) {
    connection.connect();
    
    PlcReadRequest readRequest = connection.readRequestBuilder()
        .addTagAddress("data", "holding-register:100[5]")
        .build();
    
    PlcReadResponse response = readRequest.execute().get();
    
    if (response.getResponseCode("data") == PlcResponseCode.OK) {
        PlcValue value = response.getPlcValue("data");
        
        // Check if it's a list/array
        if (value.isList()) {
            System.out.println("Array length: " + value.getLength());
            
            // Access individual elements
            for (int i = 0; i < value.getLength(); i++) {
                PlcValue element = value.getIndex(i);
                if (element.isInteger()) {
                    System.out.println("Element[" + i + "]: " + element.getInteger());
                }
            }
        }
    }
}

// Error handling
try (PlcConnection connection = driverManager.getConnection("modbus-tcp://192.168.1.100:502")) {
    connection.connect();
    
    PlcReadRequest readRequest = connection.readRequestBuilder()
        .addTagAddress("invalid", "non-existent:999")
        .build();
    
    PlcReadResponse response = readRequest.execute().get();
    
    // Check individual response codes
    PlcResponseCode code = response.getResponseCode("invalid");
    switch (code) {
        case OK:
            System.out.println("Success: " + response.getString("invalid"));
            break;
        case NOT_FOUND:
            System.out.println("Tag not found");
            break;
        case ACCESS_DENIED:
            System.out.println("Access denied");
            break;
        case INVALID_ADDRESS:
            System.out.println("Invalid tag address");
            break;
        default:
            System.out.println("Error: " + code);
            break;
    }
}

public interface PlcTagRequest extends PlcRequest {
    CompletableFuture<? extends PlcTagResponse> execute();
    int getNumberOfTags();
    LinkedHashSet<String> getTagNames();
    PlcResponseCode getTagResponseCode(String tagName);
    PlcTag getTag(String tagName);
    List<PlcTag> getTags();
}

public interface PlcTagResponse extends PlcResponse {
    PlcTagRequest getRequest();
    Collection<String> getTagNames();
    PlcTag getTag(String name);
    PlcResponseCode getResponseCode(String name);
    Metadata getTagMetadata(String name);
}