[deutschebahn] Initial contribution: New binding for DeutscheBahn Fah…

…rplan (openhab#11384)

* Created binding for DeutscheBahn Timetable API.

Signed-off-by: Sönke Küper <soenkekueper@gmx.de>

* Disabled schema validation and used original schema. Added tests for hannover hbf which has non schema conforming responses.

Signed-off-by: Sönke Küper <soenkekueper@gmx.de>

* Added information about UNDEF and NULL channel values.

Signed-off-by: Sönke Küper <soenkekueper@gmx.de>

* Added sample widget and screenshot

Signed-off-by: Sönke Küper <soenkekueper@gmx.de>

* Filtering duplicate messages

Signed-off-by: Sönke Küper <soenkekueper@gmx.de>

* Fixed some typos.

Signed-off-by: Sönke Küper <soenkekueper@gmx.de>

* Updated to jUnit5

Signed-off-by: Sönke Küper <soenkekueper@gmx.de>

* Applied review remarks in Readme

Signed-off-by: Sönke Küper <soenkekueper@gmx.de>

* Applied some review remarks

Signed-off-by: Sönke Küper <soenkekueper@gmx.de>

* 0000: Fixed compile warnings

Signed-off-by: Sönke Küper <soenkekueper@gmx.de>

Co-authored-by: Sönke Küper <soenkekueper@gmx.de>

CODEOWNERS

@@ -64,6 +64,7 @@
 /bundles/org.openhab.binding.dbquery/ @lujop
 /bundles/org.openhab.binding.deconz/ @openhab/add-ons-maintainers
 /bundles/org.openhab.binding.denonmarantz/ @jwveldhuis
+/bundles/org.openhab.binding.deutschebahn/ @soenkekueper
 /bundles/org.openhab.binding.digiplex/ @rmichalak
 /bundles/org.openhab.binding.digitalstrom/ @MichaelOchel @msiegele
 /bundles/org.openhab.binding.dlinksmarthome/ @MikeJMajor

bom/openhab-addons/pom.xml

@@ -311,6 +311,11 @@
       <artifactId>org.openhab.binding.denonmarantz</artifactId>
       <version>${project.version}</version>
     </dependency>
+    <dependency>
+      <groupId>org.openhab.addons.bundles</groupId>
+      <artifactId>org.openhab.binding.deutschebahn</artifactId>
+      <version>${project.version}</version>
+    </dependency>
     <dependency>
       <groupId>org.openhab.addons.bundles</groupId>
       <artifactId>org.openhab.binding.digiplex</artifactId>

bundles/org.openhab.binding.deutschebahn/NOTICE

@@ -0,0 +1,13 @@
+This content is produced and maintained by the openHAB project.
+
+* Project home: https://www.openhab.org
+
+== Declared Project Licenses
+
+This program and the accompanying materials are made available under the terms
+of the Eclipse Public License 2.0 which is available at
+https://www.eclipse.org/legal/epl-2.0/.
+
+== Source Code
+
+https://github.com/openhab/openhab-addons

bundles/org.openhab.binding.deutschebahn/pom.xml

@@ -0,0 +1,54 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://maven.apache.org/POM/4.0.0"
+  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+
+  <modelVersion>4.0.0</modelVersion>
+
+  <parent>
+    <groupId>org.openhab.addons.bundles</groupId>
+    <artifactId>org.openhab.addons.reactor.bundles</artifactId>
+    <version>3.2.0-SNAPSHOT</version>
+  </parent>
+
+  <artifactId>org.openhab.binding.deutschebahn</artifactId>
+
+  <name>openHAB Add-ons :: Bundles :: Deutsche Bahn Binding</name>
+
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>org.jvnet.jaxb2.maven2</groupId>
+        <artifactId>maven-jaxb2-plugin</artifactId>
+        <version>0.14.0</version>
+        <executions>
+          <execution>
+            <id>generate-jaxb-sources</id>
+            <goals>
+              <goal>generate</goal>
+            </goals>
+          </execution>
+        </executions>
+        <configuration>
+          <generatePackage>org.openhab.binding.deutschebahn.internal.timetable.dto</generatePackage>
+          <schemaDirectory>src/main/resources/xsd</schemaDirectory>
+          <noFileHeader>true</noFileHeader>
+          <locale>en</locale>
+          <episode>false</episode>
+          <extension>true</extension>
+          <args>
+            <arg>-Xxew</arg>
+            <arg>-Xxew:instantiate early</arg>
+          </args>
+          <plugins>
+            <plugin>
+              <groupId>com.github.jaxb-xew-plugin</groupId>
+              <artifactId>jaxb-xew-plugin</artifactId>
+              <version>1.10</version>
+            </plugin>
+          </plugins>
+        </configuration>
+      </plugin>
+    </plugins>
+  </build>
+
+</project>

bundles/org.openhab.binding.deutschebahn/src/main/feature/feature.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<features name="org.openhab.binding.deutschebahn-${project.version}" xmlns="http://karaf.apache.org/xmlns/features/v1.4.0">
+	<repository>mvn:org.openhab.core.features.karaf/org.openhab.core.features.karaf.openhab-core/${ohc.version}/xml/features</repository>
+
+	<feature name="openhab-binding-deutschebahn" description="DeutscheBahn Binding" version="${project.version}">
+		<feature>openhab-runtime-base</feature>
+		<bundle start-level="80">mvn:org.openhab.addons.bundles/org.openhab.binding.deutschebahn/${project.version}</bundle>
+	</feature>
+</features>

bundles/org.openhab.binding.deutschebahn/src/main/java/org/openhab/binding/deutschebahn/internal/AbstractDtoAttributeSelector.java

@@ -0,0 +1,101 @@
+/**
+ * Copyright (c) 2010-2021 Contributors to the openHAB project
+ *
+ * See the NOTICE file(s) distributed with this work for additional
+ * information.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ */
+package org.openhab.binding.deutschebahn.internal;
+
+import java.util.function.BiConsumer;
+import java.util.function.Function;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.eclipse.jdt.annotation.Nullable;
+import org.openhab.binding.deutschebahn.internal.timetable.dto.JaxbEntity;
+import org.openhab.core.types.State;
+
+/**
+ * Accessor for attribute value of an DTO-Object.
+ * 
+ * @author Sönke Küper - Initial contribution.
+ *
+ * @param <DTO_TYPE> type of value in Bean.
+ * @param <VALUE_TYPE> type of value in Bean.
+ * @param <STATE_TYPE> type of state.
+ */
+@NonNullByDefault
+public abstract class AbstractDtoAttributeSelector<DTO_TYPE extends JaxbEntity, @Nullable VALUE_TYPE, STATE_TYPE extends State> {
+
+    private final Function<DTO_TYPE, @Nullable VALUE_TYPE> getter;
+    private final BiConsumer<DTO_TYPE, VALUE_TYPE> setter;
+    private final Function<VALUE_TYPE, @Nullable STATE_TYPE> getState;
+    private final String channelTypeName;
+    private final Class<STATE_TYPE> stateType;
+
+    /**
+     * Creates an new {@link EventAttribute}.
+     *
+     * @param getter Function to get the raw value.
+     * @param setter Function to set the raw value.
+     * @param getState Function to get the Value as {@link State}.
+     */
+    protected AbstractDtoAttributeSelector(final String channelTypeName, //
+            final Function<DTO_TYPE, @Nullable VALUE_TYPE> getter, //
+            final BiConsumer<DTO_TYPE, VALUE_TYPE> setter, //
+            final Function<VALUE_TYPE, @Nullable STATE_TYPE> getState, //
+            final Class<STATE_TYPE> stateType) {
+        this.channelTypeName = channelTypeName;
+        this.getter = getter;
+        this.setter = setter;
+        this.getState = getState;
+        this.stateType = stateType;
+    }
+
+    /**
+     * Returns the type of the state value.
+     */
+    public final Class<STATE_TYPE> getStateType() {
+        return this.stateType;
+    }
+
+    /**
+     * Returns the name of the corresponding channel-type.
+     */
+    public final String getChannelTypeName() {
+        return this.channelTypeName;
+    }
+
+    /**
+     * Returns the {@link State} for the selected attribute from the given DTO object
+     * Returns <code>null</code> if the value is <code>null</code>.
+     */
+    @Nullable
+    public final STATE_TYPE getState(final DTO_TYPE object) {
+        final VALUE_TYPE value = this.getValue(object);
+        if (value == null) {
+            return null;
+        }
+        return this.getState.apply(value);
+    }
+
+    /**
+     * Returns the value for the selected attribute from the given DTO object.
+     */
+    @Nullable
+    public final VALUE_TYPE getValue(final DTO_TYPE object) {
+        return this.getter.apply(object);
+    }
+
+    /**
+     * Sets the value for the selected attribute in the given DTO object
+     */
+    public final void setValue(final DTO_TYPE event, final VALUE_TYPE object) {
+        this.setter.accept(event, object);
+    }
+}

bundles/org.openhab.binding.deutschebahn/src/main/java/org/openhab/binding/deutschebahn/internal/AttributeSelection.java

@@ -0,0 +1,33 @@
+/**
+ * Copyright (c) 2010-2021 Contributors to the openHAB project
+ *
+ * See the NOTICE file(s) distributed with this work for additional
+ * information.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ */
+package org.openhab.binding.deutschebahn.internal;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.eclipse.jdt.annotation.Nullable;
+import org.openhab.binding.deutschebahn.internal.timetable.dto.TimetableStop;
+import org.openhab.core.types.State;
+
+/**
+ * Selection of an attribute within an {@link TimetableStop} that provides a channel {@link State}.
+ * 
+ * @author Sönke Küper - Initial contribution
+ */
+@NonNullByDefault
+public interface AttributeSelection {
+
+    /**
+     * Returns the {@link State} that should be set for the channels'value for this attribute.
+     */
+    @Nullable
+    public abstract State getState(TimetableStop stop);
+}

bundles/org.openhab.binding.deutschebahn/src/main/java/org/openhab/binding/deutschebahn/internal/DeutscheBahnBindingConstants.java

@@ -0,0 +1,40 @@
+/**
+ * Copyright (c) 2010-2021 Contributors to the openHAB project
+ *
+ * See the NOTICE file(s) distributed with this work for additional
+ * information.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ */
+package org.openhab.binding.deutschebahn.internal;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.openhab.core.thing.ThingTypeUID;
+
+/**
+ * The {@link DeutscheBahnBindingConstants} class defines common constants, which are used across the whole binding.
+ *
+ * @author Sönke Küper - Initial contribution
+ */
+@NonNullByDefault
+public class DeutscheBahnBindingConstants {
+
+    /**
+     * Binding-ID.
+     */
+    public static final String BINDING_ID = "deutschebahn";
+
+    /**
+     * {@link ThingTypeUID} for Timetable-API Bridge.
+     */
+    public static final ThingTypeUID TIMETABLE_TYPE = new ThingTypeUID(BINDING_ID, "timetable");
+
+    /**
+     * {@link ThingTypeUID} for Train.
+     */
+    public static final ThingTypeUID TRAIN_TYPE = new ThingTypeUID(BINDING_ID, "train");
+}

bundles/org.openhab.binding.deutschebahn/src/main/java/org/openhab/binding/deutschebahn/internal/DeutscheBahnHandlerFactory.java

@@ -0,0 +1,60 @@
+/**
+ * Copyright (c) 2010-2021 Contributors to the openHAB project
+ *
+ * See the NOTICE file(s) distributed with this work for additional
+ * information.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ */
+package org.openhab.binding.deutschebahn.internal;
+
+import static org.openhab.binding.deutschebahn.internal.DeutscheBahnBindingConstants.TIMETABLE_TYPE;
+import static org.openhab.binding.deutschebahn.internal.DeutscheBahnBindingConstants.TRAIN_TYPE;
+
+import java.util.Date;
+import java.util.Set;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.eclipse.jdt.annotation.Nullable;
+import org.openhab.binding.deutschebahn.internal.timetable.TimetablesV1Impl;
+import org.openhab.core.thing.Bridge;
+import org.openhab.core.thing.Thing;
+import org.openhab.core.thing.ThingTypeUID;
+import org.openhab.core.thing.binding.BaseThingHandlerFactory;
+import org.openhab.core.thing.binding.ThingHandler;
+import org.openhab.core.thing.binding.ThingHandlerFactory;
+import org.osgi.service.component.annotations.Component;
+
+/**
+ * The {@link DeutscheBahnHandlerFactory} is responsible for creating things and thing handlers.
+ *
+ * @author Sönke Küper - Initial contribution
+ */
+@NonNullByDefault
+@Component(configurationPid = "binding.deutschebahn", service = ThingHandlerFactory.class)
+public class DeutscheBahnHandlerFactory extends BaseThingHandlerFactory {
+
+    private static final Set<ThingTypeUID> SUPPORTED_THING_TYPES_UIDS = Set.of(TIMETABLE_TYPE, TRAIN_TYPE);
+
+    @Override
+    public boolean supportsThingType(final ThingTypeUID thingTypeUID) {
+        return SUPPORTED_THING_TYPES_UIDS.contains(thingTypeUID);
+    }
+
+    @Override
+    protected @Nullable ThingHandler createHandler(final Thing thing) {
+        final ThingTypeUID thingTypeUID = thing.getThingTypeUID();
+
+        if (TIMETABLE_TYPE.equals(thingTypeUID)) {
+            return new DeutscheBahnTimetableHandler((Bridge) thing, TimetablesV1Impl::new, Date::new);
+        } else if (TRAIN_TYPE.equals(thingTypeUID)) {
+            return new DeutscheBahnTrainHandler(thing);
+        }
+
+        return null;
+    }
+}

bundles/org.openhab.binding.deutschebahn/src/main/java/org/openhab/binding/deutschebahn/internal/DeutscheBahnTimetableConfiguration.java

@@ -0,0 +1,46 @@
+/**
+ * Copyright (c) 2010-2021 Contributors to the openHAB project
+ *
+ * See the NOTICE file(s) distributed with this work for additional
+ * information.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ */
+package org.openhab.binding.deutschebahn.internal;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+
+/**
+ * The {@link DeutscheBahnTimetableConfiguration} for the Timetable bridge-type.
+ *
+ * @author Sönke Küper - Initial contribution
+ */
+@NonNullByDefault
+public class DeutscheBahnTimetableConfiguration {
+
+    /**
+     * Access-Token.
+     */
+    public String accessToken = "";
+
+    /**
+     * evaNo of the station to be queried.
+     */
+    public String evaNo = "";
+
+    /**
+     * Filter for timetable stops.
+     */
+    public String trainFilter = "";
+
+    /**
+     * Returns the {@link TimetableStopFilter}.
+     */
+    public TimetableStopFilter getTimetableStopFilter() {
+        return TimetableStopFilter.valueOf(this.trainFilter.toUpperCase());
+    }
+}