(feat): Add a minimum polling interval for CHANGE_ON_EVENT subscription type

plc4j/api/src/main/java/org/apache/plc4x/java/api/messages/PlcSubscriptionRequest.java

@@ -67,7 +67,7 @@ interface Builder extends PlcRequestBuilder {
          * Adds a new tag to the to be constructed request which should be polled cyclically.
          *
          * @param name            alias of the tag.
-         * @param tag           tag instance for accessing the tag.
+         * @param tag             tag instance for accessing the tag.
          * @param pollingInterval interval, in which the tag should be polled.
          * @return builder.
          */
@@ -105,6 +105,29 @@ interface Builder extends PlcRequestBuilder {
          */
         PlcSubscriptionRequest.Builder addChangeOfStateTagAddress(String name, String tagAddress, Consumer<PlcSubscriptionEvent> consumer);
 
+        /**
+         * Adds a new tag to the to be constructed request which should be updated as soon as
+         * a value changes in the PLC.
+         *
+         * @param name       alias of the tag.
+         * @param tagAddress tag address string for accessing the tag.
+         * @param minInterval min interval for updates (Limits the number of events for high frequency changes).
+         * @return builder.
+         */
+        PlcSubscriptionRequest.Builder addChangeOfStateTagAddress(String name, String tagAddress, Duration minInterval);
+
+        /**
+         * Adds a new tag to the to be constructed request which should be updated as soon as
+         * a value changes in the PLC.
+         *
+         * @param name        alias of the tag.
+         * @param tagAddress  tag address string for accessing the tag.
+         * @param consumer    consumer for receiving update events for a given tag only.
+         * @param minInterval min interval for updates (Limits the number of events for high frequency changes).
+         * @return builder.
+         */
+        PlcSubscriptionRequest.Builder addChangeOfStateTagAddress(String name, String tagAddress, Consumer<PlcSubscriptionEvent> consumer, Duration minInterval);
+
         /**
          * Adds a new tag to the to be constructed request which should be updated as soon as
          * a value changes in the PLC.
@@ -126,6 +149,29 @@ interface Builder extends PlcRequestBuilder {
          */
         PlcSubscriptionRequest.Builder addChangeOfStateTag(String name, PlcTag tag, Consumer<PlcSubscriptionEvent> consumer);
 
+        /**
+         * Adds a new tag to the to be constructed request which should be updated as soon as
+         * a value changes in the PLC.
+         *
+         * @param name        alias of the tag.
+         * @param tag         tag instance for accessing the tag.
+         * @param minInterval min interval for updates (Limits the number of events for high frequency changes).
+         * @return builder.
+         */
+        PlcSubscriptionRequest.Builder addChangeOfStateTag(String name, PlcTag tag, Duration minInterval);
+
+        /**
+         * Adds a new tag to the to be constructed request which should be updated as soon as
+         * a value changes in the PLC.
+         *
+         * @param name        alias of the tag.
+         * @param tag         tag instance for accessing the tag.
+         * @param consumer    consumer for receiving update events for a given tag only.
+         * @param minInterval min interval for updates (Limits the number of events for high frequency changes).
+         * @return builder.
+         */
+        PlcSubscriptionRequest.Builder addChangeOfStateTag(String name, PlcTag tag, Consumer<PlcSubscriptionEvent> consumer, Duration minInterval);
+
         /**
          * Adds a new subscription to the to be constructed request which should be updated
          * as soon as an event occurs.

plc4j/drivers/s7/src/main/java/org/apache/plc4x/java/s7/readwrite/utils/S7PlcSubscriptionRequest.java

@@ -21,25 +21,18 @@
 import org.apache.plc4x.java.api.exceptions.PlcRuntimeException;
 import org.apache.plc4x.java.api.messages.PlcSubscriptionEvent;
 import org.apache.plc4x.java.api.messages.PlcSubscriptionRequest;
-import org.apache.plc4x.java.api.messages.PlcSubscriptionResponse;
 import org.apache.plc4x.java.api.model.PlcSubscriptionTag;
 import org.apache.plc4x.java.api.model.PlcTag;
-import org.apache.plc4x.java.api.types.PlcResponseCode;
 import org.apache.plc4x.java.api.types.PlcSubscriptionType;
 import org.apache.plc4x.java.spi.connection.PlcTagHandler;
-import org.apache.plc4x.java.spi.generation.SerializationException;
-import org.apache.plc4x.java.spi.generation.WriteBuffer;
 import org.apache.plc4x.java.spi.messages.utils.DefaultPlcTagItem;
 import org.apache.plc4x.java.spi.messages.utils.PlcTagItem;
 import org.apache.plc4x.java.spi.model.DefaultPlcSubscriptionTag;
-import org.apache.plc4x.java.spi.utils.Serializable;
 
 import java.time.Duration;
 import java.util.*;
-import java.util.concurrent.CompletableFuture;
 import java.util.function.Consumer;
 import java.util.function.Supplier;
-import java.util.stream.Collectors;
 
 import org.apache.plc4x.java.s7.readwrite.TimeBase;
 import org.apache.plc4x.java.s7.readwrite.tag.S7SubscriptionTag;
@@ -225,40 +218,54 @@ public PlcSubscriptionRequest.Builder addCyclicTag(String name, PlcTag tag, Dura
 
         @Override
         public PlcSubscriptionRequest.Builder addChangeOfStateTagAddress(String name, String tagAddress) {
-            return addChangeOfStateTagAddress(tagAddress, name);
+            return addChangeOfStateTagAddress(name, tagAddress, null, null);
+        }
+
+        @Override
+        public PlcSubscriptionRequest.Builder addChangeOfStateTagAddress(String name, String tagAddress, Duration minInterval) {
+            return addChangeOfStateTagAddress(name, tagAddress, null, minInterval);
         }
 
-        /*
-        *
-        */
         @Override
         public PlcSubscriptionRequest.Builder addChangeOfStateTagAddress(String name, String tagAddress, Consumer<PlcSubscriptionEvent> consumer) {
+            return addChangeOfStateTagAddress(name, tagAddress, consumer, null);
+        }
+
+        @Override
+        public PlcSubscriptionRequest.Builder addChangeOfStateTagAddress(String name, String tagAddress, Consumer<PlcSubscriptionEvent> consumer, Duration minInterval) {
             if (tags.containsKey(name)) {
                 throw new PlcRuntimeException(CONST_DUPLICATE_TAG + " '" + name + "'");
             }
-            S7Tag[] s7tags = new S7Tag[]{S7Tag.of(tagAddress)};   
-            S7SubscriptionTag tag = new S7SubscriptionTag(S7SubscriptionType.CYCLIC_SUBSCRIPTION, s7tags, TimeBase.B01SEC, (short) 1);            
-            tags.put(name, new BuilderItem(() -> tag, PlcSubscriptionType.CHANGE_OF_STATE, consumer));
+            S7Tag[] s7tags = new S7Tag[]{S7Tag.of(tagAddress)};
+            S7SubscriptionTag tag = new S7SubscriptionTag(S7SubscriptionType.CYCLIC_SUBSCRIPTION, s7tags, TimeBase.B01SEC, (short) 1);
+            tags.put(name, new BuilderItem(() -> tag, PlcSubscriptionType.CHANGE_OF_STATE, minInterval, consumer));
             return this;
         }
 
         @Override
         public PlcSubscriptionRequest.Builder addChangeOfStateTag(String name, PlcTag tag) {
-            return addChangeOfStateTag(name, tag, null);
+            return addChangeOfStateTag(name, tag, null, null);
+        }
+
+        @Override
+        public PlcSubscriptionRequest.Builder addChangeOfStateTag(String name, PlcTag tag, Duration minInterval) {
+            return addChangeOfStateTag(name, tag, null, minInterval);
         }
 
-        /*
-        *
-        */        
         @Override
         public PlcSubscriptionRequest.Builder addChangeOfStateTag(String name, PlcTag tag, Consumer<PlcSubscriptionEvent> consumer) {
+            return addChangeOfStateTag(name, tag, consumer, null);
+        }
+
+        @Override
+        public PlcSubscriptionRequest.Builder addChangeOfStateTag(String name, PlcTag tag, Consumer<PlcSubscriptionEvent> consumer, Duration minInterval) {
             if (tags.containsKey(name)) {
                 throw new PlcRuntimeException(CONST_DUPLICATE_TAG + " '" + name + "'");
             }
-            if (!(tag instanceof S7SubscriptionTag)){
+            if (!(tag instanceof S7SubscriptionTag)) {
                 throw new PlcRuntimeException(CONST_INVALID_TYPE);
-            }              
-            tags.put(name, new BuilderItem(() -> tag, PlcSubscriptionType.CHANGE_OF_STATE, consumer));
+            }
+            tags.put(name, new BuilderItem(() -> tag, PlcSubscriptionType.CHANGE_OF_STATE, minInterval, consumer));
             return this;
         }
 

plc4j/spi/src/main/java/org/apache/plc4x/java/spi/messages/DefaultPlcSubscriptionRequest.java

@@ -179,31 +179,50 @@ public PlcSubscriptionRequest.Builder addCyclicTag(String name, PlcTag tag, Dura
 
         @Override
         public PlcSubscriptionRequest.Builder addChangeOfStateTagAddress(String name, String tagAddress) {
-            addChangeOfStateTagAddress(name, tagAddress, null);
-            return this;
+            return addChangeOfStateTagAddress(name, tagAddress, null, null);
+        }
+
+        @Override
+        public PlcSubscriptionRequest.Builder addChangeOfStateTagAddress(String name, String tagAddress, Duration minInterval) {
+            return addChangeOfStateTagAddress(name, tagAddress, null, minInterval);
         }
 
         @Override
         public PlcSubscriptionRequest.Builder addChangeOfStateTagAddress(String name, String tagAddress, Consumer<PlcSubscriptionEvent> consumer) {
+            return addChangeOfStateTagAddress(name, tagAddress, consumer, null);
+        }
+
+        @Override
+        public PlcSubscriptionRequest.Builder addChangeOfStateTagAddress(String name, String tagAddress, Consumer<PlcSubscriptionEvent> consumer, Duration minInterval) {
             if (tags.containsKey(name)) {
                 throw new PlcRuntimeException("Duplicate tag definition '" + name + "'");
             }
-            tags.put(name, new BuilderItem(() -> tagHandler.parseTag(tagAddress), PlcSubscriptionType.CHANGE_OF_STATE, consumer));
-            return null;
+            tags.put(name, new BuilderItem(() -> tagHandler.parseTag(tagAddress), PlcSubscriptionType.CHANGE_OF_STATE, minInterval, consumer));
+            return this;
         }
 
         @Override
         public PlcSubscriptionRequest.Builder addChangeOfStateTag(String name, PlcTag tag) {
-            addChangeOfStateTag(name, tag, null);
-            return this;
+            return addChangeOfStateTag(name, tag, null, null);
+        }
+
+        @Override
+        public PlcSubscriptionRequest.Builder addChangeOfStateTag(String name, PlcTag tag, Duration minInterval) {
+            return addChangeOfStateTag(name, tag, null, minInterval);
         }
 
         @Override
         public PlcSubscriptionRequest.Builder addChangeOfStateTag(String name, PlcTag tag, Consumer<PlcSubscriptionEvent> consumer) {
+            return addChangeOfStateTag(name, tag, consumer, null);
+        }
+
+        @Override
+        public PlcSubscriptionRequest.Builder addChangeOfStateTag(String name, PlcTag tag, Consumer<PlcSubscriptionEvent> consumer,
+                                                                  Duration minInterval) {
             if (tags.containsKey(name)) {
                 throw new PlcRuntimeException("Duplicate tag definition '" + name + "'");
             }
-            tags.put(name, new BuilderItem(() -> tag, PlcSubscriptionType.CHANGE_OF_STATE, consumer));
+            tags.put(name, new BuilderItem(() -> tag, PlcSubscriptionType.CHANGE_OF_STATE, minInterval, consumer));
             return this;
         }
 

plc4j/tools/connection-cache/src/main/java/org/apache/plc4x/java/utils/cache/LeasedPlcConnection.java

@@ -394,6 +394,16 @@ public PlcSubscriptionRequest.Builder addChangeOfStateTagAddress(String name, St
                 return innerBuilder.addChangeOfStateTagAddress(name, tagAddress, consumer);
             }
 
+            @Override
+            public PlcSubscriptionRequest.Builder addChangeOfStateTagAddress(String name, String tagAddress, Duration minInterval) {
+                return innerBuilder.addChangeOfStateTagAddress(name, tagAddress, minInterval);
+            }
+
+            @Override
+            public PlcSubscriptionRequest.Builder addChangeOfStateTagAddress(String name, String tagAddress, Consumer<PlcSubscriptionEvent> consumer, Duration minInterval) {
+                return innerBuilder.addChangeOfStateTagAddress(name, tagAddress, consumer, minInterval);
+            }
+
             @Override
             public PlcSubscriptionRequest.Builder addChangeOfStateTag(String name, PlcTag tag) {
                 return innerBuilder.addChangeOfStateTag(name, tag);
@@ -404,6 +414,16 @@ public PlcSubscriptionRequest.Builder addChangeOfStateTag(String name, PlcTag ta
                 return innerBuilder.addChangeOfStateTag(name, tag, consumer);
             }
 
+            @Override
+            public PlcSubscriptionRequest.Builder addChangeOfStateTag(String name, PlcTag tag, Duration minInterval) {
+                return innerBuilder.addChangeOfStateTag(name, tag, minInterval);
+            }
+
+            @Override
+            public PlcSubscriptionRequest.Builder addChangeOfStateTag(String name, PlcTag tag, Consumer<PlcSubscriptionEvent> consumer, Duration minInterval) {
+                return innerBuilder.addChangeOfStateTag(name, tag, consumer, minInterval);
+            }
+
             @Override
             public PlcSubscriptionRequest.Builder addEventTagAddress(String name, String tagAddress) {
                 return innerBuilder.addEventTagAddress(name, tagAddress);