Merge pull request #1869 from rcordovano/6217-refactor-art-attr-JSON-utils

6217 Refactor geo json attr utils

bindings/java/src/org/sleuthkit/datamodel/TimelineEventTypes.java

@@ -25,8 +25,8 @@
 import java.util.stream.Stream;
 import org.apache.commons.lang3.StringUtils;
 import static org.sleuthkit.datamodel.BlackboardAttribute.ATTRIBUTE_TYPE.TSK_GEO_TRACKPOINTS;
-import org.sleuthkit.datamodel.blackboardutils.attributes.TskGeoTrackpointsUtil;
-import org.sleuthkit.datamodel.blackboardutils.attributes.TskGeoTrackpointsUtil.GeoTrackPointList;
+import org.sleuthkit.datamodel.blackboardutils.attributes.BlackboardJsonAttrUtil;
+import org.sleuthkit.datamodel.blackboardutils.attributes.GeoTrackPoints;
 
 /**
  * Container class for various types of timeline events
@@ -124,9 +124,7 @@ TimelineEventDescription parseDescription(String fullDescriptionRaw, String medD
 	 * JSON list of waypoints from which a start time can be extracted.
 	 */
 	static class GPSTrackArtifactEventType extends TimelineEventArtifactTypeSingleDescription {
-		
-		private final TskGeoTrackpointsUtil trackpointUtil = new TskGeoTrackpointsUtil();
-		
+				
 		GPSTrackArtifactEventType(int typeID, String displayName, TimelineEventType superType, BlackboardArtifact.Type artifactType, BlackboardAttribute.Type descriptionAttribute) {
 			// Passing TSK_GEO_TRACKPOINTS as the "time attribute" as more of a place filler, to avoid any null issues
 			super(typeID, displayName, superType, artifactType, new BlackboardAttribute.Type(TSK_GEO_TRACKPOINTS), descriptionAttribute);
@@ -142,7 +140,12 @@ public TimelineEventDescriptionWithTime makeEventDescription(BlackboardArtifact
 			}
 			
 			// Get the waypoint list "start time"
-			GeoTrackPointList pointsList = trackpointUtil.fromAttribute(attribute);
+            GeoTrackPoints pointsList;
+			try {
+			pointsList = BlackboardJsonAttrUtil.fromAttribute(attribute, GeoTrackPoints.class);
+            } catch (BlackboardJsonAttrUtil.InvalidJsonException ex) {
+                throw new TskCoreException("Unable to parse track points in TSK_GEO_TRACKPOINTS attribute", ex);
+            }			
 			Long startTime = pointsList.getStartTime();
 			
 			// If we didn't find a startime do not create an event.

bindings/java/src/org/sleuthkit/datamodel/blackboardutils/GeoArtifactsHelper.java

@@ -19,7 +19,6 @@
 package org.sleuthkit.datamodel.blackboardutils;
 
 import java.util.ArrayList;
-import org.sleuthkit.datamodel.blackboardutils.attributes.TskGeoTrackpointsUtil.GeoTrackPointList;
 import java.util.List;
 import org.sleuthkit.datamodel.Blackboard.BlackboardException;
 import org.sleuthkit.datamodel.BlackboardArtifact;
@@ -27,9 +26,9 @@
 import org.sleuthkit.datamodel.Content;
 import org.sleuthkit.datamodel.SleuthkitCase;
 import org.sleuthkit.datamodel.TskCoreException;
-import org.sleuthkit.datamodel.blackboardutils.attributes.TskGeoWaypointsUtil.GeoWaypointList;
-import org.sleuthkit.datamodel.blackboardutils.attributes.TskGeoTrackpointsUtil;
-import org.sleuthkit.datamodel.blackboardutils.attributes.TskGeoWaypointsUtil;
+import org.sleuthkit.datamodel.blackboardutils.attributes.BlackboardJsonAttrUtil;
+import org.sleuthkit.datamodel.blackboardutils.attributes.GeoWaypoints;
+import org.sleuthkit.datamodel.blackboardutils.attributes.GeoTrackPoints;
 
 /**
  * An artifact creation helper that adds geolocation artifacts to the case
@@ -37,9 +36,9 @@
  */
 public final class GeoArtifactsHelper extends ArtifactHelperBase {
 
+	private static final BlackboardAttribute.Type WAYPOINTS_ATTR_TYPE = new BlackboardAttribute.Type(BlackboardAttribute.ATTRIBUTE_TYPE.TSK_GEO_WAYPOINTS);
+	private static final BlackboardAttribute.Type TRACKPOINTS_ATTR_TYPE = new BlackboardAttribute.Type(BlackboardAttribute.ATTRIBUTE_TYPE.TSK_GEO_TRACKPOINTS);	
 	private final String programName;
-	private final TskGeoTrackpointsUtil trackPointAttributeUtil;
-	private final TskGeoWaypointsUtil waypointsAttributeUtil;
 
 	/**
 	 * Constructs an artifact creation helper that adds geolocation artifacts to
@@ -58,8 +57,6 @@ public final class GeoArtifactsHelper extends ArtifactHelperBase {
 	public GeoArtifactsHelper(SleuthkitCase caseDb, String moduleName, String programName, Content srcContent) {
 		super(caseDb, moduleName, srcContent);
 		this.programName = programName;
-		trackPointAttributeUtil = new TskGeoTrackpointsUtil();
-		waypointsAttributeUtil = new TskGeoWaypointsUtil();
 	}
 
 	/**
@@ -80,7 +77,7 @@ public GeoArtifactsHelper(SleuthkitCase caseDb, String moduleName, String progra
 	 * @throws BlackboardException If there is a error posting the artifact to
 	 *                             the blackboard.
 	 */
-	public BlackboardArtifact addTrack(String trackName, GeoTrackPointList trackPoints, List<BlackboardAttribute> moreAttributes) throws TskCoreException, BlackboardException {
+	public BlackboardArtifact addTrack(String trackName, GeoTrackPoints trackPoints, List<BlackboardAttribute> moreAttributes) throws TskCoreException, BlackboardException {
 		if (trackPoints == null) {
 			throw new IllegalArgumentException(String.format("addTrack was passed a null list of track points"));
 		}
@@ -92,7 +89,7 @@ public BlackboardArtifact addTrack(String trackName, GeoTrackPointList trackPoin
 			attributes.add(new BlackboardAttribute(BlackboardAttribute.ATTRIBUTE_TYPE.TSK_NAME, getModuleName(), trackName));
 		}
 
-		attributes.add(trackPointAttributeUtil.toAttribute(getModuleName(), trackPoints));
+		attributes.add(BlackboardJsonAttrUtil.toAttribute(TRACKPOINTS_ATTR_TYPE, getModuleName(), trackPoints));
 
 		if (programName != null) {
 			attributes.add(new BlackboardAttribute(BlackboardAttribute.ATTRIBUTE_TYPE.TSK_PROG_NAME, getModuleName(), programName));
@@ -107,8 +104,8 @@ public BlackboardArtifact addTrack(String trackName, GeoTrackPointList trackPoin
 		getSleuthkitCase().getBlackboard().postArtifact(artifact, getModuleName());
 
 		return artifact;
-	}
-
+	}	
+	
 	/**
 	 * 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
@@ -130,7 +127,7 @@ public BlackboardArtifact addTrack(String trackName, GeoTrackPointList trackPoin
 	 * @throws BlackboardException If there is a error posting the artifact to
 	 *                             the blackboard.
 	 */
-	public BlackboardArtifact addRoute(String routeName, Long creationTime, GeoWaypointList wayPoints, List<BlackboardAttribute> moreAttributes) throws TskCoreException, BlackboardException {
+	public BlackboardArtifact addRoute(String routeName, Long creationTime, GeoWaypoints wayPoints, List<BlackboardAttribute> moreAttributes) throws TskCoreException, BlackboardException {
 		if (wayPoints == null) {
 			throw new IllegalArgumentException(String.format("addRoute was passed a null list of waypoints"));
 		}
@@ -138,7 +135,7 @@ public BlackboardArtifact addRoute(String routeName, Long creationTime, GeoWaypo
 		BlackboardArtifact artifact = getContent().newArtifact(BlackboardArtifact.ARTIFACT_TYPE.TSK_GPS_ROUTE);
 		List<BlackboardAttribute> attributes = new ArrayList<>();
 
-		attributes.add(waypointsAttributeUtil.toAttribute(getModuleName(), wayPoints));
+		attributes.add(BlackboardJsonAttrUtil.toAttribute(WAYPOINTS_ATTR_TYPE, getModuleName(), wayPoints));
 
 		if (routeName != null) {
 			attributes.add(new BlackboardAttribute(BlackboardAttribute.ATTRIBUTE_TYPE.TSK_NAME, getModuleName(), routeName));
@@ -162,4 +159,5 @@ public BlackboardArtifact addRoute(String routeName, Long creationTime, GeoWaypo
 
 		return artifact;
 	}
+	
 }

bindings/java/src/org/sleuthkit/datamodel/blackboardutils/attributes/BlackboardAttributeUtil.java

-/*
- * Sleuth Kit Data Model
- *
- * Copyright 2020 Basis Technology Corp.
- * Contact: carrier <at> sleuthkit <dot> org
- *
- * 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.
- */
-package org.sleuthkit.datamodel.blackboardutils.attributes;
-
-import org.sleuthkit.datamodel.BlackboardAttribute;
-
-/**
- * An interface for Utility classes to implement for translating
- * BlackboardAttributes to and from a particular format. Initial use case is for
- * BlackboardAttributes of type TSK_BLACKBOARD_ATTRIBUTE_VALUE_TYPE.JSON.
- */
-public interface BlackboardAttributeUtil<T> {
-
-	/**
-	 * Translates the value of type T to a attribute.
-	 *
-	 * @param moduleName	Name of module creating the artifact
-	 * @param value			Object to Translate to attribute
-	 *
-	 * @return BlackboardAttribute created from value
-	 */
-	BlackboardAttribute toAttribute(String moduleName, T value);
-
-	/**
-	 * Translates a attribute to an object of type T.
-	 *
-	 * @param attribute The attribute to be translated to T
-	 *
-	 * @return A new instance of T created from the attribute
-	 */
-	T fromAttribute(BlackboardAttribute attribute);
-}

bindings/java/src/org/sleuthkit/datamodel/blackboardutils/attributes/BlackboardJsonAttrUtil.java

+/*
+ * Sleuth Kit Data Model
+ *
+ * Copyright 2020 Basis Technology Corp.
+ * Contact: carrier <at> sleuthkit <dot> org
+ *
+ * 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.
+ */
+package org.sleuthkit.datamodel.blackboardutils.attributes;
+
+import com.google.gson.Gson;
+import com.google.gson.JsonSyntaxException;
+import org.sleuthkit.datamodel.BlackboardAttribute;
+
+/**
+ * A utility for converting between JSON and artifact attributes of value type
+ * TSK_BLACKBOARD_ATTRIBUTE_VALUE_TYPE.JSON.
+ */
+public final class BlackboardJsonAttrUtil {
+
+	/**
+	 * Creates an attribute of a given type with the string value set to an
+	 * object of type T serialized to JSON.
+	 *
+	 * @param <T>        The type of the attribute value object to be
+	 *                   serialized.
+	 * @param attrType   The type of attribute to create.
+	 * @param moduleName The name of the module creating the attribute.
+	 * @param attrValue  The attribute value object.
+	 *
+	 * @return The BlackboardAttribute object.
+	 */
+	public static <T> BlackboardAttribute toAttribute(BlackboardAttribute.Type attrType, String moduleName, T attrValue) {
+		if (attrType.getValueType() != BlackboardAttribute.TSK_BLACKBOARD_ATTRIBUTE_VALUE_TYPE.JSON) {
+			throw new IllegalArgumentException(String.format("Attribute type %s does not have value type BlackboardAttribute.TSK_BLACKBOARD_ATTRIBUTE_VALUE_TYPE.JSON", attrType.getTypeName()));
+		}
+		return new BlackboardAttribute(attrType, moduleName, (new Gson()).toJson(attrValue));
+	}
+
+	/**
+	 * Creates an object of type T from the JSON in the string value of a
+	 * BlackboardAttribute with a value type of
+	 * TSK_BLACKBOARD_ATTRIBUTE_VALUE_TYPE.JSON.
+	 *
+	 * @param <T>   The type of the object to be created from the JSON.
+	 * @param attr  The attribute.
+	 * @param clazz The class object for class T.
+	 *
+	 * @return The T object from the attribute.
+	 *
+	 * @throws InvalidJsonException Thrown the JSON in an artifact attribute
+	 *                              cannot be deserialized to an object of the
+	 *                              specified type.
+	 */
+	public static <T> T fromAttribute(BlackboardAttribute attr, Class<T> clazz) throws InvalidJsonException {
+		BlackboardAttribute.Type attrType = attr.getAttributeType();
+		if (attrType.getValueType() != BlackboardAttribute.TSK_BLACKBOARD_ATTRIBUTE_VALUE_TYPE.JSON) {
+			throw new IllegalArgumentException(String.format("Attribute type %s does not have value type BlackboardAttribute.TSK_BLACKBOARD_ATTRIBUTE_VALUE_TYPE.JSON", attrType.getTypeName()));
+		}
+		String json = attr.getValueString();
+		if (json == null || json.isEmpty()) {
+			throw new InvalidJsonException("The string value (JSON) of the attribute is null or empty");
+		}
+		try {
+			return (new Gson()).fromJson(json, clazz);
+		} catch (JsonSyntaxException ex) {
+			throw new InvalidJsonException(String.format("The string value (JSON) could not be deserialized as a %s", clazz.getName()), ex);
+		}
+	}
+
+	/**
+	 * Constructs an exception to be thrown when the JSON in an artifact
+	 * attribute cannot be deserialized to an object of the specified type.
+	 */
+	public static class InvalidJsonException extends Exception {
+
+		private static final long serialVersionUID = 1L;
+
+		/**
+		 * Constructs an exception thrown when JSON in an artifact attribute
+		 * cannot be deserialized to an object of the specified type.
+		 *
+		 * @param message An error message.
+		 */
+		public InvalidJsonException(String message) {
+			super(message);
+		}
+
+		/**
+		 * Constructs an exception thrown when JSON in an artifact attribute
+		 * cannot be deserialized to an object of the specified type.
+		 *
+		 * @param message An error message.
+		 * @param cause   An excception that caused this exception to be thrown.
+		 */
+		public InvalidJsonException(String message, Throwable cause) {
+			super(message, cause);
+		}
+	}
+
+	/**
+	 * Prevents instantiation of this utility class.
+	 */
+	private BlackboardJsonAttrUtil() {
+	}
+
+}

bindings/java/src/org/sleuthkit/datamodel/blackboardutils/attributes/GeoTrackPoints.java

+/*
+ * Sleuth Kit Data Model
+ *
+ * Copyright 2020 Basis Technology Corp.
+ * Contact: carrier <at> sleuthkit <dot> org
+ *
+ * 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.
+ */
+package org.sleuthkit.datamodel.blackboardutils.attributes;
+
+import com.google.gson.annotations.SerializedName;
+import java.util.ArrayList;
+import java.util.Iterator;
+import java.util.List;
+import java.util.stream.Collectors;
+
+/**
+ * A GeoTrackPoints object is a collection of TrackPoint objects. A TrackPoint
+ * represents a track point, which is a location in a geographic coordinate
+ * system with latitude, longitude and altitude (elevation) axes.
+ *
+ * GeoTrackPoints objects are designed to be used as the string value of the
+ * TSK_GEO_TRACKPOINTS attribute of a TSK_GPS_TRACK artifact. TSK_GPS_TRACK
+ * artifacts are used to record a track, or path, of a GPS-enabled device as a
+ * connected series of track points.
+ *
+ */
+public class GeoTrackPoints implements Iterable<GeoTrackPoints.TrackPoint> {
+
+	private final List<TrackPoint> pointList;
+
+	/**
+	 * Constructs an empty GeoTrackPoints object.
+	 */
+	public GeoTrackPoints() {
+		pointList = new ArrayList<>();
+	}
+
+	/**
+	 * Adds a track point to this list of track points.
+	 *
+	 * @param trackPoint A track point.
+	 */
+	public void addPoint(TrackPoint trackPoint) {
+		if (trackPoint == null) {
+			throw new IllegalArgumentException("addPoint was passed a null track point");
+		}
+
+		pointList.add(trackPoint);
+	}
+
+	@Override
+	public Iterator<TrackPoint> iterator() {
+		return pointList.iterator();
+	}
+
+	/**
+	 * Returns whether or not this list of track points is empty.
+	 *
+	 * @return True or false.
+	 */
+	public boolean isEmpty() {
+		return pointList.isEmpty();
+	}
+
+	/**
+	 * Gets the earliest track point timestamp in this list of track points, if
+	 * timestamps are present.
+	 *
+	 * @return The timestamp in milliseconds from the Java epoch of
+	 *         1970-01-01T00:00:00Z, may be null or zero.
+	 */
+	public Long getStartTime() {
+		List<TrackPoint> orderedPoints = getTimeOrderedPoints();
+		if (orderedPoints != null) {
+			for (TrackPoint point : orderedPoints) {
+				if (point.getTimeStamp() != null) {
+					return point.getTimeStamp();
+				}
+			}
+		}
+		return null;
+	}
+
+	/**
+	 * Gets the latest track point timestamp in this list of track points, if
+	 * timestamps are present.
+	 *
+	 * @return The timestamp in milliseconds from the Java epoch of
+	 *         1970-01-01T00:00:00Z, may be null or zero.
+	 */
+	public Long getEndTime() {
+		List<TrackPoint> orderedPoints = getTimeOrderedPoints();
+		if (orderedPoints != null) {
+			for (int index = orderedPoints.size() - 1; index >= 0; index--) {
+				TrackPoint point = orderedPoints.get(index);
+				if (point.getTimeStamp() != null) {
+					return point.getTimeStamp();
+				}
+			}
+		}
+		return null;
+	}
+
+	/**
+	 * Gets this list of track points as a list ordered by track point
+	 * timestamp.
+	 *
+	 * @return The ordered list of track points.
+	 */
+	private List<TrackPoint> getTimeOrderedPoints() {
+		return pointList.stream().sorted().collect(Collectors.toCollection(ArrayList::new));
+	}
+
+	/**
+	 * 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 TrackPoint extends GeoWaypoints.Waypoint implements Comparable<TrackPoint> {
+
+		@SerializedName("TSK_GEO_VELOCITY")
+		private final Double velocity;
+		@SerializedName("TSK_DISTANCE_FROM_HOMEPOINT")
+		private final Double distanceFromHomePoint;
+		@SerializedName("TSK_DISTANCE_TRAVELED")
+		private final Double distanceTraveled;
+		@SerializedName("TSK_DATETIME")
+		private final Long timestamp;
+
+		/**
+		 * 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              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 TrackPoint(Double latitude,
+				Double longitude,
+				Double altitude,
+				String name,
+				Double velocity,
+				Double distanceFromHomePoint,
+				Double distanceTraveled,
+				Long timestamp) {
+			super(latitude, longitude, altitude, name);
+			this.velocity = velocity;
+			this.distanceFromHomePoint = distanceFromHomePoint;
+			this.distanceTraveled = distanceTraveled;
+			this.timestamp = timestamp;
+		}
+
+		/**
+		 * Gets the velocity of the device at this track point in meters per
+		 * second, if known.
+		 *
+		 * @return The velocity in meters/sec, may be null or zero.
+		 */
+		public Double getVelocity() {
+			return velocity;
+		}
+
+		/**
+		 * Gets the distance of this track point from an established home point,
+		 * if known.
+		 *
+		 * @return The distance in meters, may be null or zero.
+		 */
+		public Double getDistanceFromHomePoint() {
+			return distanceFromHomePoint;
+		}
+
+		/**
+		 * Gets the distance the device has traveled in meters at the time this
+		 * track point was created, if known.
+		 *
+		 * @return The distance traveled in meters, may be null or zero.
+		 */
+		public Double getDistanceTraveled() {
+			return distanceTraveled;
+		}
+
+		/**
+		 * Gets the timestamp of this track point as milliseconds from the Java
+		 * epoch of 1970-01-01T00:00:00Z, if known.
+		 *
+		 * @return The timestamp, may be null or zero.
+		 */
+		public Long getTimeStamp() {
+			return timestamp;
+		}
+
+		@Override
+		public int compareTo(TrackPoint otherTP) {
+			Long otherTimeStamp = otherTP.getTimeStamp();
+
+			if (timestamp == null && otherTimeStamp != null) {
+				return -1;
+			} else if (timestamp != null && otherTimeStamp == null) {
+				return 1;
+			} else {
+				return timestamp.compareTo(otherTP.getTimeStamp());
+			}
+		}
+	}
+
+}

bindings/java/src/org/sleuthkit/datamodel/blackboardutils/attributes/GeoWaypoints.java

+/*
+ * Sleuth Kit Data Model
+ *
+ * Copyright 2020 Basis Technology Corp.
+ * Contact: carrier <at> sleuthkit <dot> org
+ *
+ * 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.
+ */
+package org.sleuthkit.datamodel.blackboardutils.attributes;
+
+import com.google.gson.annotations.SerializedName;
+import java.util.ArrayList;
+import java.util.Iterator;
+import java.util.List;
+
+/**
+ * A GeoWaypoints object is a collection of Waypoint objects. A Waypoint object
+ * 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.
+ *
+ * GeoWaypoints objects are designed to be used as the string value of the
+ * TSK_GEO_WAYPOINTS attribute of a TSK_GPS_ROUTE artifact. TSK_GPS_ROUTE
+ * artifacts are used to record one or more waypoints linked together as a route
+ * to be navigated from waypoint to waypoint.
+ */
+public class GeoWaypoints implements Iterable<GeoWaypoints.Waypoint> {
+
+	private final List<Waypoint> points;
+
+	/**
+	 * Constructs an empty GeoWaypoints object.
+	 */
+	public GeoWaypoints() {
+		points = new ArrayList<>();
+	}
+
+	/**
+	 * Adds a waypoint to this list of waypoints.
+	 *
+	 * @param wayPoint A waypoint.
+	 */
+	public void addPoint(Waypoint wayPoint) {
+		if (wayPoint == null) {
+			throw new IllegalArgumentException("addPoint was passed a null waypoint");
+		}
+
+		points.add(wayPoint);
+	}
+
+	/**
+	 * Returns whether or not this list of waypoints is empty.
+	 *
+	 * @return True or false.
+	 */
+	public boolean isEmpty() {
+		return points.isEmpty();
+	}
+
+	@Override
+	public Iterator<Waypoint> iterator() {
+		return points.iterator();
+	}
+
+	/**
+	 * 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 Waypoint {
+
+		@SerializedName("TSK_GEO_LATITUDE")
+		private final Double latitude;
+		@SerializedName("TSK_GEO_LONGITUDE")
+		private final Double longitude;
+		@SerializedName("TSK_GEO_ALTITUDE")
+		private final Double altitude;
+		@SerializedName("TSK_NAME")
+		private final String name;
+
+		/**
+		 * 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 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 Waypoint(Double latitude, Double longitude, Double altitude, String name) {
+			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;
+			this.longitude = longitude;
+			this.altitude = altitude;
+			this.name = name;
+		}
+
+		/**
+		 * Gets the latitude of this waypoint.
+		 *
+		 * @return The latitude.
+		 */
+		public Double getLatitude() {
+			return latitude;
+		}
+
+		/**
+		 * Gets the longitude of this waypoint.
+		 *
+		 * @return The longitude.
+		 */
+		public Double getLongitude() {
+			return longitude;
+		}
+
+		/**
+		 * Gets the altitude of this waypoint, if available.
+		 *
+		 * @return The altitude, may be null or zero.
+		 */
+		public Double getAltitude() {
+			return altitude;
+		}
+
+		/**
+		 * Gets the name of this waypoint, if available.
+		 *
+		 * @return	The name, may be null or empty.
+		 */
+		public String getName() {
+			return name;
+		}
+	}
+
+}

bindings/java/src/org/sleuthkit/datamodel/blackboardutils/attributes/MessageAttachments.java

@@ -333,7 +333,6 @@ public Long getObjId() {
 		}
 	}
 
-
 	private final Collection<FileAttachment> fileAttachments;
 	private final Collection<URLAttachment> urlAttachments;
 

bindings/java/src/org/sleuthkit/datamodel/blackboardutils/attributes/TskGeoTrackpointsUtil.java

-/*
- * Sleuth Kit Data Model
- *
- * Copyright 2020 Basis Technology Corp.
- * Contact: carrier <at> sleuthkit <dot> org
- *
- * 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.
- */
-package org.sleuthkit.datamodel.blackboardutils.attributes;
-
-import com.google.gson.Gson;
-import com.google.gson.annotations.SerializedName;
-import java.util.ArrayList;
-import java.util.Iterator;
-import java.util.List;
-import java.util.stream.Collectors;
-import org.sleuthkit.datamodel.BlackboardAttribute;
-import org.sleuthkit.datamodel.blackboardutils.attributes.TskGeoTrackpointsUtil.GeoTrackPointList;
-import org.sleuthkit.datamodel.blackboardutils.attributes.TskGeoTrackpointsUtil.GeoTrackPointList.GeoTrackPoint;
-
-/**
- * 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");
-		}
-
-		return new BlackboardAttribute(
-				BlackboardAttribute.ATTRIBUTE_TYPE.TSK_GEO_TRACKPOINTS,
-				moduleName,
-				toJSON(value));
-	}
-
-	@Override
-	public GeoTrackPointList fromAttribute(BlackboardAttribute attribute) {
-		if (attribute == null) {
-			throw new IllegalArgumentException("fromAttribute was passed a null attribute");
-		}
-
-		BlackboardAttribute.ATTRIBUTE_TYPE type = BlackboardAttribute.ATTRIBUTE_TYPE.fromID(attribute.getAttributeType().getTypeID());
-		if (type != BlackboardAttribute.ATTRIBUTE_TYPE.TSK_GEO_TRACKPOINTS) {
-			throw new IllegalArgumentException(String.format("Invalid attribute of type %s passed to fromAttribute method. Attribute of type TSK_GEO_TRACKPOINTS is required", type.getDisplayName()));
-		}
-
-		return fromJSON(attribute.getValueString());
-	}
-
-	/**
-	 * Constructs a GeoTrackPointList object from its JSON representation.
-	 *
-	 * @param json A JSON representation of a GeoTrackPointList.
-	 *
-	 * @return	The GeoTrackPointList object.
-	 */
-	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(json, GeoTrackPointList.class);
-	}
-
-	/**
-	 * Creates a JSON representation of a GeoTrackPointList object.
-	 *
-	 * @param trackPoints A GeoTrackPointList object.
-	 *
-	 * @return The JSON representation of the GeoTrackPointList object.
-	 */
-	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(trackPoints);
-	}
-
-	/**
-	 * 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;
-
-		/**
-		 * Constructs an empty GeoTrackPointList.
-		 */
-		public GeoTrackPointList() {
-			pointList = new ArrayList<>();
-		}
-
-		/**
-		 * Adds a track point to this list of track points.
-		 *
-		 * @param trackPoint A track point.
-		 */
-		public void addPoint(GeoTrackPoint trackPoint) {
-			if (trackPoint == null) {
-				throw new IllegalArgumentException("addPoint was passed a null track point");
-			}
-
-			pointList.add(trackPoint);
-		}
-
-		@Override
-		public Iterator<GeoTrackPoint> iterator() {
-			return pointList.iterator();
-		}
-
-		/**
-		 * Returns whether or not this list of track points is empty.
-		 *
-		 * @return True or false.
-		 */
-		public boolean isEmpty() {
-			return pointList.isEmpty();
-		}
-
-		/**
-		 * Gets the earliest track point timestamp in this list of track points,
-		 * if timestamps are present.
-		 *
-		 * @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();
-			if (orderedPoints != null) {
-				for (GeoTrackPoint point : orderedPoints) {
-					if (point.getTimeStamp() != null) {
-						return point.getTimeStamp();
-					}
-				}
-			}
-			return null;
-		}
-
-		/**
-		 * Gets the latest track point timestamp in this list of track points,
-		 * if timestamps are present.
-		 *
-		 * @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();
-			if (orderedPoints != null) {
-				for (int index = orderedPoints.size() - 1; index >= 0; index--) {
-					GeoTrackPoint point = orderedPoints.get(index);
-					if (point.getTimeStamp() != null) {
-						return point.getTimeStamp();
-					}
-				}
-			}
-			return null;
-		}
-
-		/**
-		 * Gets this list of track points as a list ordered by track point
-		 * timestamp.
-		 *
-		 * @return The ordered list of track points.
-		 */
-		private List<GeoTrackPoint> getTimeOrderedPoints() {
-			return pointList.stream().sorted().collect(Collectors.toCollection(ArrayList::new));
-		}
-
-		/**
-		 * 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<GeoTrackPoint> {
-
-			@SerializedName("TSK_GEO_VELOCITY")
-			private final Double velocity;
-			@SerializedName("TSK_DISTANCE_FROM_HOMEPOINT")
-			private final Double distanceFromHomePoint;
-			@SerializedName("TSK_DISTANCE_TRAVELED")
-			private final Double distanceTraveled;
-			@SerializedName("TSK_DATETIME")
-			private final Long timestamp;
-
-			/**
-			 * 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              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,
-					Double altitude,
-					String name,
-					Double velocity,
-					Double distanceFromHomePoint,
-					Double distanceTraveled,
-					Long timestamp) {
-				super(latitude, longitude, altitude, name);
-				this.velocity = velocity;
-				this.distanceFromHomePoint = distanceFromHomePoint;
-				this.distanceTraveled = distanceTraveled;
-				this.timestamp = timestamp;
-			}
-
-			/**
-			 * Gets the velocity of the device at this track point in meters per
-			 * second, if known.
-			 *
-			 * @return The velocity in meters/sec, may be null or zero.
-			 */
-			public Double getVelocity() {
-				return velocity;
-			}
-
-			/**
-			 * Gets the distance of this track point from an established home
-			 * point, if known.
-			 *
-			 * @return The distance in meters, may be null or zero.
-			 */
-			public Double getDistanceFromHomePoint() {
-				return distanceFromHomePoint;
-			}
-
-			/**
-			 * Gets the distance the device has traveled in meters at the time
-			 * this track point was created, if known.
-			 *
-			 * @return The distance traveled in meters, may be null or zero.
-			 */
-			public Double getDistanceTraveled() {
-				return distanceTraveled;
-			}
-
-			/**
-			 * Gets the timestamp of this track point as milliseconds from the
-			 * Java epoch of 1970-01-01T00:00:00Z, if known.
-			 *
-			 * @return The timestamp, may be null or zero.
-			 */
-			public Long getTimeStamp() {
-				return timestamp;
-			}
-
-			@Override
-			public int compareTo(GeoTrackPoint otherTP) {
-				Long otherTimeStamp = otherTP.getTimeStamp();
-
-				if (timestamp == null && otherTimeStamp != null) {
-					return -1;
-				} else if (timestamp != null && otherTimeStamp == null) {
-					return 1;
-				} else {
-					return timestamp.compareTo(otherTP.getTimeStamp());
-				}
-			}
-		}
-	}
-}

bindings/java/src/org/sleuthkit/datamodel/blackboardutils/attributes/TskGeoWaypointsUtil.java

-/*
- * Sleuth Kit Data Model
- *
- * Copyright 2020 Basis Technology Corp.
- * Contact: carrier <at> sleuthkit <dot> org
- *
- * 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.
- */
-package org.sleuthkit.datamodel.blackboardutils.attributes;
-
-import com.google.gson.Gson;
-import com.google.gson.annotations.SerializedName;
-import java.util.ArrayList;
-import java.util.Iterator;
-import java.util.List;
-import org.sleuthkit.datamodel.BlackboardAttribute;
-import org.sleuthkit.datamodel.blackboardutils.attributes.TskGeoWaypointsUtil.GeoWaypointList;
-import org.sleuthkit.datamodel.blackboardutils.attributes.TskGeoWaypointsUtil.GeoWaypointList.GeoWaypoint;
-
-/**
- * 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");
-		}
-
-		return new BlackboardAttribute(
-				BlackboardAttribute.ATTRIBUTE_TYPE.TSK_GEO_WAYPOINTS,
-				moduleName,
-				toJSON(value));
-	}
-
-	@Override
-	public GeoWaypointList fromAttribute(BlackboardAttribute attribute) {
-		if (attribute == null) {
-			throw new IllegalArgumentException("fromAttribute was pass a null list");
-		}
-
-		BlackboardAttribute.ATTRIBUTE_TYPE type = BlackboardAttribute.ATTRIBUTE_TYPE.fromID(attribute.getAttributeType().getTypeID());
-		if (type != BlackboardAttribute.ATTRIBUTE_TYPE.TSK_GEO_WAYPOINTS) {
-			throw new IllegalArgumentException(String.format("Invalid attribute of type %s passed to fromAttribute method. Attribute of type TSK_GEO_WAYPOINTS is required", type.getDisplayName()));
-		}
-
-		return fromJSON(attribute.getValueString());
-	}
-
-	/**
-	 * Constructs a GeoWaypointList object from its JSON representation.
-	 *
-	 * @param json A JSON representation of a GeoWaypointList.
-	 *
-	 * @return	The GeoWaypointList object.
-	 */
-	private static GeoWaypointList fromJSON(String json) {
-		if (json == null || json.isEmpty()) {
-			return null;
-		}
-
-		return (new Gson()).fromJson(json, GeoWaypointList.class);
-	}
-
-	/**
-	 * Creates a JSON representation of a GeoWaypointList object.
-	 *
-	 * @param waypoints A GeoWaypointList object.
-	 *
-	 * @return The JSON representation of the GeoWaypointList object.
-	 */
-	private static String toJSON(GeoWaypointList waypoints) {
-		Gson gson = new Gson();
-		return gson.toJson(waypoints);
-	}
-
-	/**
-	 * 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 waypoint to this list of waypoints.
-		 *
-		 * @param wayPoint A waypoint.
-		 */
-		public void addPoint(GeoWaypoint wayPoint) {
-			if (wayPoint == null) {
-				throw new IllegalArgumentException("addPoint was passed a null waypoint");
-			}
-
-			points.add(wayPoint);
-		}
-
-		/**
-		 * Returns whether or not this list of waypoints is empty.
-		 *
-		 * @return True or false.
-		 */
-		public boolean isEmpty() {
-			return points.isEmpty();
-		}
-
-		@Override
-		public Iterator<GeoWaypointList.GeoWaypoint> iterator() {
-			return points.iterator();
-		}
-
-		/**
-		 * 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 {
-
-			@SerializedName("TSK_GEO_LATITUDE")
-			private final Double latitude;
-			@SerializedName("TSK_GEO_LONGITUDE")
-			private final Double longitude;
-			@SerializedName("TSK_GEO_ALTITUDE")
-			private final Double altitude;
-			@SerializedName("TSK_NAME")
-			private final String name;
-
-			/**
-			 * 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 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) {
-					throw new IllegalArgumentException("Constructor was passed null latitude");
-				}
-
-				if (longitude == null) {
-					throw new IllegalArgumentException("Constructor was passed null longitude");
-				}
-
-				this.latitude = latitude;
-				this.longitude = longitude;
-				this.altitude = altitude;
-				this.name = name;
-			}
-
-			/**
-			 * Gets the latitude of this waypoint.
-			 *
-			 * @return The latitude.
-			 */
-			public Double getLatitude() {
-				return latitude;
-			}
-
-			/**
-			 * Gets the longitude of this waypoint.
-			 *
-			 * @return The longitude.
-			 */
-			public Double getLongitude() {
-				return longitude;
-			}
-
-			/**
-			 * Get the altitude of this waypoint, if available.
-			 *
-			 * @return The altitude, may be null or zero.
-			 */
-			public Double getAltitude() {
-				return altitude;
-			}
-
-			/**
-			 * Get the name of this waypoint, if available.
-			 *
-			 * @return	The name, may be null or empty.
-			 */
-			public String getName() {
-				return name;
-			}
-		}
-	}
-}