git.basschouten.com Git - openhab-addons.git/blob

   1 /**
   2  * Copyright (c) 2010-2023 Contributors to the openHAB project
   3  *
   4  * See the NOTICE file(s) distributed with this work for additional
   5  * information.
   6  *
   7  * This program and the accompanying materials are made available under the
   8  * terms of the Eclipse Public License 2.0 which is available at
   9  * http://www.eclipse.org/legal/epl-2.0
  10  *
  11  * SPDX-License-Identifier: EPL-2.0
  12  */
  13 package org.openhab.binding.deutschebahn.internal.timetable;
  14
  15 import java.io.IOException;
  16 import java.util.Date;
  17
  18 import org.eclipse.jdt.annotation.NonNullByDefault;
  19 import org.openhab.binding.deutschebahn.internal.timetable.dto.Timetable;
  20
  21 /**
  22  * Interface for timetables API in V1.
  23  *
  24  * @see <a href="https://developers.deutschebahn.com/db-api-marketplace/apis/product/timetables">DB API Marketplace</a>
  25  *
  26  * @author Sönke Küper - initial contribution
  27  */
  28 @NonNullByDefault
  29 public interface TimetablesV1Api {
  30
  31     /**
  32      * Requests the timetable with the planned data for the given station and time.
  33      * Calls the "/plan" endpoint of the rest-service.
  34      *
  35      * REST-endpoint documentation: (from
  36      * {@see https://developers.deutschebahn.com/db-api-marketplace/apis/product/timetables}).
  37      * Returns a Timetable object (see Timetable) that contains planned data for the specified station (evaNo)
  38      * within the hourly time slice given by date (format YYMMDD) and hour (format HH). The data includes stops
  39      * for all trips that arrive or depart within that slice. There is a small overlap between slices since some
  40      * trips arrive in one slice and depart in another.
  41      *
  42      * Planned data does never contain messages. On event level, planned data contains the 'plannned' attributes pt, pp,
  43      * ps and ppth
  44      * while the 'changed' attributes ct, cp, cs and cpth are absent.
  45      *
  46      * Planned data is generated many hours in advance and is static, i.e. it does never change.
  47      * It should be cached by web caches.public interface allows access to information about a station.
  48      *
  49      * @param evaNo The Station EVA-number.
  50      * @param time The time for which the timetable is requested. It will be requested for the given day and hour.
  51      *
  52      * @return The {@link Timetable} containing the planned arrivals and departues.
  53      */
  54     public abstract Timetable getPlan(String evaNo, Date time) throws IOException;
  55
  56     /**
  57      * Requests all known changes in the timetable for the given station.
  58      * Calls the "/fchg" endpoint of the rest-service.
  59      *
  60      * REST-endpoint documentation: (from
  61      * {@see https://developers.deutschebahn.com/db-api-marketplace/apis/product/timetables}).
  62      * Returns a Timetable object (see Timetable) that contains all known changes for the station given by evaNo.
  63      *
  64      * The data includes all known changes from now on until undefinitely into the future. Once changes become obsolete
  65      * (because their trip departs from the station) they are removed from this resource.
  66      *
  67      * Changes may include messages. On event level, they usually contain one or more of the 'changed' attributes ct,
  68      * cp, cs or cpth.
  69      * Changes may also include 'planned' attributes if there is no associated planned data for the change (e.g. an
  70      * unplanned stop or trip).
  71      *
  72      * Full changes are updated every 30s and should be cached for that period by web caches.
  73      *
  74      * @param evaNo The Station EVA-number.
  75      *
  76      * @return The {@link Timetable} containing all known changes for the given station.
  77      */
  78     public abstract Timetable getFullChanges(String evaNo) throws IOException;
  79
  80     /**
  81      * Requests the timetable with the planned data for the given station and time.
  82      * Calls the "/plan" endpoint of the rest-service.
  83      *
  84      * REST-endpoint documentation: (from
  85      * {@see https://developers.deutschebahn.com/db-api-marketplace/apis/product/timetables}).
  86      * Returns a Timetable object (see Timetable) that contains all recent changes for the station given by evaNo.
  87      * Recent changes are always a subset of the full changes. They may equal full changes but are typically much
  88      * smaller.
  89      * Data includes only those changes that became known within the last 2 minutes.
  90      *
  91      * A client that updates its state in intervals of less than 2 minutes should load full changes initially and then
  92      * proceed to periodically load only the recent changes in order to save bandwidth.
  93      *
  94      * Recent changes are updated every 30s as well and should be cached for that period by web caches.
  95      *
  96      * @param evaNo The Station EVA-number.
  97      *
  98      * @return The {@link Timetable} containing recent changes (from last two minutes) for the given station.
  99      */
 100     public abstract Timetable getRecentChanges(String evaNo) throws IOException;
 101 }