[Ephemeris] Binding to make the bridge with core Ephemeris functions (o…

…penhab#16628)

* [ephemeris] Initial commit of the ephemeris binding

Signed-off-by: gael@lhopital.org <gael@lhopital.org>
Signed-off-by: Paul Smedley <paul@smedley.id.au>

CODEOWNERS

@@ -102,6 +102,7 @@
 /bundles/org.openhab.binding.enocean/ @fruggy83
 /bundles/org.openhab.binding.enphase/ @Hilbrand
 /bundles/org.openhab.binding.enturno/ @klocsson
+/bundles/org.openhab.binding.ephemeris/ @clinique
 /bundles/org.openhab.binding.epsonprojector/ @mlobstein
 /bundles/org.openhab.binding.etherrain/ @dfad1469
 /bundles/org.openhab.binding.evcc/ @florian-h05

bom/openhab-addons/pom.xml

@@ -501,6 +501,11 @@
       <artifactId>org.openhab.binding.enturno</artifactId>
       <version>${project.version}</version>
     </dependency>
+    <dependency>
+      <groupId>org.openhab.addons.bundles</groupId>
+      <artifactId>org.openhab.binding.ephemeris</artifactId>
+      <version>${project.version}</version>
+    </dependency>
     <dependency>
       <groupId>org.openhab.addons.bundles</groupId>
       <artifactId>org.openhab.binding.epsonprojector</artifactId>

bundles/org.openhab.binding.ephemeris/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.ephemeris/README.md

@@ -0,0 +1,105 @@
+# Ephemeris Binding
+
+The Ephemeris Binding makes the bridge with Ephemeris core actions.
+It provides access to Ephemeris data via Items without requiring usage of a scripting language.
+
+The binding will search your Jollyday event definition files in the sub folder `/misc/ephemeris` located in the configuration folder of openHAB (e.g. for a linux system : /etc/openhab/misc/ephemeris/)
+
+## Supported Things
+
+The binding handles the following Things:
+
+* default holiday data (`holiday`)
+* custom holiday file (`custom`)
+* daysets (`dayset`)
+* weekend (`weekend`)
+
+## Discovery
+
+The binding discovers `weekend` and `holiday` things.
+
+## Binding Configuration
+
+There is no configuration at binding level.
+
+## Thing Configuration
+
+
+### `custom` Thing Configuration
+
+| Name            | Type    | Description                                       | Default | Required | Advanced |
+|-----------------|---------|---------------------------------------------------|---------|----------|----------|
+| fileName        | text    | Name of the XML file in the configuration folder  | N/A     | yes      | no       |
+
+The file has to use the syntax described here : https://www.openhab.org/docs/configuration/actions.html#custom-bank-holidays
+
+### `dayset` Thing Configuration
+
+| Name            | Type    | Description               | Default | Required | Advanced |
+|-----------------|---------|---------------------------|---------|----------|----------|
+| name            | text    | Name of the dayset used   | N/A     | yes      | no       |
+
+
+## Channels
+
+### `weekend` Channels
+
+| Name     | Type   | Description                                                   |
+|----------|--------|---------------------------------------------------------------|
+| today    | Switch | Set to ON if today is a weekend day, OFF in the other case    |
+| tomorrow | Switch | Set to ON if tomorrow is a weekend day, OFF in the other case |
+
+### `dayset` Channels
+
+| Name     | Type   | Description                                                         |
+|----------|--------|---------------------------------------------------------------------|
+| today    | Switch | Set to ON if today is in the given dayset, OFF in the other case    |
+| tomorrow | Switch | Set to ON if tomorrow is in the given dayset, OFF in the other case |
+
+### `holiday` Channels
+
+| Name             | Type        | Description                                    |
+|------------------|-------------|------------------------------------------------|
+| title-today      | String      | Name of today's holiday if any, NULL otherwise |
+| holiday-today    | Switch      | Set to ON if today is a holiday                |
+| holiday-tomorrow | Switch      | Set to ON if tomorrow is a holiday             |
+| next-title       | String      | Name of the next coming holiday                |
+| next-start       | DateTime    | Start date of the next coming holiday          |
+| days-remaining   | Number:Time | Remaining days until next holiday              |
+
+### `custom` Channels
+
+| Name           | Type        | Description                            |
+|----------------|-------------|----------------------------------------|
+| title-today    | String      | Title of the currently present event   |
+| event-today    | Switch      | Set to ON if an event exists today     |
+| event-tomorrow | Switch      | Set to ON if an event exists tomorrow  |
+| next-title     | String      | Title of the next starting event       |
+| next-start     | DateTime    | Start date of the next coming event    |
+| days-remaining | Number:Time | Remaining days until next event        |
+
+## Full Example
+
+### Thing Configuration
+
+```java
+Thing ephemeris:holiday:local "Holidays"
+Thing ephemeris:weekend:local "Week-end"
+Thing ephemeris:custom:events "Event" [fileName="events.xml"]
+```
+
+### Item Configuration
+
+```java
+String         ToD_Event_Current          "Event Today"       <calendar>    (gEvents)                           {channel="ephemeris:custom:events:title-today"}
+String         ToD_Event_Next          "Event Next"       <calendar>    (gEvents)                           {channel="ephemeris:custom:events:next-title"}
+Number:Time    ToD_Event_Next_Left       "Event In"          <calendar>    (gEvents)       ["Measurement","Duration"]    {channel="ephemeris:custom:events:days-remaining", unit="day"}
+
+Switch         ToD_Week_End_Current           "Week-End"                <calendar>    (gWeekEnd)                               {channel="ephemeris:weekend:local:today"}
+Switch         ToD_Week_End_Tomorrow           "Week-End Tomorrow"         <calendar>    (gWeekEnd)                               {channel="ephemeris:weekend:local:tomorrow"}
+
+String         ToD_Holiday_Current              "Holiday Today"       <calendar>    (gHoliday)                                 {channel="ephemeris:holiday:local:title-today"}
+String         ToD_Holiday_Next              "Holiday Next"           <calendar>    (gHoliday)                                 {channel="ephemeris:holiday:local:next-title"}
+Number:Time    ToD_Holiday_Next_Left           "Holiday In"              <calendar>    (gHoliday)            ["Measurement","Duration"]    {channel="ephemeris:holiday:local:days-remaining", unit="day"}
+
+```

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

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://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>4.2.0-SNAPSHOT</version>
+  </parent>
+
+  <artifactId>org.openhab.binding.ephemeris</artifactId>
+
+  <name>openHAB Add-ons :: Bundles :: Ephemeris Binding</name>
+
+</project>

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

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<features name="org.openhab.binding.ephemeris-${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-ephemeris" description="Ephemeris Binding" version="${project.version}">
+		<feature>openhab-runtime-base</feature>
+		<bundle start-level="80">mvn:org.openhab.addons.bundles/org.openhab.binding.ephemeris/${project.version}</bundle>
+	</feature>
+</features>

bundles/org.openhab.binding.ephemeris/src/main/java/org/openhab/binding/ephemeris/internal/EphemerisBindingConstants.java

@@ -0,0 +1,53 @@
+/**
+ * Copyright (c) 2010-2024 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.ephemeris.internal;
+
+import java.io.File;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.openhab.core.OpenHAB;
+import org.openhab.core.thing.ThingTypeUID;
+
+/**
+ * The {@link EphemerisBindingConstants} class defines common constants, which are
+ * used across the whole binding.
+ *
+ * @author Gaël L'hopital - Initial contribution
+ */
+@NonNullByDefault
+public class EphemerisBindingConstants {
+
+    public static final String BINDING_ID = "ephemeris";
+
+    // List of all Thing Type UIDs
+    public static final ThingTypeUID THING_TYPE_CUSTOM = new ThingTypeUID(BINDING_ID, "custom");
+    public static final ThingTypeUID THING_TYPE_HOLIDAY = new ThingTypeUID(BINDING_ID, "holiday");
+    public static final ThingTypeUID THING_TYPE_DAYSET = new ThingTypeUID(BINDING_ID, "dayset");
+    public static final ThingTypeUID THING_TYPE_WEEKEND = new ThingTypeUID(BINDING_ID, "weekend");
+
+    // List of all Channel ids
+    public static final String CHANNEL_CURRENT_EVENT = "title-today";
+    public static final String CHANNEL_NEXT_EVENT = "next-title";
+    public static final String CHANNEL_NEXT_START = "next-start";
+    public static final String CHANNEL_NEXT_REMAINING = "days-remaining";
+    public static final String CHANNEL_TODAY = "today";
+    public static final String CHANNEL_TOMORROW = "tomorrow";
+    public static final String CHANNEL_HOLIDAY_TODAY = "holiday-today";
+    public static final String CHANNEL_HOLIDAY_TOMORROW = "holiday-tomorrow";
+    public static final String CHANNEL_EVENT_TODAY = "event-today";
+    public static final String CHANNEL_EVENT_TOMORROW = "event-tomorrow";
+
+    // Folder for xml storage eg: /etc/openhab/misc/ephemeris
+    public static final String BINDING_DATA_PATH = "%s%smisc%s%s".formatted(OpenHAB.getConfigFolder(), File.separator,
+            File.separator, BINDING_ID);
+}

bundles/org.openhab.binding.ephemeris/src/main/java/org/openhab/binding/ephemeris/internal/EphemerisException.java

@@ -0,0 +1,36 @@
+/**
+ * Copyright (c) 2010-2024 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.ephemeris.internal;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.openhab.core.thing.ThingStatusDetail;
+
+/**
+ * Exception raised by Ephemeris Handlers
+ *
+ * @author Gaël L'hopital - Initial contribution
+ */
+@NonNullByDefault
+public class EphemerisException extends Exception {
+    private static final long serialVersionUID = -8813754360966576513L;
+    private final ThingStatusDetail statusDetail;
+
+    public EphemerisException(String message, ThingStatusDetail statusDetail) {
+        super(message);
+        this.statusDetail = statusDetail;
+    }
+
+    public ThingStatusDetail getStatusDetail() {
+        return statusDetail;
+    }
+}

bundles/org.openhab.binding.ephemeris/src/main/java/org/openhab/binding/ephemeris/internal/EphemerisHandlerFactory.java

@@ -0,0 +1,93 @@
+/**
+ * Copyright (c) 2010-2024 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.ephemeris.internal;
+
+import static org.openhab.binding.ephemeris.internal.EphemerisBindingConstants.*;
+
+import java.io.File;
+import java.time.ZoneId;
+import java.util.Set;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.eclipse.jdt.annotation.Nullable;
+import org.openhab.binding.ephemeris.internal.handler.CustomHandler;
+import org.openhab.binding.ephemeris.internal.handler.DaysetHandler;
+import org.openhab.binding.ephemeris.internal.handler.HolidayHandler;
+import org.openhab.binding.ephemeris.internal.handler.WeekendHandler;
+import org.openhab.binding.ephemeris.internal.providers.EphemerisDescriptionProvider;
+import org.openhab.core.ephemeris.EphemerisManager;
+import org.openhab.core.i18n.TimeZoneProvider;
+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.Activate;
+import org.osgi.service.component.annotations.Component;
+import org.osgi.service.component.annotations.Reference;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+/**
+ * The {@link EphemerisHandlerFactory} is responsible for creating things and thing
+ * handlers.
+ *
+ * @author Gaël L'hopital - Initial contribution
+ */
+@NonNullByDefault
+@Component(configurationPid = "binding.ephemeris", service = ThingHandlerFactory.class)
+public class EphemerisHandlerFactory extends BaseThingHandlerFactory {
+    private static final Set<ThingTypeUID> SUPPORTED_THING_TYPES_UIDS = Set.of(THING_TYPE_CUSTOM, THING_TYPE_HOLIDAY,
+            THING_TYPE_DAYSET, THING_TYPE_WEEKEND);
+
+    private final Logger logger = LoggerFactory.getLogger(EphemerisHandlerFactory.class);
+    private final EphemerisManager ephemerisManager;
+    private final ZoneId zoneId;
+    private final EphemerisDescriptionProvider descriptionProvider;
+
+    @Activate
+    public EphemerisHandlerFactory(final @Reference EphemerisManager ephemerisManager,
+            final @Reference TimeZoneProvider timeZoneProvider,
+            final @Reference EphemerisDescriptionProvider descriptionProvider) {
+        this.ephemerisManager = ephemerisManager;
+        this.zoneId = timeZoneProvider.getTimeZone();
+        this.descriptionProvider = descriptionProvider;
+        File folder = new File(BINDING_DATA_PATH);
+        if (!folder.exists()) {
+            logger.info("Please, create the folder '{}' to store your custom Jollyday definition files.",
+                    BINDING_DATA_PATH);
+        }
+    }
+
+    @Override
+    public boolean supportsThingType(ThingTypeUID thingTypeUID) {
+        return SUPPORTED_THING_TYPES_UIDS.contains(thingTypeUID);
+    }
+
+    @Override
+    protected @Nullable ThingHandler createHandler(Thing thing) {
+        ThingTypeUID thingTypeUID = thing.getThingTypeUID();
+
+        if (THING_TYPE_CUSTOM.equals(thingTypeUID)) {
+            return new CustomHandler(thing, ephemerisManager, zoneId);
+        } else if (THING_TYPE_HOLIDAY.equals(thingTypeUID)) {
+            return new HolidayHandler(thing, ephemerisManager, zoneId, descriptionProvider);
+        } else if (THING_TYPE_DAYSET.equals(thingTypeUID)) {
+            return new DaysetHandler(thing, ephemerisManager, zoneId);
+        } else if (THING_TYPE_WEEKEND.equals(thingTypeUID)) {
+            return new WeekendHandler(thing, ephemerisManager, zoneId);
+        }
+
+        return null;
+    }
+}

bundles/org.openhab.binding.ephemeris/src/main/java/org/openhab/binding/ephemeris/internal/configuration/DaysetConfiguration.java

@@ -0,0 +1,25 @@
+/**
+ * Copyright (c) 2010-2024 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.ephemeris.internal.configuration;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+
+/**
+ * The {@link DaysetConfiguration} class contains fields mapping Dayset Thing configuration parameters.
+ *
+ * @author Gaël L'hopital - Initial contribution
+ */
+@NonNullByDefault
+public class DaysetConfiguration {
+    public String name = "";
+}