Merge pull request #1201 from millmanorama/932-CommunicationsManager_API_cleanup

932 communications manager api review

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

 /*
  * Sleuth Kit Data Model
  *
- * Copyright 2016 Basis Technology Corp.
+ * Copyright 2016-18 Basis Technology Corp.
  * Contact: carrier <at> sleuthkit <dot> org
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
@@ -27,7 +27,7 @@
  * number, phone, Application, Web-site login, etc. Accounts are unique to the
  * case.
  */
-public class Account {
+public final class Account {
 
 	/**
 	 * primary key in the Accounts table, unique at the case-level
@@ -36,14 +36,13 @@ public class Account {
 
 	private final Account.Type accountType;
 	/**
-	 * id of the account, specific to the accounts type. For example: email address,
-	 * phone number, or website user name.
+	 * id of the account, specific to the accounts type. For example: email
+	 * address, phone number, or website user name.
 	 */
 	private final String typeSpecificID;
 
 	public static final class Type {
 
-		private static final long serialVersionUID = 1L;
 		//JIRA-900:Should the display names of predefined types be internationalized?
 		public static final Account.Type CREDIT_CARD = new Type("CREDIT_CARD", "Credit Card");
 		public static final Account.Type DEVICE = new Type("DEVICE", "Device");
@@ -92,6 +91,11 @@ public String getTypeName() {
 			return this.typeName;
 		}
 
+		/**
+		 * Gets the display name
+		 *
+		 * @return The display name.
+		 */
 		public String getDisplayName() {
 			return displayName;
 		}

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

 /*
  * Sleuth Kit Data Model
  *
- * Copyright 2017 Basis Technology Corp.
+ * Copyright 2017-18 Basis Technology Corp.
  * Contact: carrier <at> sleuthkit <dot> org
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
@@ -24,7 +24,7 @@
  * There is a 1:M:N relationship between 
  * Account, AccountDeviceInstance &  AccountFileInstance
  */
-public class AccountDeviceInstance {
+public final class AccountDeviceInstance {
 	private final Account account;				
 	private final String deviceID;	
 	
@@ -79,6 +79,4 @@ public boolean equals(Object obj) {
 		}
 		return true;
 	}
-	
-	
 }

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

 /*
  * Sleuth Kit Data Model
  *
- * Copyright 2017 Basis Technology Corp.
+ * Copyright 2017-18 Basis Technology Corp.
  * Contact: carrier <at> sleuthkit <dot> org
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
@@ -21,16 +21,17 @@
 import java.util.Collection;
 
 /**
- * An instance of an Account in a specific file. 
- * An Account may be found in multiple Content
- * objects (such as different databases) on a single device.
+ * An instance of an Account in a specific file. An Account may be found in
+ * multiple Content objects (such as different databases) on a single device.
  * There is a 1:N relationship between Account objects and AccountFileInstance
  * objects. A TSK_ACCOUNT artifact is created for every account file instance.
  *
- * AccountFileInstances can optionally have BlackboardAttributes to store more details.
+ * AccountFileInstances can optionally have BlackboardAttributes to store more
+ * details.
  */
-public class AccountFileInstance {
-	private final BlackboardArtifact artifact; 
+public final class AccountFileInstance {
+
+	private final BlackboardArtifact artifact;
 	private final Account account;
 
 	AccountFileInstance(BlackboardArtifact artifact, Account account) throws TskCoreException {
@@ -41,10 +42,10 @@ public class AccountFileInstance {
 	/**
 	 * Gets the first occurrence of an attribute by type.
 	 *
-	 * @param attrType The attribute type. 
-	 * 
+	 * @param attrType The attribute type.
+	 *
 	 * @return The attribute, or null if no attribute of the given type exists.
-	 * 
+	 *
 	 * @throws TskCoreException if an there is an error getting the attribute.
 	 */
 	public BlackboardAttribute getAttribute(BlackboardAttribute.ATTRIBUTE_TYPE attrType) throws TskCoreException {
@@ -52,10 +53,11 @@ public BlackboardAttribute getAttribute(BlackboardAttribute.ATTRIBUTE_TYPE attrT
 	}
 
 	/**
-	 * Adds an attribute.  It is faster to add them as part of a list.
+	 * Adds an attribute. It is faster to add multiple attributes as a
+	 * collection using addAttributes().
 	 *
 	 * @param bbatr The attribute to add.
-	 * 
+	 *
 	 * @throws TskCoreException if an there is an error adding the attribute.
 	 */
 	public void addAttribute(BlackboardAttribute bbatr) throws TskCoreException {
@@ -66,25 +68,30 @@ public void addAttribute(BlackboardAttribute bbatr) throws TskCoreException {
 	 * Adds a collection of attributes
 	 *
 	 * @param bbatrs The collection of attributes to add.
-	 * 
+	 *
 	 * @throws TskCoreException if an there is an error adding the attributes.
 	 */
 	public void addAttributes(Collection<BlackboardAttribute> bbatrs) throws TskCoreException {
 		this.artifact.addAttributes(bbatrs);
 	}
-	
+
 	/**
 	 * Gets the underlying Account for this instance.
 	 *
 	 * @return The account.
-	 * 
+	 *
 	 * @throws TskCoreException if an there is an error getting the account.
 	 */
 	public Account getAccount() throws TskCoreException {
 		return this.account;
 	}
-	
-	long getDataSourceObjectID(){
+
+	/**
+	 * Get the object ID of the artifact this account file instance maps to.
+	 *
+	 * @return A Data Source Object ID
+	 */
+	long getDataSourceObjectID() {
 		return artifact.getDataSourceObjectID();
 	}
 }

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

@@ -20,17 +20,30 @@
 
 /**
  * Class representing an unordered pair of account device instances. <a,b> is
- * same as <b,a>
+ * same as <b,a>. First and second are used to distinguish the two accounts, but
+ * do not imply an order.
  */
 public final class AccountPair {
 
 	private final AccountDeviceInstance account1;
 	private final AccountDeviceInstance account2;
 
+	/**
+	 * Get the first AccountDeviceInstance. First doesn't imply order and is
+	 * simply used to distinguish the two accounts.
+	 *
+	 * @return The first AccountDeviceInstance.
+	 */
 	public AccountDeviceInstance getFirst() {
 		return account1;
 	}
 
+	/**
+	 * Get the second AccountDeviceInstance. Second doesn't imply order and is
+	 * simply used to distinguish the two accounts.
+	 *
+	 * @return The second AccountDeviceInstance.
+	 */
 	public AccountDeviceInstance getSecond() {
 		return account2;
 	}
@@ -57,5 +70,4 @@ public boolean equals(Object other) {
 		return (account1.equals(otherPair.account1) && account2.equals(otherPair.account2))
 				|| (account1.equals(otherPair.account2) && account2.equals(otherPair.account1));
 	}
-
 }

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

 /*
  * Sleuth Kit Data Model
  *
- * Copyright 2011-2017 Basis Technology Corp.
+ * Copyright 2017-2018 Basis Technology Corp.
  * Contact: carrier <at> sleuthkit <dot> org
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
@@ -29,21 +29,23 @@
 
 /**
  * Defines an aggregate of filters to apply to a CommunicationsManager query.
- *
  */
 final public class CommunicationsFilter {
 
+	/**
+	 * For now all filters are anded together
+	 */
 	private final List<SubFilter> andFilters;
-	// RAMAN TBD: figure out OR filters, I don't think we need any
-	//private final List<SubFilter> orFilters;
 
+	/**
+	 * Create a new empty CommunicationsFilter.
+	 */
 	public CommunicationsFilter() {
 		this(Collections.<SubFilter>emptyList());
 	}
 
 	CommunicationsFilter(List<? extends SubFilter> andSubFilters) {
 		this.andFilters = new ArrayList<SubFilter>(andSubFilters);
-		//this.orFilters = new ArrayList<SubFilter>;
 	}
 
 	/**
@@ -72,7 +74,7 @@ public void addAndFilter(SubFilter subFilter) {
 	/**
 	 * Unit level filter.
 	 */
-	static abstract class SubFilter {
+	 static abstract class SubFilter {
 
 		/**
 		 * Returns a string description of the filter.
@@ -92,7 +94,7 @@ static abstract class SubFilter {
 	}
 
 	/**
-	 * Filters communications by relationship type.
+	 * Filters relationships by relationship type.
 	 *
 	 */
 	final public static class RelationshipTypeFilter extends SubFilter {
@@ -135,6 +137,9 @@ public String getSQL(CommunicationsManager commsManager) {
 		}
 	}
 
+	/**
+	 * Filters communications by date range
+	 */
 	final public static class DateRangeFilter extends SubFilter {
 
 		private final long startDate;
@@ -189,7 +194,7 @@ public String getSQL(CommunicationsManager commsManager) {
 	}
 
 	/**
-	 * Filter communications by account type.
+	 * Filter accounts and relationships by account type.
 	 *
 	 */
 	final public static class AccountTypeFilter extends SubFilter {

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

@@ -34,8 +34,7 @@
  * A relationship between Accounts, such as a communication ( email, sms, phone
  * call (call log) ) or presence in a contact book.
  */
-public class Relationship {
-
+public final class Relationship {
 
 	public static final class Type {
 
@@ -79,14 +78,29 @@ private Type(String name, String displayName, int id) {
 			this.typeID = id;
 		}
 
+		/**
+		 * Get the display name.
+		 *
+		 * @return The display name.
+		 */
 		public String getDisplayName() {
 			return displayName;
 		}
 
+		/**
+		 * Get the unique type name
+		 *
+		 * @return The unique type name.
+		 */
 		public String getTypeName() {
 			return typeName;
 		}
 
+		/**
+		 * Get the id of this type.
+		 *
+		 * @return The type ID.
+		 */
 		public int getTypeID() {
 			return typeID;
 		}
@@ -122,7 +136,7 @@ public boolean equals(Object obj) {
 
 		@Override
 		public String toString() {
-			return "{" + this.getClass().getName() + ": typeID=" + typeName + " displayName=" + this.displayName + ", typeName=" + this.typeName + "}";
+			return "{" + this.getClass().getName() + ": typeID=" + typeName + ", displayName=" + this.displayName + ", typeName=" + this.typeName + "}";
 		}
 
 		/**