diff --git a/src/main/java/de/stklcode/pubtrans/ura/UraClient.java b/src/main/java/de/stklcode/pubtrans/ura/UraClient.java index 97e2f51..2794811 100644 --- a/src/main/java/de/stklcode/pubtrans/ura/UraClient.java +++ b/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; /** diff --git a/src/main/java/de/stklcode/pubtrans/ura/UraClientConfiguration.java b/src/main/java/de/stklcode/pubtrans/ura/UraClientConfiguration.java index 126afde..d035fb8 100644 --- a/src/main/java/de/stklcode/pubtrans/ura/UraClientConfiguration.java +++ b/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; /** diff --git a/src/main/java/de/stklcode/pubtrans/ura/exception/package-info.java b/src/main/java/de/stklcode/pubtrans/ura/exception/package-info.java new file mode 100644 index 0000000..d7d17a7 --- /dev/null +++ b/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; diff --git a/src/main/java/de/stklcode/pubtrans/ura/model/Message.java b/src/main/java/de/stklcode/pubtrans/ura/model/Message.java index fe5f707..c816064 100644 --- a/src/main/java/de/stklcode/pubtrans/ura/model/Message.java +++ b/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. + * + * * @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() { diff --git a/src/main/java/de/stklcode/pubtrans/ura/model/Stop.java b/src/main/java/de/stklcode/pubtrans/ura/model/Stop.java index 8d8950c..99e5327 100644 --- a/src/main/java/de/stklcode/pubtrans/ura/model/Stop.java +++ b/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: + * + * + * @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() { diff --git a/src/main/java/de/stklcode/pubtrans/ura/model/Trip.java b/src/main/java/de/stklcode/pubtrans/ura/model/Trip.java index 17fc7f7..76c0361 100644 --- a/src/main/java/de/stklcode/pubtrans/ura/model/Trip.java +++ b/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() { diff --git a/src/main/java/de/stklcode/pubtrans/ura/reader/package-info.java b/src/main/java/de/stklcode/pubtrans/ura/reader/package-info.java new file mode 100644 index 0000000..af3f0b7 --- /dev/null +++ b/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; diff --git a/src/main/java/module-info.java b/src/main/java/module-info.java index afff089..588c1b1 100644 --- a/src/main/java/module-info.java +++ b/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;