JavaDoc++

src/main/java/de/stklcode/pubtrans/ura/UraClient.java

@@ -79,7 +79,14 @@ public class UraClient implements Serializable {
     private static final String[] REQUEST_MESSAGE = {PAR_STOP_NAME, PAR_STOP_ID, PAR_STOP_INDICATOR, PAR_STOP_STATE, PAR_GEOLOCATION,
             PAR_MSG_UUID, PAR_MSG_TYPE, PAR_MSG_PRIORITY, PAR_MSG_TEXT};
 
+    /**
+     * The client configuration.
+     */
     private final UraClientConfiguration config;
+
+    /**
+     * The JSON mapper.
+     */
     private final ObjectMapper mapper;
 
     /**

src/main/java/de/stklcode/pubtrans/ura/UraClientConfiguration.java

@@ -15,10 +15,29 @@ public class UraClientConfiguration implements Serializable {
     private static final String DEFAULT_INSTANT_PATH = "/interfaces/ura/instant_V1";
     private static final String DEFAULT_STREAM_PATH = "/interfaces/ura/stream_V1";
 
+    /**
+     * API base URL.
+     */
     private final String baseURL;
+
+    /**
+     * Path to instant API endpoint.
+     */
     private final String instantPath;
+
+    /**
+     * Path to stream API endpoint.
+     */
     private final String streamPath;
+
+    /**
+     * Optional connection timeout.
+     */
     private final Duration connectTimeout;
+
+    /**
+     * Optional read timeout.
+     */
     private final Duration timeout;
 
     /**

src/main/java/de/stklcode/pubtrans/ura/exception/package-info.java

@@ -0,0 +1,20 @@
+/*
+ * Copyright 2016-2021 Stefan Kalscheuer
+ *
+ * Licensed 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
+ *
+ * http://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.
+ */
+
+/**
+ * jURAclient exceptions thrown by the client.
+ */
+package de.stklcode.pubtrans.ura.exception;

src/main/java/de/stklcode/pubtrans/ura/model/Message.java

@@ -19,10 +19,29 @@ public class Message implements Model {
     private static final int MSG_TEXT = 10;
     private static final int NUM_OF_FIELDS = 11;
 
+    /**
+     * Corresponding stop.
+     */
     private final Stop stop;
+
+    /**
+     * Message UUID.
+     */
     private final String uuid;
+
+    /**
+     * Message type.
+     */
     private final Integer type;
+
+    /**
+     * Message priority.
+     */
     private final Integer priority;
+
+    /**
+     * Message text.
+     */
     private final String text;
 
     /**
@@ -132,6 +151,8 @@ public class Message implements Model {
     }
 
     /**
+     * The stop, the message is targeted.
+     *
      * @return The affected stop.
      */
     public Stop getStop() {
@@ -139,6 +160,8 @@ public class Message implements Model {
     }
 
     /**
+     * This is the unique identifier of the flexible message.
+     *
      * @return Message's unique identifier.
      */
     public String getUuid() {
@@ -146,6 +169,15 @@ public class Message implements Model {
     }
 
     /**
+     * Messages are assigned a type.
+     * This is predominantly in order to define how they should be displayed on on-street signs, however can be used to
+     * alter display on other devices.
+     * <ul>
+     * <li>0: “Normal”</li>
+     * <li>1: “Special”</li>
+     * <li>2: “Full Matrix” – Stop is temporarily out of service and predictions should not be presented</li>
+     * </ul>
+     *
      * @return Message type.
      */
     public Integer getType() {
@@ -153,13 +185,19 @@ public class Message implements Model {
     }
 
     /**
-     * @return Message priority. Lower value equals higher priority.
+     * Messages are assigned a priority in order for them to be ranked.
+     * Since it is possible for a stop to be assigned multiple messages it is important to ensure priority is given.
+     * Priorities are between 1 and 10 (where 1 is the highest priority). By default the message priority is set to 3.
+     *
+     * @return Message priority.
      */
     public Integer getPriority() {
         return priority;
     }
 
     /**
+     * The text of the message. This should be displayed to the public.
+     *
      * @return Message text.
      */
     public String getText() {

src/main/java/de/stklcode/pubtrans/ura/model/Stop.java

@@ -36,11 +36,34 @@ public final class Stop implements Model {
     private static final int F_LONGITUDE = 6;
     private static final int F_NUM_OF_FIELDS = 7;
 
+    /**
+     * Stop identifier.
+     */
     private final String id;
+
+    /**
+     * The name of the bus stop.
+     */
     private final String name;
+
+    /**
+     * The stop indicator.
+     */
     private final String indicator;
+
+    /**
+     * The stop state
+     */
     private final Integer state;
+
+    /**
+     * The stop geolocation latitude.
+     */
     private final Double latitude;
+
+    /**
+     * The stop geolocation longitude.
+     */
     private final Double longitude;
 
     /**
@@ -118,6 +141,8 @@ public final class Stop implements Model {
     }
 
     /**
+     * Stop identifier.
+     *
      * @return The stop ID.
      */
     public String getId() {
@@ -125,6 +150,8 @@ public final class Stop implements Model {
     }
 
     /**
+     * The name of the bus stop.
+     *
      * @return The stop name.
      */
     public String getName() {
@@ -132,6 +159,9 @@ public final class Stop implements Model {
     }
 
     /**
+     * The letter(s) that are displayed on top of the bus stop flag (e.g. SA).
+     * These are used to help passengers easily identify a bus stop from others in the locality.
+     *
      * @return The stop indicator.
      */
     public String getIndicator() {
@@ -139,13 +169,26 @@ public final class Stop implements Model {
     }
 
     /**
-     * @return The stop indicator.
+     * The different stop states and their definitions are provided below:
+     * <ul>
+     * <li>0: “Open”: Bus stop is being served as usual</li>
+     * <li>1: “Temporarily Closed” : Vehicles are not serving the stop but may be serving a nearby bus stop,
+     *                               predictions may be available</li>
+     * <li>2: “Closed” : Vehicles are not serving the stop.
+     *                   Stop should display the closed message and predictions should not be shown.</li>
+     * <li>3: “Suspended” : Vehicles are not serving the stop.
+     *                      Stop should display the closed message and predictions should not be shown.</li>
+     * </ul>
+     *
+     * @return The stop state.
      */
     public Integer getState() {
         return state;
     }
 
     /**
+     * The latitude of the stop. This is expressed using the WGS84 coordinate system.
+     *
      * @return The stop geolocation latitude.
      */
     public Double getLatitude() {
@@ -153,6 +196,8 @@ public final class Stop implements Model {
     }
 
     /**
+     * The longitude of the stop. This isexpressed using the WGS84 coordinate system.
+     *
      * @return The stop geolocation longitude.
      */
     public Double getLongitude() {

src/main/java/de/stklcode/pubtrans/ura/model/Trip.java

@@ -39,15 +39,54 @@ public final class Trip implements Model {
     private static final int ESTIMATED_TIME = 15;
     private static final int NUM_OF_FIELDS = 16;
 
+    /**
+     * The starting stop.
+     */
     private final Stop stop;
+
+    /**
+     * The identifier of the specific trip that the prediction is for.
+     */
     private final String id;
+
+    /**
+     * Visit identifier.
+     */
     private final Integer visitID;
+
+    /**
+     * The line ID.
+     */
     private final String lineID;
+
+    /**
+     * The line name
+     */
     private final String lineName;
+
+    /**
+     * The direction ID.
+     */
     private final Integer directionID;
+
+    /**
+     * The destination name.
+     */
     private final String destinationName;
+
+    /**
+     * The destination text.
+     */
     private final String destinationText;
+
+    /**
+     * The estimated departure time.
+     */
     private final Long estimatedTime;
+
+    /**
+     * The vehicle ID.
+     */
     private final String vehicleID;
 
     /**
@@ -229,6 +268,8 @@ public final class Trip implements Model {
     }
 
     /**
+     * The starting stop.
+     *
      * @return The (starting) stop.
      */
     public Stop getStop() {
@@ -243,6 +284,8 @@ public final class Trip implements Model {
     }
 
     /**
+     * Visit identifier.
+     *
      * @return The visit ID.
      */
     public Integer getVisitID() {
@@ -250,6 +293,9 @@ public final class Trip implements Model {
     }
 
     /**
+     * The identifier of a route. This is an internal identifier and is not equal to the route number displayed on
+     * the front of the bus. It should not be displayed to the public.
+     *
      * @return The line ID.
      */
     public String getLineID() {
@@ -257,6 +303,8 @@ public final class Trip implements Model {
     }
 
     /**
+     * This is the route number that is displayed on the front of the bus and on any publicity advertising the route.
+     *
      * @return The line name.
      */
     public String getLineName() {
@@ -264,6 +312,9 @@ public final class Trip implements Model {
     }
 
     /**
+     * This identifies the direction of the trip that the vehicle is on.
+     * It indicates whether the vehicle is on an outbound or inbound trip.
+     *
      * @return The direction ID.
      */
     public Integer getDirectionID() {
@@ -271,6 +322,9 @@ public final class Trip implements Model {
     }
 
     /**
+     * The full length destination name of the trip the vehicle is on.
+     * The destination name is based on the route and end point of the trip.
+     *
      * @return The destination name.
      */
     public String getDestinationName() {
@@ -278,6 +332,9 @@ public final class Trip implements Model {
     }
 
     /**
+     * The abbreviated destination name of the trip the vehicle is on.
+     * The destination text is based on the route and end point of the trip.
+     *
      * @return The destination text.
      */
     public String getDestinationText() {
@@ -285,6 +342,9 @@ public final class Trip implements Model {
     }
 
     /**
+     * This is the predicted time of arrival for the vehicle at a specific stop.
+     * It is an absolute time in UTC as per Unix epoch (in milliseconds).
+     *
      * @return The estimated departure time.
      */
     public Long getEstimatedTime() {
@@ -292,6 +352,8 @@ public final class Trip implements Model {
     }
 
     /**
+     * The unique identifier of the vehicle. This is an internal identifier and should not be displayed to the public.
+     *
      * @return The vehicle ID or {@code null} if not present.
      */
     public String getVehicleID() {

src/main/java/de/stklcode/pubtrans/ura/reader/package-info.java

@@ -0,0 +1,20 @@
+/*
+ * Copyright 2016-2021 Stefan Kalscheuer
+ *
+ * Licensed 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
+ *
+ * http://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.
+ */
+
+/**
+ * jURAclient utility classes for asynchronous reading from the API.
+ */
+package de.stklcode.pubtrans.ura.reader;

src/main/java/module-info.java

@@ -14,6 +14,9 @@
  * limitations under the License.
  */
 
+/**
+ * jURAclient main module.
+ */
 module de.stklcode.pubtrans.juraclient {
     exports de.stklcode.pubtrans.ura;
     exports de.stklcode.pubtrans.ura.exception;