diff --git a/bindings/java/src/org/sleuthkit/datamodel/blackboardutils/GeoArtifactsHelper.java b/bindings/java/src/org/sleuthkit/datamodel/blackboardutils/GeoArtifactsHelper.java
index 0e3f99f5a072d33678e470d91dfb72af8b68e6fe..838c8e601166a379477cdb454adccacc92b76c4d 100755
--- a/bindings/java/src/org/sleuthkit/datamodel/blackboardutils/GeoArtifactsHelper.java
+++ b/bindings/java/src/org/sleuthkit/datamodel/blackboardutils/GeoArtifactsHelper.java
@@ -32,8 +32,8 @@
import org.sleuthkit.datamodel.blackboardutils.attributes.TskGeoWaypointsUtil;
/**
- * Class to help ingest modules create Geolocation artifacts.
- *
+ * An artifact creation helper that adds geolocation artifacts to the case
+ * database.
*/
public final class GeoArtifactsHelper extends ArtifactHelperBase {
@@ -42,49 +42,57 @@ public final class GeoArtifactsHelper extends ArtifactHelperBase {
private final TskGeoWaypointsUtil waypointsAttributeUtil;
/**
- * Constructs a geolocation artifact helper for the given source file.
+ * Constructs an artifact creation helper that adds geolocation artifacts to
+ * the case database.
*
- * @param caseDb Sleuthkit case db.
- * @param moduleName Name of module using the helper.
- * @param programName Optional program name for TSK_PROG_NAME attribute,
- * nulls and empty string will be ignored.
- * @param srcFile Source file being processed by the module.
+ * @param caseDb The case database.
+ * @param moduleName The name of the module creating the artifacts.
+ * @param programName The name of the user application associated with the
+ * geolocation data to be recorded as artifacts, may be
+ * null. If a program name is supplied, it will be added
+ * to each artifact that is created as a TSK_PROG_NAME
+ * attribute.
+ * @param srcContent The source content for the artifacts, i.e., either a
+ * file within a data source or a data source.
*/
- public GeoArtifactsHelper(SleuthkitCase caseDb, String moduleName, String programName, Content srcFile) {
- super(caseDb, moduleName, srcFile);
+ public GeoArtifactsHelper(SleuthkitCase caseDb, String moduleName, String programName, Content srcContent) {
+ super(caseDb, moduleName, srcContent);
this.programName = programName;
trackPointAttributeUtil = new TskGeoTrackpointsUtil();
waypointsAttributeUtil = new TskGeoWaypointsUtil();
}
/**
- * Add a Track from a GPS device to the database. A Track represents a
- * series of points that the device has traveled on. This will create a
- * TSK_GPS_TRACK artifact and add it to the case.
+ * Adds a TSK_GPS_TRACK artifact to the case database. A Global Positioning
+ * System (GPS) track artifact records the track, or path, of a GPS-enabled
+ * device as a connected series of track points. A track point is a location
+ * in a geographic coordinate system with latitude, longitude and altitude
+ * (elevation) axes.
*
- * @param trackName Name of GPS track, not required.
- * @param points List of GeoTrackPoints that the track traversed.
- * Required.
- * @param moreAttributes Optional list of other artifact attributes
+ * @param trackName The name of the GPS track, may be null.
+ * @param trackPoints The track points that make up the track.
+ * @param moreAttributes Additional attributes for the TSK_GPS_TRACK
+ * artifact, may be null.
*
- * @return TSK_GPS_TRACK artifact
+ * @return The TSK_GPS_TRACK artifact that was added to the case database.
*
- * @throws TskCoreException If there is an error creating the artifact.
- * @throws BlackboardException If there is a problem posting the artifact
+ * @throws TskCoreException If there is an error creating the artifact.
+ * @throws BlackboardException If there is a error posting the artifact to
+ * the blackboard.
*/
- public BlackboardArtifact addTrack(String trackName, GeoTrackPointList points, List<BlackboardAttribute> moreAttributes) throws TskCoreException, BlackboardException {
-
- if(points == null) {
+ public BlackboardArtifact addTrack(String trackName, GeoTrackPointList trackPoints, List<BlackboardAttribute> moreAttributes) throws TskCoreException, BlackboardException {
+ if (trackPoints == null) {
throw new IllegalArgumentException(String.format("addTrack was passed a null list of track points"));
}
-
+
BlackboardArtifact artifact = getContent().newArtifact(BlackboardArtifact.ARTIFACT_TYPE.TSK_GPS_TRACK);
List<BlackboardAttribute> attributes = new ArrayList<>();
+
if (trackName != null) {
attributes.add(new BlackboardAttribute(BlackboardAttribute.ATTRIBUTE_TYPE.TSK_NAME, getModuleName(), trackName));
}
- attributes.add(trackPointAttributeUtil.toAttribute(getModuleName(), points));
+ attributes.add(trackPointAttributeUtil.toAttribute(getModuleName(), trackPoints));
if (programName != null) {
attributes.add(new BlackboardAttribute(BlackboardAttribute.ATTRIBUTE_TYPE.TSK_PROG_NAME, getModuleName(), programName));
@@ -93,7 +101,7 @@ public BlackboardArtifact addTrack(String trackName, GeoTrackPointList points, L
if (moreAttributes != null) {
attributes.addAll(moreAttributes);
}
-
+
artifact.addAttributes(attributes);
getSleuthkitCase().getBlackboard().postArtifact(artifact, getModuleName());
@@ -102,30 +110,36 @@ public BlackboardArtifact addTrack(String trackName, GeoTrackPointList points, L
}
/**
- * Add a Route from a GPS device to the database. This will create a
- * TSK_GPS_ROUTE artifact and add it to the case.
+ * Adds a TSK_GPS_ROUTE artifact to the case database. A Global Positioning
+ * System (GPS) route artifact records one or more waypoints entered into a
+ * GPS-enabled device as a route to be navigated from waypoint to waypoint.
+ * A waypoint is a location in a geographic coordinate system with latitude,
+ * longitude and altitude (elevation) axes.
*
- * @param routeName Optional route name
- * @param creationTime Time the route was created, optional.
- * @param points List of GeoWaypointList belonging to the route, required
- * @param moreAttributes Optional list of other artifact attributes.
+ * @param routeName The name of the GPS route, may be null.
+ * @param creationTime The time at which the route was created as
+ * milliseconds from the Java epoch of
+ * 1970-01-01T00:00:00Z, may be null.
+ * @param wayPoints The waypoints that make up the route.
+ * @param moreAttributes Additional attributes for the TSK_GPS_ROUTE
+ * artifact, may be null.
*
- * @return TSK_GPS_ROUTE artifact
+ * @return The TSK_GPS_ROUTE artifact that was added to the case database.
*
- * @throws TskCoreException If there is an error creating the artifact.
- * @throws BlackboardException If there is a problem posting the artifact.
+ * @throws TskCoreException If there is an error creating the artifact.
+ * @throws BlackboardException If there is a error posting the artifact to
+ * the blackboard.
*/
- public BlackboardArtifact addRoute(String routeName, Long creationTime, GeoWaypointList points, List<BlackboardAttribute> moreAttributes) throws TskCoreException, BlackboardException {
-
- if (points == null) {
+ public BlackboardArtifact addRoute(String routeName, Long creationTime, GeoWaypointList wayPoints, List<BlackboardAttribute> moreAttributes) throws TskCoreException, BlackboardException {
+ if (wayPoints == null) {
throw new IllegalArgumentException(String.format("addRoute was passed a null list of waypoints"));
}
BlackboardArtifact artifact = getContent().newArtifact(BlackboardArtifact.ARTIFACT_TYPE.TSK_GPS_ROUTE);
List<BlackboardAttribute> attributes = new ArrayList<>();
- attributes.add(waypointsAttributeUtil.toAttribute(getModuleName(), points));
-
+ attributes.add(waypointsAttributeUtil.toAttribute(getModuleName(), wayPoints));
+
if (routeName != null) {
attributes.add(new BlackboardAttribute(BlackboardAttribute.ATTRIBUTE_TYPE.TSK_NAME, getModuleName(), routeName));
}
diff --git a/bindings/java/src/org/sleuthkit/datamodel/blackboardutils/attributes/TskGeoTrackpointsUtil.java b/bindings/java/src/org/sleuthkit/datamodel/blackboardutils/attributes/TskGeoTrackpointsUtil.java
index ad434f5c7d3e1da86cbf7620629b9fb0a9c9b835..d5df2ca7a5dbc3efe34bebdf8c5e1ce2a1e13566 100755
--- a/bindings/java/src/org/sleuthkit/datamodel/blackboardutils/attributes/TskGeoTrackpointsUtil.java
+++ b/bindings/java/src/org/sleuthkit/datamodel/blackboardutils/attributes/TskGeoTrackpointsUtil.java
@@ -28,14 +28,19 @@
import org.sleuthkit.datamodel.blackboardutils.attributes.TskGeoTrackpointsUtil.GeoTrackPointList.GeoTrackPoint;
/**
- * Utility class for translating TSK_GEO_TRACKPOINTS attribute values to
- * GeoTrackPointList objects and GeoTrackPointList to BlackboardAttributes.
+ * A utility class for converting between a TSK_GEO_TRACKPOINTS attribute and a
+ * GeoTrackPointList. A GeoTrackPointList is a collection of GeoTrackPoints. A
+ * GeoTrackPoint represents a track point, which is a location in a geographic
+ * coordinate system with latitude, longitude and altitude (elevation) axes.
+ *
+ * TSK_GEO_TRACKPOINTS attributes are used by TSK_GPS_TRACK artifacts to record
+ * a track, or path, of a GPS-enabled device as a connected series of track
+ * points.
*/
public final class TskGeoTrackpointsUtil implements BlackboardAttributeUtil<GeoTrackPointList> {
@Override
public BlackboardAttribute toAttribute(String moduleName, GeoTrackPointList value) {
-
if (value == null) {
throw new IllegalArgumentException("toAttribute was passed a null list");
}
@@ -61,131 +66,85 @@ public GeoTrackPointList fromAttribute(BlackboardAttribute attribute) {
}
/**
- * Creates a GeoTrackPointList from the given JSON string.
+ * Constructs a GeoTrackPointList object from its JSON representation.
*
- * @param jsonString JSon string of track points.
+ * @param json A JSON representation of a GeoTrackPointList.
*
- * @return Timestamp ordered list of GeoTrackPoints, empty list will be
- * returned if jsonString is null or empty.
+ * @return The GeoTrackPointList object.
*/
- private static GeoTrackPointList fromJSON(String jsonString) {
- if (jsonString == null || jsonString.isEmpty()) {
- return null;
+ private static GeoTrackPointList fromJSON(String json) {
+ if (json == null || json.isEmpty()) {
+ throw new IllegalArgumentException("fromJSON was passed a empty or null JSON string");
}
- return (new Gson()).fromJson(jsonString, GeoTrackPointList.class);
+ return (new Gson()).fromJson(json, GeoTrackPointList.class);
}
/**
- * Returns a JSON string representing the given object.
+ * Creates a JSON representation of a GeoTrackPointList object.
*
- * @return JSON string
+ * @param trackPoints A GeoTrackPointList object.
+ *
+ * @return The JSON representation of the GeoTrackPointList object.
*/
- private static String toJSON(GeoTrackPointList pointList) {
+ private static String toJSON(GeoTrackPointList trackPoints) {
+ if (trackPoints == null) {
+ throw new IllegalArgumentException("toJSON was passed a null track points list");
+ }
+
Gson gson = new Gson();
- return gson.toJson(pointList);
+ return gson.toJson(trackPoints);
}
/**
- * A list of GeoTrackPoints.
+ * A list of GeoTrackPoints. A GeoTrackPoint represents a track point, which
+ * is a location in a geographic coordinate system with latitude, longitude
+ * and altitude (elevation) axes.
*/
public static class GeoTrackPointList implements Iterable<GeoTrackPointList.GeoTrackPoint> {
private final List<GeoTrackPoint> pointList;
/**
- * Construct an empty GeoTrackPointList.
+ * Constructs an empty GeoTrackPointList.
*/
public GeoTrackPointList() {
pointList = new ArrayList<>();
}
/**
- * Construct a new instance with the given list of GeoTrackPoint
- * objects.
- *
- * @param points List of track points, cannot be null.
- */
- public GeoTrackPointList(List<GeoTrackPoint> points) {
- if (points == null) {
- throw new IllegalArgumentException("Constructor was passed a null list");
- }
-
- pointList = points;
- }
-
- /**
- * Add a point to the list of track points.
+ * Adds a track point to this list of track points.
*
- * @param point A point to add to the track point list, cannot be null.
+ * @param trackPoint A track point.
*/
- public void addPoint(GeoTrackPoint point) {
- if (point == null) {
- throw new IllegalArgumentException("addPoint was passed a null list");
+ public void addPoint(GeoTrackPoint trackPoint) {
+ if (trackPoint == null) {
+ throw new IllegalArgumentException("addPoint was passed a null track point");
}
- pointList.add(point);
+ pointList.add(trackPoint);
}
- /**
- * Adds a new point with the given attributes.
- *
- * @param latitude Latitude of the trackpoint, required
- * @param longitude Longitude of the trackpoint, required
- * @param altitude Altitude of the trackpoint, maybe null
- * @param name Name of trackpoint, maybe null
- * @param velocity Velocity in meters/sec, maybe null
- * @param distanceFromHomePoint Track point distance from an established
- * "home point", may be null if not
- * applicable
- * @param distanceTraveled Overall distance traveled in meters at
- * the time this trackpoint was created,
- * maybe null if not applicable
- * @param timestamp Trackpoint creation time, maybe null if
- * not applicable
- */
- public void addPoint(Double latitude,
- Double longitude,
- Double altitude,
- String name,
- Double velocity,
- Double distanceFromHomePoint,
- Double distanceTraveled,
- Long timestamp) {
- pointList.add(new GeoTrackPoint(
- latitude,
- longitude,
- altitude,
- name,
- velocity,
- distanceFromHomePoint,
- distanceTraveled,
- timestamp));
- }
-
- /**
- * Returns an iterator over the points in this GeoTrackPointList.
- *
- * @return An iterator over the elements of the list.
- */
@Override
public Iterator<GeoTrackPoint> iterator() {
return pointList.iterator();
}
/**
- * Returns true if this list contains no points.
+ * Returns whether or not this list of track points is empty.
*
- * @return True if this list contains no points.
+ * @return True or false.
*/
public boolean isEmpty() {
return pointList.isEmpty();
}
/**
- * Return the start time for the track.
+ * Gets the earliest track point timestamp in this list of track points,
+ * if timestamps are present.
*
- * @return First non-null time stamp or null, if one was not found.
+ * @return The timestamp in milliseconds from the Java epoch of
+ * 1970-01-01T00:00:00Z, may be null or zero.
*/
public Long getStartTime() {
List<GeoTrackPoint> orderedPoints = getTimeOrderedPoints();
@@ -200,9 +159,11 @@ public Long getStartTime() {
}
/**
- * Return the ends time for the track.
+ * Gets the latest track point timestamp in this list of track points,
+ * if timestamps are present.
*
- * @return First non-null time stamp or null, if one was not found.
+ * @return The timestamp in milliseconds from the Java epoch of
+ * 1970-01-01T00:00:00Z, may be null or zero.
*/
public Long getEndTime() {
List<GeoTrackPoint> orderedPoints = getTimeOrderedPoints();
@@ -218,20 +179,21 @@ public Long getEndTime() {
}
/**
- * Returns a timestamp ordered copy of the points list.
+ * Gets this list of track points as a list ordered by track point
+ * timestamp.
*
- * @return List of points sorted by timestamps.
+ * @return The ordered list of track points.
*/
private List<GeoTrackPoint> getTimeOrderedPoints() {
return pointList.stream().sorted().collect(Collectors.toCollection(ArrayList::new));
}
/**
- * A GeoTrackPoint is a Waypoint with more detailed information about
- * the point.
- *
+ * A representation of a track point, which is a location in a
+ * geographic coordinate system with latitude, longitude and altitude
+ * (elevation) axes.
*/
- public final static class GeoTrackPoint extends TskGeoWaypointsUtil.GeoWaypointList.GeoWaypoint implements Comparable<GeoTrackPointList.GeoTrackPoint> {
+ public final static class GeoTrackPoint extends TskGeoWaypointsUtil.GeoWaypointList.GeoWaypoint implements Comparable<GeoTrackPoint> {
private final Double velocity;
private final Double distanceFromHomePoint;
@@ -239,24 +201,28 @@ public final static class GeoTrackPoint extends TskGeoWaypointsUtil.GeoWaypointL
private final Long timestamp;
/**
- * Constructs a GeoTrackPoint with the given attributes.
+ * Constructs a representation of a track point, which is a location
+ * in a geographic coordinate system with latitude, longitude and
+ * altitude (elevation) axes.
*
- * @param latitude Latitude of the track point, required
- * @param longitude Longitude of the track point,
- * required
- * @param altitude Altitude of the track point, may be
- * null
- * @param name Name of track point, may be null
- * @param velocity Velocity in meters/sec, may be null
- * @param distanceFromHomePoint Track point distance from an
- * established "home point", maybe null
- * if not applicable
- * @param distanceTraveled Overall distance traveled in meters
- * at the time this track point was
- * created, maybe null if not
- * applicable
- * @param timestamp Track point creation time, maybe
- * null if not applicable
+ * @param latitude The latitude of the track point.
+ * @param longitude The longitude of the track point.
+ * @param altitude The altitude of the track point, may
+ * be null.
+ * @param name The name of the track point, may be
+ * null.
+ * @param velocity The velocity of the device at the
+ * track point in meters per second,
+ * may be null.
+ * @param distanceFromHomePoint The distance of the track point in
+ * meters from an established home
+ * point, may be null.
+ * @param distanceTraveled The distance the device has traveled
+ * in meters at the time this track
+ * point was created, may be null.
+ * @param timestamp The timestamp of the track point as
+ * milliseconds from the Java epoch of
+ * 1970-01-01T00:00:00Z, may be null.
*/
public GeoTrackPoint(Double latitude,
Double longitude,
@@ -274,47 +240,47 @@ public GeoTrackPoint(Double latitude,
}
/**
- * Returns velocity of the point.
+ * Gets the velocity of the device at this track point in meters per
+ * second, if known.
*
- * @return Double velocity value, maybe null if not available or
- * applicable
+ * @return The velocity in meters/sec, may be null or zero.
*/
public Double getVelocity() {
return velocity;
}
/**
- * Returns distance from home point for the point.
+ * Gets the distance of this track point from an established home
+ * point, if known.
*
- * @return Double velocity distance from home point, maybe null if
- * not available or applicable
+ * @return The distance in meters, may be null or zero.
*/
public Double getDistanceFromHomePoint() {
return distanceFromHomePoint;
}
/**
- * Returns distance traveled for the point.
+ * Gets the distance the device has traveled in meters at the time
+ * this track point was created, if known.
*
- * @return Double distance traveled value, maybe null if not
- * available or applicable
+ * @return The distance traveled in meters, may be null or zero.
*/
public Double getDistanceTraveled() {
return distanceTraveled;
}
/**
- * Returns the time stamp (seconds from java/unix epoch) of the
- * track point.
+ * Gets the timestamp of this track point as milliseconds from the
+ * Java epoch of 1970-01-01T00:00:00Z, if known.
*
- * @return time stamp of the track point, or null if not available
+ * @return The timestamp, may be null or zero.
*/
public Long getTimeStamp() {
return timestamp;
}
@Override
- public int compareTo(GeoTrackPointList.GeoTrackPoint otherTP) {
+ public int compareTo(GeoTrackPoint otherTP) {
Long otherTimeStamp = otherTP.getTimeStamp();
if (timestamp == null && otherTimeStamp != null) {
diff --git a/bindings/java/src/org/sleuthkit/datamodel/blackboardutils/attributes/TskGeoWaypointsUtil.java b/bindings/java/src/org/sleuthkit/datamodel/blackboardutils/attributes/TskGeoWaypointsUtil.java
index 08d5a1c6bd6a77ab67bf0992c5a73a2d4e58ebe5..a8d4a5e105d7043382c77acd8d66c6e06ae9c2dc 100755
--- a/bindings/java/src/org/sleuthkit/datamodel/blackboardutils/attributes/TskGeoWaypointsUtil.java
+++ b/bindings/java/src/org/sleuthkit/datamodel/blackboardutils/attributes/TskGeoWaypointsUtil.java
@@ -27,14 +27,21 @@
import org.sleuthkit.datamodel.blackboardutils.attributes.TskGeoWaypointsUtil.GeoWaypointList.GeoWaypoint;
/**
- * Utility class for Translating TSK_GEO_WAYPOINTS attribute values to
- * GeoWaypointList objects and GeoWaypointList to BlackboardAttributes.
+ * A utility class for converting between a TSK_GEO_WAYPOINTS attribute and a
+ * GeoWaypointList object. A GeoWaypointList is a collection of GeoWaypoints
+ * objects. A GeoWaypoint represents a waypoint for a GPS-enabled device with a
+ * navigation capability. Every waypoint is a location, possibly named, in a
+ * geographic coordinate system with latitude, longitude and altitude
+ * (elevation) axes.
+ *
+ * TSK_GEO_WAYPOINTS attributes are used by TSK_GPS_ROUTE artifacts to record
+ * one or more waypoints linked together as a route to be navigated from
+ * waypoint to waypoint.
*/
public final class TskGeoWaypointsUtil implements BlackboardAttributeUtil<GeoWaypointList> {
@Override
public BlackboardAttribute toAttribute(String moduleName, GeoWaypointList value) {
-
if (value == null) {
throw new IllegalArgumentException("toAttribute was pass a null list");
}
@@ -60,61 +67,65 @@ public GeoWaypointList fromAttribute(BlackboardAttribute attribute) {
}
/**
- * Deserialize the given list of GeoTrackPoints.
+ * Constructs a GeoWaypointList object from its JSON representation.
*
- * @param jsonString JSon string of track points.
+ * @param json A JSON representation of a GeoWaypointList.
*
- * @return Timestamp ordered list of GeoTrackPoints, empty list will be
- * returned if jsonString is null or empty.
+ * @return The GeoWaypointList object.
*/
- private static GeoWaypointList fromJSON(String jsonString) {
- if (jsonString == null || jsonString.isEmpty()) {
+ private static GeoWaypointList fromJSON(String json) {
+ if (json == null || json.isEmpty()) {
return null;
}
- return (new Gson()).fromJson(jsonString, GeoWaypointList.class);
+ return (new Gson()).fromJson(json, GeoWaypointList.class);
}
/**
- * Returns a JSON string can than be used as the TSK_GEO_TRACKPOINTS
- * attribute of the TSK_GPS_TRACK artifact.
+ * Creates a JSON representation of a GeoWaypointList object.
+ *
+ * @param waypoints A GeoWaypointList object.
*
- * @return JSON string
+ * @return The JSON representation of the GeoWaypointList object.
*/
- private static String toJSON(GeoWaypointList pointList) {
+ private static String toJSON(GeoWaypointList waypoints) {
Gson gson = new Gson();
- return gson.toJson(pointList);
+ return gson.toJson(waypoints);
}
/**
- * Helper class to make it easier to serialize and deserialize the list of
- * waypoints points with json.
- *
+ * A list of GeoWaypoints. A GeoWaypoint represents a waypoint, which is a a
+ * location, possibly named, in a geographic coordinate system with
+ * latitude, longitude and altitude (elevation) axes.
*/
public static final class GeoWaypointList implements Iterable<GeoWaypointList.GeoWaypoint> {
private final List<GeoWaypoint> points;
+ /**
+ * Constructs an empty GeoWaypointList.
+ */
public GeoWaypointList() {
points = new ArrayList<>();
}
/**
- * Adds a point to the list of waypoints.
+ * Adds a waypoint to this list of waypoints.
*
- * @param latitude The latitude, required
- * @param longitude The longitude, required
- * @param altitude The altitude, can be null
- * @param name A name for the point, can be null
+ * @param wayPoint A waypoint.
*/
- public void addPoint(Double latitude, Double longitude, Double altitude, String name) {
- points.add(new GeoWaypoint(latitude, longitude, altitude, name));
+ public void addPoint(GeoWaypoint wayPoint) {
+ if (wayPoint == null) {
+ throw new IllegalArgumentException("addPoint was passed a null waypoint");
+ }
+
+ points.add(wayPoint);
}
/**
- * Returns true if this list contains no points.
+ * Returns whether or not this list of waypoints is empty.
*
- * @return True if this list contains no points.
+ * @return True or false.
*/
public boolean isEmpty() {
return points.isEmpty();
@@ -126,8 +137,9 @@ public Iterator<GeoWaypointList.GeoWaypoint> iterator() {
}
/**
- * Class that represents a single waypoint made up of longitude,
- * latitude, and altitude.
+ * A representation of a waypoint, which is a a location, possibly
+ * named, in a geographic coordinate system with latitude, longitude and
+ * altitude (elevation) axes.
*/
public static class GeoWaypoint {
@@ -137,16 +149,22 @@ public static class GeoWaypoint {
private final String name;
/**
- * Creates a GeoWaypoint instance.
+ * Constructs a representation of a waypoint, which is a a location,
+ * possibly named, in a geographic coordinate system with latitude,
+ * longitude and altitude (elevation) axes.
*
- * @param latitude The latitude, required
- * @param longitude The longitude, required
- * @param altitude The altitude, can be null
- * @param name A name for the waypoint, optional
+ * @param latitude The latitude of the waypoint.
+ * @param longitude The longitude of the waypoint.
+ * @param altitude The altitude of the waypoint, may be null.
+ * @param name The name of the waypoint, may be null.
*/
public GeoWaypoint(Double latitude, Double longitude, Double altitude, String name) {
- if (latitude == null || longitude == null) {
- throw new IllegalArgumentException("Constructor was passed null coordinate");
+ if (latitude == null) {
+ throw new IllegalArgumentException("Constructor was passed null latitude");
+ }
+
+ if (longitude == null) {
+ throw new IllegalArgumentException("Constructor was passed null longitude");
}
this.latitude = latitude;
@@ -156,38 +174,36 @@ public GeoWaypoint(Double latitude, Double longitude, Double altitude, String na
}
/**
- * Returns latitude of the waypoint.
+ * Gets the latitude of this waypoint.
*
- * @return Double latitude value
+ * @return The latitude.
*/
public Double getLatitude() {
return latitude;
}
/**
- * Returns longitude of the waypoint.
+ * Gets the longitude of this waypoint.
*
- * @return Double longitude value
+ * @return The longitude.
*/
public Double getLongitude() {
return longitude;
}
/**
- * Get the altitude if available for this waypoint.
+ * Get the altitude of this waypoint, if available.
*
- * @return Double altitude value, may be null if not available or
- * applicable
+ * @return The altitude, may be null or zero.
*/
public Double getAltitude() {
return altitude;
}
/**
- * Returns the name for this waypoint.
+ * Get the name of this waypoint, if available.
*
- * @return Returns waypoint name, may be null if not available or
- * applicable.
+ * @return The name, may be null or empty.
*/
public String getName() {
return name;