feat: First draft of a publication API (Still needs some fine-tuning)

.mvn/jvm.config

@@ -1 +1 @@
---add-exports jdk.compiler/com.sun.tools.javac.api=ALL-UNNAMED --add-exports jdk.compiler/com.sun.tools.javac.file=ALL-UNNAMED --add-exports jdk.compiler/com.sun.tools.javac.parser=ALL-UNNAMED --add-exports jdk.compiler/com.sun.tools.javac.tree=ALL-UNNAMED --add-exports jdk.compiler/com.sun.tools.javac.util=ALL-UNNAMED
+-XX:+EnableDynamicAgentLoading --add-exports jdk.compiler/com.sun.tools.javac.api=ALL-UNNAMED --add-exports jdk.compiler/com.sun.tools.javac.file=ALL-UNNAMED --add-exports jdk.compiler/com.sun.tools.javac.parser=ALL-UNNAMED --add-exports jdk.compiler/com.sun.tools.javac.tree=ALL-UNNAMED --add-exports jdk.compiler/com.sun.tools.javac.util=ALL-UNNAMED

plc4j/api/src/main/java/org/apache/plc4x/java/api/PlcConnection.java

@@ -56,10 +56,7 @@ public interface PlcConnection extends AutoCloseable {
  *
  * @throws PlcRuntimeException If the string cannot be parsed
  */
- @Deprecated
- default PlcTag parseTagAddress(String tagAddress) throws PlcInvalidTagException {
- throw new PlcRuntimeException("Parse method is not implemented for this connection / driver");
- }
+ PlcTag parseTagAddress(String tagAddress) throws PlcInvalidTagException;
 
  /**
  * Provides connection metadata.

plc4j/api/src/main/java/org/apache/plc4x/java/api/messages/PlcSubscriptionTagRequest.java → plc4j/api/src/main/java/org/apache/plc4x/java/api/messages/PlcPublicationEventRequest.java

@@ -18,27 +18,13 @@
  */
 package org.apache.plc4x.java.api.messages;
 
-import org.apache.plc4x.java.api.model.PlcSubscriptionTag;
+import java.time.Instant;
 
-import java.util.LinkedHashSet;
-import java.util.List;
-import java.util.Map;
-import java.util.concurrent.CompletableFuture;
-import java.util.function.Consumer;
+public interface PlcPublicationEventRequest extends PlcWriteRequest {
 
-public interface PlcSubscriptionTagRequest extends PlcRequest {
-
- @Override
- CompletableFuture<? extends PlcSubscriptionTagResponse> execute();
-
- int getNumberOfTags();
-
- LinkedHashSet<String> getTagNames();
-
- PlcSubscriptionTag getTag(String name);
-
- List<PlcSubscriptionTag> getTags();
-
- Map<String, List<Consumer<PlcSubscriptionEvent>>> getPreRegisteredConsumers();
+ /**
+ * @return the timestamp at which this event occurred.
+ */
+ Instant getTimestamp();
 
 }

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

@@ -0,0 +1,23 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.plc4x.java.api.messages;
+
+public interface PlcPublicationEventResponse extends PlcWriteResponse {
+
+}

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

@@ -0,0 +1,96 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.plc4x.java.api.messages;
+
+import org.apache.plc4x.java.api.model.PlcPublicationTag;
+import org.apache.plc4x.java.api.model.PlcTag;
+import org.apache.plc4x.java.api.value.PlcValue;
+
+import java.time.Duration;
+import java.util.LinkedHashSet;
+import java.util.List;
+import java.util.concurrent.CompletableFuture;
+
+public interface PlcPublicationRequest extends PlcRequest {
+
+ @Override
+ CompletableFuture<? extends PlcPublicationResponse> execute();
+
+ int getNumberOfTags();
+
+ LinkedHashSet<String> getTagNames();
+
+ PlcPublicationTag getTag(String name);
+
+ List<PlcPublicationTag> getTags();
+
+ interface Builder extends PlcRequestBuilder {
+
+ @Override
+ PlcPublicationRequest build();
+
+ /**
+ * Adds a new tag to the to be constructed request which should be published cyclically.
+ * In this case will the driver regularly publish the given value, if it has changed or not.
+ *
+ * @param name alias of the tag.
+ * @param tagAddress tag address string for accessing the tag.
+ * @param publicationInterval interval, in which the tag should be published.
+ * @param initialValue initial value of the tag
+ * @return builder.
+ */
+ PlcPublicationRequest.Builder addCyclicTagAddress(String name, String tagAddress, Duration publicationInterval, PlcValue initialValue);
+
+ /**
+ * Adds a new tag to the to be constructed request which should be published cyclically.
+ * In this case will the driver regularly publish the given value, if it has changed or not.
+ *
+ * @param name alias of the tag.
+ * @param tag tag instance for accessing the tag.
+ * @param publicationInterval interval, in which the tag should be published.
+ * @param initialValue initial value of the tag
+ * @return builder.
+ */
+ PlcPublicationRequest.Builder addCyclicTag(String name, PlcTag tag, Duration publicationInterval, PlcValue initialValue);
+
+ /**
+ * Adds a new tag to the to be constructed request which should be published as soon as
+ * a value changes locally.
+ *
+ * @param name alias of the tag.
+ * @param tagAddress tag address string for accessing the tag.
+ * @param initialValue initial value of the tag
+ * @return builder.
+ */
+ PlcPublicationRequest.Builder addChangeOfStateTagAddress(String name, String tagAddress, PlcValue initialValue);
+
+ /**
+ * Adds a new tag to the to be constructed request which should be published as soon as
+ * a value changes locally.
+ *
+ * @param name alias of the tag.
+ * @param tag tag instance for accessing the tag.
+ * @param initialValue initial value of the tag
+ * @return builder.
+ */
+ PlcPublicationRequest.Builder addChangeOfStateTag(String name, PlcTag tag, PlcValue initialValue);
+
+ }
+
+}

plc4j/api/src/main/java/org/apache/plc4x/java/api/messages/PlcSubscriptionTagResponse.java → plc4j/api/src/main/java/org/apache/plc4x/java/api/messages/PlcPublicationResponse.java

@@ -18,24 +18,21 @@
  */
 package org.apache.plc4x.java.api.messages;
 
-import org.apache.plc4x.java.api.model.PlcSubscriptionTag;
+import org.apache.plc4x.java.api.model.PlcPublicationTag;
 import org.apache.plc4x.java.api.types.PlcResponseCode;
 
 import java.util.Collection;
 
-/**
- * Base type for all response messages sent as response for a prior request
- * from a plc to the plc4x system.
- */
-public interface PlcSubscriptionTagResponse extends PlcResponse {
+public interface PlcPublicationResponse extends PlcResponse {
 
  @Override
- PlcSubscriptionTagRequest getRequest();
+ PlcPublicationRequest getRequest();
 
  Collection<String> getTagNames();
 
- PlcSubscriptionTag getTag(String name);
+ PlcPublicationTag getTag(String name);
 
  PlcResponseCode getResponseCode(String name);
 
+
 }

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

@@ -24,5 +24,7 @@
  * Base type for all messages sent from the plc4x system to a connected plc.
  */
 public interface PlcRequest extends PlcMessage {
+
  CompletableFuture<? extends PlcResponse> execute();
+
 }

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

@@ -18,18 +18,32 @@
  */
 package org.apache.plc4x.java.api.messages;
 
-import org.apache.plc4x.java.api.model.PlcConsumerRegistration;
+import org.apache.plc4x.java.api.model.PlcSubscriptionTag;
 import org.apache.plc4x.java.api.model.PlcTag;
 
 import java.time.Duration;
+import java.util.LinkedHashSet;
+import java.util.List;
 import java.util.concurrent.CompletableFuture;
 import java.util.function.Consumer;
 
-public interface PlcSubscriptionRequest extends PlcSubscriptionTagRequest {
+public interface PlcSubscriptionRequest extends PlcRequest {
 
  @Override
  CompletableFuture<? extends PlcSubscriptionResponse> execute();
 
+ CompletableFuture<? extends PlcSubscriptionResponse> executeWithConsumer(Consumer<PlcSubscriptionEvent> subscriptionConsumer);
+
+ int getNumberOfTags();
+
+ LinkedHashSet<String> getTagNames();
+
+ PlcSubscriptionTag getTag(String name);
+
+ List<PlcSubscriptionTag> getTags();
+
+ List<Consumer<PlcSubscriptionEvent>> getConsumers();
+
  interface Builder extends PlcRequestBuilder {
 
  @Override
@@ -99,18 +113,6 @@ interface Builder extends PlcRequestBuilder {
  */
  PlcSubscriptionRequest.Builder addEventTag(String name, PlcTag tag);
 
- /**
- * Convenience method which attaches the {@link Consumer<PlcSubscriptionEvent>} directly to the handles once the
- * requests succeeds.
- * Note: opposed to register on the {@link org.apache.plc4x.java.api.model.PlcSubscriptionHandle} directly you
- * won't retrieve a {@link PlcConsumerRegistration} which is useful to cancel registrations.
- *
- * @param name alias of the tag.
- * @param preRegisteredConsumer {@link Consumer<PlcSubscriptionEvent>} to be attached
- * @return builder.
- */
- PlcSubscriptionRequest.Builder addPreRegisteredConsumer(String name, Consumer<PlcSubscriptionEvent> preRegisteredConsumer);
-
  }
 
 }

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

@@ -18,26 +18,25 @@
  */
 package org.apache.plc4x.java.api.messages;
 
-import org.apache.plc4x.java.api.model.PlcSubscriptionHandle;
+import org.apache.plc4x.java.api.model.PlcSubscriptionTag;
+import org.apache.plc4x.java.api.types.PlcResponseCode;
 
 import java.util.Collection;
+import java.util.function.Consumer;
 
-public interface PlcSubscriptionResponse extends PlcSubscriptionTagResponse {
+public interface PlcSubscriptionResponse extends PlcResponse {
 
  @Override
  PlcSubscriptionRequest getRequest();
 
- /**
- * Returns a {@link PlcSubscriptionHandle} associated with a {@code name} from {@link PlcSubscriptionRequest#getTag(String)}
- *
- * @param name the tag name which a {@link PlcSubscriptionHandle} is required to
- * @return a {@link PlcSubscriptionHandle}
- */
- PlcSubscriptionHandle getSubscriptionHandle(String name);
-
- /**
- * @return all {@link PlcSubscriptionHandle}s
- */
- Collection<PlcSubscriptionHandle> getSubscriptionHandles();
+ PlcUnsubscriptionRequest getUnsubscriptionRequest();
+
+ Collection<String> getTagNames();
+
+ PlcSubscriptionTag getTag(String name);
+
+ PlcResponseCode getResponseCode(String name);
+
+ void registerConsumer(Consumer<PlcSubscriptionEvent> subscriptionConsumer);
 
 }

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

@@ -18,45 +18,11 @@
  */
 package org.apache.plc4x.java.api.messages;
 
-import org.apache.plc4x.java.api.model.PlcSubscriptionHandle;
-
-import java.util.Collection;
-import java.util.List;
 import java.util.concurrent.CompletableFuture;
 
 public interface PlcUnsubscriptionRequest extends PlcRequest {
 
- List<PlcSubscriptionHandle> getSubscriptionHandles();
-
  @Override
  CompletableFuture<PlcUnsubscriptionResponse> execute();
 
- interface Builder extends PlcRequestBuilder {
-
- @Override
- PlcUnsubscriptionRequest build();
-
- /**
- * {@link PlcSubscriptionHandle} that should be removed from the subscription
- *
- * @param plcSubscriptionHandle {@link PlcSubscriptionHandle} to be removed
- */
- PlcUnsubscriptionRequest.Builder addHandles(PlcSubscriptionHandle plcSubscriptionHandle);
-
- /**
- * {@link PlcSubscriptionHandle}s that should be removed from the subscription
- *
- * @param plcSubscriptionHandle1 {@link PlcSubscriptionHandle} to be removed
- * @param plcSubscriptionHandles {@link PlcSubscriptionHandle} to be removed
- */
- PlcUnsubscriptionRequest.Builder addHandles(PlcSubscriptionHandle plcSubscriptionHandle1, PlcSubscriptionHandle... plcSubscriptionHandles);
-
- /**
- * {@link PlcSubscriptionHandle}s that should be removed from the subscription
- *
- * @param plcSubscriptionHandle {@link PlcSubscriptionHandle} to be removed
- */
- PlcUnsubscriptionRequest.Builder addHandles(Collection<PlcSubscriptionHandle> plcSubscriptionHandle);
- }
-
 }

plc4j/api/src/main/java/org/apache/plc4x/java/api/model/PlcSubscriptionHandle.java → plc4j/api/src/main/java/org/apache/plc4x/java/api/model/PlcPublicationHandle.java

@@ -18,27 +18,26 @@
  */
 package org.apache.plc4x.java.api.model;
 
+import org.apache.plc4x.java.api.messages.PlcPublicationEventRequest;
+import org.apache.plc4x.java.api.messages.PlcPublicationEventResponse;
 import org.apache.plc4x.java.api.messages.PlcSubscriptionEvent;
 
 import java.util.function.Consumer;
 
 /**
- * When subscribing to remote resources, depending on the used protocol
- * different data is used to identify a subscription. This interface is
+ * When publishing data to remote resources, depending on the used protocol
+ * different data is used to identify a publication. This interface is
  * to be implemented in the individual Driver implementations to contain
- * all information needed to pull or unsubscribe any form of subscription.
- * <p>
- * For every subscribed item, a separate {@link PlcSubscriptionHandle} object is
- * returned in order to allow fine granular un-subscriptions.
+ * all information needed to publish data or to unsubscribe any form of publication.
  */
-public interface PlcSubscriptionHandle {
+public interface PlcPublicationHandle {
 
  /**
- * Registers a given consumer for the events emitted by the current subscription handle.
+ * Allows publishing events to the registered consumer..
  *
- * @param consumer consumer
- * @return consumer registration
+ * @param publicationEvent publication event containing the data we want to publish.
+ * @return PlcPublicationEventResponse response of the publication.
  */
- PlcConsumerRegistration register(Consumer<PlcSubscriptionEvent> consumer);
+ PlcPublicationEventResponse publish(PlcPublicationEventRequest publicationEvent);
 
 }