This is an automated email from the ASF dual-hosted git repository. cdutz pushed a commit to branch feature/publish-api in repository https://gitbox.apache.org/repos/asf/plc4x.git
commit 6e9b727b033ef634ef866bca664e39cc1a93ccb2 Author: Christofer Dutz <[email protected]> AuthorDate: Sun Jul 23 13:36:45 2023 +0200 feat: First draft of a publication API (Still needs some fine-tuning) --- .../api/messages/PlcPublicationEventRequest.java | 30 ++++++++ .../api/messages/PlcPublicationEventResponse.java | 23 ++++++ .../java/api/messages/PlcPublicationRequest.java | 85 ++++++++++++++++++++++ .../java/api/messages/PlcPublicationResponse.java | 44 +++++++++++ .../api/messages/PlcPublicationTagRequest.java | 41 +++++++++++ .../api/messages/PlcPublicationTagResponse.java | 42 +++++++++++ .../plc4x/java/api/model/PlcPublicationHandle.java | 43 +++++++++++ .../plc4x/java/api/model/PlcPublicationTag.java | 24 ++++++ 8 files changed, 332 insertions(+) diff --git a/plc4j/api/src/main/java/org/apache/plc4x/java/api/messages/PlcPublicationEventRequest.java b/plc4j/api/src/main/java/org/apache/plc4x/java/api/messages/PlcPublicationEventRequest.java new file mode 100644 index 0000000000..5f9fb1e1dc --- /dev/null +++ b/plc4j/api/src/main/java/org/apache/plc4x/java/api/messages/PlcPublicationEventRequest.java @@ -0,0 +1,30 @@ +/* + * 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 java.time.Instant; + +public interface PlcPublicationEventRequest extends PlcWriteRequest { + + /** + * @return the timestamp at which this event occurred. + */ + Instant getTimestamp(); + +} diff --git a/plc4j/api/src/main/java/org/apache/plc4x/java/api/messages/PlcPublicationEventResponse.java b/plc4j/api/src/main/java/org/apache/plc4x/java/api/messages/PlcPublicationEventResponse.java new file mode 100644 index 0000000000..536c3c4f92 --- /dev/null +++ b/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 { + +} diff --git a/plc4j/api/src/main/java/org/apache/plc4x/java/api/messages/PlcPublicationRequest.java b/plc4j/api/src/main/java/org/apache/plc4x/java/api/messages/PlcPublicationRequest.java new file mode 100644 index 0000000000..218de9898d --- /dev/null +++ b/plc4j/api/src/main/java/org/apache/plc4x/java/api/messages/PlcPublicationRequest.java @@ -0,0 +1,85 @@ +/* + * 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.PlcTag; +import org.apache.plc4x.java.api.value.PlcValue; + +import java.time.Duration; +import java.util.concurrent.CompletableFuture; + +public interface PlcPublicationRequest extends PlcPublicationTagRequest { + + @Override + CompletableFuture<? extends PlcPublicationResponse> execute(); + + 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); + + } + +} diff --git a/plc4j/api/src/main/java/org/apache/plc4x/java/api/messages/PlcPublicationResponse.java b/plc4j/api/src/main/java/org/apache/plc4x/java/api/messages/PlcPublicationResponse.java new file mode 100644 index 0000000000..e45bdf459b --- /dev/null +++ b/plc4j/api/src/main/java/org/apache/plc4x/java/api/messages/PlcPublicationResponse.java @@ -0,0 +1,44 @@ +/* + * 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.PlcPublicationHandle; +import org.apache.plc4x.java.api.model.PlcSubscriptionHandle; + +import java.util.Collection; + +public interface PlcPublicationResponse extends PlcPublicationTagResponse { + + @Override + PlcPublicationRequest getRequest(); + + /** + * Returns a {@link PlcPublicationHandle} associated with a {@code name} from {@link PlcPublicationRequest#getTag(String)} + * + * @param name the tag name which a {@link PlcPublicationHandle} is required to + * @return a {@link PlcPublicationHandle} + */ + PlcPublicationHandle getPublicationHandle(String name); + + /** + * @return all {@link PlcPublicationHandle}s + */ + Collection<PlcPublicationHandle> getPublicationHandles(); + +} diff --git a/plc4j/api/src/main/java/org/apache/plc4x/java/api/messages/PlcPublicationTagRequest.java b/plc4j/api/src/main/java/org/apache/plc4x/java/api/messages/PlcPublicationTagRequest.java new file mode 100644 index 0000000000..d7eb06f6ea --- /dev/null +++ b/plc4j/api/src/main/java/org/apache/plc4x/java/api/messages/PlcPublicationTagRequest.java @@ -0,0 +1,41 @@ +/* + * 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.PlcSubscriptionTag; + +import java.util.LinkedHashSet; +import java.util.List; +import java.util.concurrent.CompletableFuture; + +public interface PlcPublicationTagRequest extends PlcRequest { + + @Override + CompletableFuture<? extends PlcPublicationTagResponse> execute(); + + int getNumberOfTags(); + + LinkedHashSet<String> getTagNames(); + + PlcPublicationTag getTag(String name); + + List<PlcPublicationTag> getTags(); + +} diff --git a/plc4j/api/src/main/java/org/apache/plc4x/java/api/messages/PlcPublicationTagResponse.java b/plc4j/api/src/main/java/org/apache/plc4x/java/api/messages/PlcPublicationTagResponse.java new file mode 100644 index 0000000000..7bdf79d89a --- /dev/null +++ b/plc4j/api/src/main/java/org/apache/plc4x/java/api/messages/PlcPublicationTagResponse.java @@ -0,0 +1,42 @@ +/* + * 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.PlcSubscriptionTag; +import org.apache.plc4x.java.api.types.PlcResponseCode; + +import java.util.Collection; + +/** + * Base type for all publication response messages sent as response for a prior publication request + * from the plc4x-system to a remote system (PLC). + */ +public interface PlcPublicationTagResponse extends PlcResponse { + + @Override + PlcPublicationTagRequest getRequest(); + + Collection<String> getTagNames(); + + PlcPublicationTag getTag(String name); + + PlcResponseCode getResponseCode(String name); + +} diff --git a/plc4j/api/src/main/java/org/apache/plc4x/java/api/model/PlcPublicationHandle.java b/plc4j/api/src/main/java/org/apache/plc4x/java/api/model/PlcPublicationHandle.java new file mode 100644 index 0000000000..c17e72b33e --- /dev/null +++ b/plc4j/api/src/main/java/org/apache/plc4x/java/api/model/PlcPublicationHandle.java @@ -0,0 +1,43 @@ +/* + * 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.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 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 publish data or to unsubscribe any form of publication. + */ +public interface PlcPublicationHandle { + + /** + * Allows publishing events to the registered consumer.. + * + * @param publicationEvent publication event containing the data we want to publish. + * @return PlcPublicationEventResponse response of the publication. + */ + PlcPublicationEventResponse publish(PlcPublicationEventRequest publicationEvent); + +} diff --git a/plc4j/api/src/main/java/org/apache/plc4x/java/api/model/PlcPublicationTag.java b/plc4j/api/src/main/java/org/apache/plc4x/java/api/model/PlcPublicationTag.java new file mode 100644 index 0000000000..192295ed8b --- /dev/null +++ b/plc4j/api/src/main/java/org/apache/plc4x/java/api/model/PlcPublicationTag.java @@ -0,0 +1,24 @@ +/* + * 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.model; + + +public interface PlcPublicationTag extends PlcTag { + +}
