From 2ef24ca16a6c61d11f6c64b07726be5f0199f5ba Mon Sep 17 00:00:00 2001
From: Richard Cordovano <rcordovano@basistech.com>
Date: Fri, 6 Mar 2020 12:17:33 -0500
Subject: [PATCH] Update docs for geoartifact helpers
---
.../blackboardutils/GeoArtifactsHelper.java | 97 ++++---
.../attributes/TskGeoTrackpointsUtil.java | 269 +++++++++++-------
2 files changed, 219 insertions(+), 147 deletions(-)
diff --git a/bindings/java/src/org/sleuthkit/datamodel/blackboardutils/GeoArtifactsHelper.java b/bindings/java/src/org/sleuthkit/datamodel/blackboardutils/GeoArtifactsHelper.java
index 0e3f99f5a..a589c764f 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,59 @@ 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., 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 (see
+ * https://en.wikipedia.org/wiki/Geographic_coordinate_system) where the
+ * coordinates are latitude, longitude and altitude (elevation).
*
- * @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 +103,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 +112,38 @@ 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 navigation device as a route by a user. A waypoint is a
+ * location in a geographic coordinate system (see
+ * https://en.wikipedia.org/wiki/Geographic_coordinate_system) where the
+ * coordinates are latitude, longitude and altitude (elevation).
*
- * @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 {
+ public BlackboardArtifact addRoute(String routeName, Long creationTime, GeoWaypointList wayPoints, List<BlackboardAttribute> moreAttributes) throws TskCoreException, BlackboardException {
- if (points == null) {
+ 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));
}
@@ -148,4 +166,5 @@ public BlackboardArtifact addRoute(String routeName, Long creationTime, GeoWaypo
return artifact;
}
+
}
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 ad434f5c7..861670375 100755
--- a/bindings/java/src/org/sleuthkit/datamodel/blackboardutils/attributes/TskGeoTrackpointsUtil.java
+++ b/bindings/java/src/org/sleuthkit/datamodel/blackboardutils/attributes/TskGeoTrackpointsUtil.java
@@ -28,10 +28,18 @@
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 JSON-valued TSK_GEO_TRACKPOINTS
+ * attribute and a GeoTrackPointList object. A GeoTrackPointList is a collection
+ * of GeoTrackPoint objects. A GeoTrackPoint object represents a track point,
+ * which is a location in a geographic coordinate system (see
+ * https://en.wikipedia.org/wiki/Geographic_coordinate_system) where the
+ * coordinates are latitude, longitude and altitude (elevation).
+ *
+ * A TSK_GEO_TRACKPOINTS atrribute is typically attached to a TSK_GPS_TRACK
+ * artifact. A TSK_GPS_TRACK artifact records a track, or path, of a GPS-enabled
+ * device as a connected series of track points.
*/
-public final class TskGeoTrackpointsUtil implements BlackboardAttributeUtil<GeoTrackPointList> {
+public final class TskGeoTrackpointsUtil implements BlackboardAttributeUtil<TskGeoTrackpointsUtil.GeoTrackPointList> {
@Override
public BlackboardAttribute toAttribute(String moduleName, GeoTrackPointList value) {
@@ -61,112 +69,126 @@ public GeoTrackPointList fromAttribute(BlackboardAttribute attribute) {
}
/**
- * Creates a GeoTrackPointList from the given JSON string.
+ * Constructs a GeoTrackPointList object from a GeoTrackPointList serailized
+ * as JSON.
*
- * @param jsonString JSon string of track points.
+ * @param trackPointsJson 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 trackPointsJson) {
+ if (trackPointsJson == null || trackPointsJson.isEmpty()) {
+ throw new IllegalArgumentException("fromJSON was passed a empty or null JSON string");
}
- return (new Gson()).fromJson(jsonString, GeoTrackPointList.class);
+ return (new Gson()).fromJson(trackPointsJson, GeoTrackPointList.class);
}
/**
- * Returns a JSON string representing the given object.
+ * Serializes a GeoTrackPointList object as JSON.
+ *
+ * @param trackPoints A GeoTrackPointList object.
*
- * @return JSON string
+ * @return The JSON serialization of the GeoTrackPointList.
*/
- 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 collection of GeoTrackPoint objects. A GeoTrackPoint object represents
+ * a track point, which is a location in a geographic coordinate system (see
+ * https://en.wikipedia.org/wiki/Geographic_coordinate_system) where the
+ * coordinates are latitude, longitude and altitude (elevation).
*/
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.
+ * Constructs a GeoTrackPointList from a list of GeoTrackPoint objects.
*
- * @param points List of track points, cannot be null.
+ * @param trackPoints A list of GeoTrackPoint objects.
*/
- public GeoTrackPointList(List<GeoTrackPoint> points) {
- if (points == null) {
+ public GeoTrackPointList(List<GeoTrackPoint> trackPoints) {
+ if (trackPoints == null) {
throw new IllegalArgumentException("Constructor was passed a null list");
}
- pointList = points;
+ pointList = new ArrayList<>();
+ for (GeoTrackPoint point : trackPoints) {
+ pointList.add(new GeoTrackPoint(point));
+ }
}
/**
- * 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));
- }
+// /**
+// * Adds a track point to this list of track points.
+// *
+// * @param latitude The latitude of the track point.
+// * @param longitude The longitude of the trac kpoint.
+// * @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/sec, may be null.
+// * @param distanceFromHomePoint The distance of the track point 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 creation time of the track point as
+// * milliseconds from the Java epoch of
+// * 1970-01-01T00:00:00Z, may be null.
+// */
+// 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.
+ * Gets an iterator for the track points in this list of track points.
*
- * @return An iterator over the elements of the list.
+ * @return The iterator.
*/
@Override
public Iterator<GeoTrackPoint> iterator() {
@@ -174,18 +196,20 @@ public Iterator<GeoTrackPoint> 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.
+ * Get the nominal start time for the track represented by this list of
+ * track points, if available.
*
- * @return First non-null time stamp or null, if one was not found.
+ * @return The earliest timestamp of a track point in this list of track
+ * points, may be null.
*/
public Long getStartTime() {
List<GeoTrackPoint> orderedPoints = getTimeOrderedPoints();
@@ -200,9 +224,11 @@ public Long getStartTime() {
}
/**
- * Return the ends time for the track.
+ * Get the nominal end time for the track represented by this list of
+ * track points, if available.
*
- * @return First non-null time stamp or null, if one was not found.
+ * @return The latest timestamp of a track point in this list of track
+ * points, may be null.
*/
public Long getEndTime() {
List<GeoTrackPoint> orderedPoints = getTimeOrderedPoints();
@@ -218,20 +244,22 @@ public Long getEndTime() {
}
/**
- * Returns a timestamp ordered copy of the points list.
+ * Gets the list of track points in this object as a list ordered by
+ * tarck 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 (see
+ * https://en.wikipedia.org/wiki/Geographic_coordinate_system) where the
+ * coordinates are latitude, longitude and altitude (elevation).
*/
- 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 +267,30 @@ 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 (see
+ * https://en.wikipedia.org/wiki/Geographic_coordinate_system) where
+ * the coordinates are latitude, longitude and altitude (elevation).
*
- * @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 trac kpoint.
+ * @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/sec, 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 creation time 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 +308,64 @@ public GeoTrackPoint(Double latitude,
}
/**
- * Returns velocity of the point.
+ * Constructs a copy of a representation of a track point, which is
+ * a location in a geographic coordinate system (see
+ * https://en.wikipedia.org/wiki/Geographic_coordinate_system) where
+ * the coordinates are latitude, longitude and altitude (elevation).
*
- * @return Double velocity value, maybe null if not available or
- * applicable
+ * @param other A GeoTrackPoint to be copied.
+ */
+ private GeoTrackPoint(GeoTrackPoint other) {
+ super(other.getLatitude(), other.getLongitude(), other.getAltitude(), other.getName());
+ this.velocity = other.getVelocity();
+ this.distanceFromHomePoint = other.getDistanceFromHomePoint();
+ this.distanceTraveled = other.getDistanceTraveled();
+ this.timestamp = other.getTimeStamp();
+ }
+
+ /**
+ * Gets the velocity of the device at this track point in
+ * meters/sec, if known.
+ *
+ * @return The velocity in meters/sec, may be null.
*/
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.
*/
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.
*/
public Double getDistanceTraveled() {
return distanceTraveled;
}
/**
- * Returns the time stamp (seconds from java/unix epoch) of the
- * track point.
+ * Gets the creation time 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 creation timestamp, may be null.
*/
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) {
@@ -326,5 +377,7 @@ public int compareTo(GeoTrackPointList.GeoTrackPoint otherTP) {
}
}
}
+
}
+
}
--
GitLab