Added comm mgr comments

bindings/java/doxygen/communications.dox

 /*! \page mod_compage Communications 
 
+
+
+NOTE: This is a work in progress
+
+
 \section jni_com_overview Overview
 
-Work in progress
+The Java code and database in Sleuth Kit contain special classes and tables to deal with communications between two parties. This page outlines what a developer should do when they are parsing communications data so that it can be properly displayed and used by other code (such as the Autopsy Communications UI). 
+
+\section jni_com_types Terminology
+
+First, lets cover the terminology that we use. 
+
+
+An <b>Account</b> is an entity with a type and an identifier that is unique to the type.  Common examples of types include:
+- Credit Card (and the unique identifier is the credit card number)
+- Email (and the unique identifier is the email address)
+- Phone (and the unique identifier is the phone number)
+- Twitter (with a unique identifier of the login)
+- ...
+
+Accounts are found in forensics when parsing structured data (such as email messages) or keyword searching.
+
+
+Two accounts have a <b>relationship</b> if they are believed to have communicated in some way.  Examples of interactions that cause a relationship are:
+- Being part of the same email message
+- Being in a call log
+- Being in an address book
+
+When there are multiple people involved with an email message, a relationship is made between each of them.  For example, if A sends a message to B and CC:s C, then there will be relationships between A <-> B, A <-> C, and B <-> C.  Relationships in The Sleuth Kit are not directional. 
+
+A <b>relationship source</b> is where we learned about the relationship.  This typically comes from Blackboard Artifacts, but may come from generic files in the future. 
+
+\section jni_com_add Adding Communication Information to Database
+
+Now lets cover what you should do when you are parsing some communications data and want to store it in the TSK database.  Let's assume we are parsing a smart phone app that has messages. 
+
+When you encounter a message, the first thing to do is store information about the accounts.  TSK wants to know about each <i>file</i> that had a reference of the account.   You should call X…..
+
+
+
+
+\section OTHER ……
+
 
 Things to cover:
 - What to do when you encounter an Account.

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

@@ -19,7 +19,7 @@
 package org.sleuthkit.datamodel;
 
 /**
- * Encapsulates an Account existing on a given device. 
+ * Encapsulates an Account existing on a specific device.
  * 
  * There is a 1:M:N relationship between 
  * Account, AccountDeviceInstance &  AccountFileInstance
@@ -34,7 +34,7 @@ public class AccountDeviceInstance {
 	}
 
 	/**
-	 *  Returns the underlying account
+	 *  Returns the underlying Account
 	 * 
 	 * @return account
 	 */
@@ -43,7 +43,7 @@ public Account getAccount(){
 	}
 	
 	/**
-	 *  Returns the device Id
+	 *  Returns the device Id the Account existed on
 	 * 
 	 * @return device id
 	 */

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

@@ -22,11 +22,12 @@
 
 /**
  * An instance of an Account in a specific file. 
- * An account may be found in multiple content
- * objects, so there can be up to one account instance per content object, 
- * and there is a 1:N relationship between Account objects and AccountFileInstance
- * objects. Currently, there is an underlying TSK_ACCOUNT artifact for every 
- * account instance. This may change in the future.
+ * 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.
  */
 public class AccountFileInstance {
 	private final BlackboardArtifact artifact; 
@@ -38,8 +39,7 @@ public class AccountFileInstance {
 	}
 
 	/**
-	 * Gets the first occurrence of an attribute of the account instance
-	 * of a given type. 
+	 * Gets the first occurrence of an attribute by type.
 	 *
 	 * @param attrType The attribute type. 
 	 * 
@@ -52,8 +52,7 @@ public BlackboardAttribute getAttribute(BlackboardAttribute.ATTRIBUTE_TYPE attrT
 	}
 
 	/**
-	 * Adds an attribute to the account instance.  It is faster to 
-	 * add them as part of a list.
+	 * Adds an attribute.  It is faster to add them as part of a list.
 	 *
 	 * @param bbatr The attribute to add.
 	 * 
@@ -64,7 +63,7 @@ public void addAttribute(BlackboardAttribute bbatr) throws TskCoreException {
 	}
 
 	/**
-	 * Adds a collection of attributes to the account instance
+	 * Adds a collection of attributes
 	 *
 	 * @param bbatrs The collection of attributes to add.
 	 * 
@@ -75,7 +74,7 @@ public void addAttributes(Collection<BlackboardAttribute> bbatrs) throws TskCore
 	}
 	
 	/**
-	 * Gets the account of which this object is an instance.
+	 * Gets the underlying Account for this instance.
 	 *
 	 * @return The account.
 	 * 

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

@@ -173,9 +173,11 @@ SleuthkitCase getSleuthkitCase() {
 	}
 
 	/**
-	 * Add an account type. Returns the type if it is already defined.
+	 * Add a custom account type that is not already defined in Account.Type.
+     * Will not allow duplicates and will return existing type if the name is
+     * already defined.
 	 *
-	 * @param accountTypeName account type name
+	 * @param accountTypeName account type that must be unique
 	 * @param displayName     account type display name
 	 *
 	 * @return Account.Type
@@ -340,13 +342,13 @@ public Account getAccount(Account.Type accountType, String accountUniqueID) thro
 //		return accountInstance;
 //	}
 	/**
-	 * Add relationships between the sender and recipient account instances. All
-	 * accounts the relationship must be from the same data source.
+	 * Add one or more relationships between the sender and recipient account instances. All
+	 * account instances must be from the same data source.
 	 *
 	 * @param sender               sender account
 	 * @param recipients           list of recipients
-	 * @param relationshipArtifact relationship artifact
-	 * @param relationshipType     The type of relationship to be created
+	 * @param sourceArtifact       Artifact that relationships were derived from
+	 * @param relationshipType     The type of relationships to be created
 	 * @param dateTime             Date of communications/relationship, as epoch
 	 *                             seconds
 	 *
@@ -356,20 +358,20 @@ public Account getAccount(Account.Type accountType, String accountUniqueID) thro
 	 *                                                  and the relationship are
 	 *                                                  not from the same data
 	 *                                                  source, or if the
-	 *                                                  relationshipArtifact and
+	 *                                                  sourceArtifact and
 	 *                                                  relationshipType are not
 	 *                                                  compatible.
 	 */
 	public void addRelationships(AccountFileInstance sender, List<AccountFileInstance> recipients,
-			BlackboardArtifact relationshipArtifact, Relationship.Type relationshipType, long dateTime) throws TskCoreException, TskDataException {
+			BlackboardArtifact sourceArtifact, Relationship.Type relationshipType, long dateTime) throws TskCoreException, TskDataException {
 
-		if (relationshipType.isCreatableFrom(relationshipArtifact) == false) {
+		if (relationshipType.isCreatableFrom(sourceArtifact) == false) {
 			throw new TskDataException("Can not make a " + relationshipType.getDisplayName()
-					+ " relationship from a" + relationshipArtifact.getDisplayName());
+					+ " relationship from a" + sourceArtifact.getDisplayName());
 		}
 
 		/*
-		 * Enforce that all accounts and the relationship between them on from
+		 * Enforce that all accounts and the relationship between them are from
 		 * the same 'source'. This is required for the queries to work
 		 * correctly.
 		 */
@@ -378,17 +380,17 @@ public void addRelationships(AccountFileInstance sender, List<AccountFileInstanc
 
 		if (null != sender) {
 			accountIDs.add(sender.getAccount().getAccountID());
-			if (sender.getDataSourceObjectID() != relationshipArtifact.getDataSourceObjectID()) {
+			if (sender.getDataSourceObjectID() != sourceArtifact.getDataSourceObjectID()) {
 				throw new TskDataException("Sender and relationship are from different data sources :"
-						+ "Sender source ID" + sender.getDataSourceObjectID() + " != relationship source ID" + relationshipArtifact.getDataSourceObjectID());
+						+ "Sender source ID" + sender.getDataSourceObjectID() + " != relationship source ID" + sourceArtifact.getDataSourceObjectID());
 			}
 		}
 
 		for (AccountFileInstance recipient : recipients) {
 			accountIDs.add(recipient.getAccount().getAccountID());
-			if (recipient.getDataSourceObjectID() != relationshipArtifact.getDataSourceObjectID()) {
+			if (recipient.getDataSourceObjectID() != sourceArtifact.getDataSourceObjectID()) {
 				throw new TskDataException("Recipient and relationship are from different data sources :"
-						+ "Recipient source ID" + recipient.getDataSourceObjectID() + " != relationship source ID" + relationshipArtifact.getDataSourceObjectID());
+						+ "Recipient source ID" + recipient.getDataSourceObjectID() + " != relationship source ID" + sourceArtifact.getDataSourceObjectID());
 			}
 		}
 
@@ -399,12 +401,12 @@ public void addRelationships(AccountFileInstance sender, List<AccountFileInstanc
 			try {
 				UnorderedAccountPair accountPair = iter.next();
 				addAccountsRelationship(accountPair.getFirst(), accountPair.getSecond(),
-						relationshipArtifact, relationshipType, dateTime);
+						sourceArtifact, relationshipType, dateTime);
 			} catch (TskCoreException ex) {
-				LOGGER.log(Level.WARNING, "Could not get timezone for image", ex); //NON-NLS
+                // @@@ This should probably not be caught and instead we stop adding
+				LOGGER.log(Level.WARNING, "Error adding relationship", ex); //NON-NLS
 			}
 		}
-
 	}
 
 	/**
@@ -464,14 +466,14 @@ private Account getOrCreateAccount(Account.Type accountType, String accountUniqu
 
 	/**
 	 * Get the blackboard artifact for the given account type, account ID, and
-	 * source file. Create an artifact and return that, of a matching doesn't
-	 * exists
+	 * source file. Create an artifact if it doesn't already exist.
 	 *
 	 * @param accountType     account type
-	 * @param accountUniqueID accountID
+	 * @param accountUniqueID Unique account ID (such as email address)
+     * @param moduleName        module name that found this instance (for the artifact)
 	 * @param sourceFile		    Source file (for the artifact)
 	 *
-	 * @return blackboard artifact, returns NULL is no matching account found
+	 * @return blackboard artifact for the instance
 	 *
 	 * @throws TskCoreException exception thrown if a critical error occurs
 	 *                          within TSK core
@@ -569,6 +571,7 @@ public Account.Type getAccountType(String accountTypeName) throws TskCoreExcepti
 		if (this.typeNameToAccountTypeMap.containsKey(accountTypeName)) {
 			return this.typeNameToAccountTypeMap.get(accountTypeName);
 		}
+        
 		CaseDbConnection connection = db.getConnection();
 		db.acquireSingleUserCaseReadLock();
 		Statement s = null;
@@ -689,7 +692,8 @@ private void addAccountsRelationship(long account1_id, long account2_id, Blackbo
 	}
 
 	/**
-	 * Returns a list of AccountDeviceInstances that have any relationships.
+	 * Returns a list of AccountDeviceInstances that at least one relationship that meets
+     * the criteria listed in the filters.
 	 *
 	 * Applicable filters: DeviceFilter, AccountTypeFilter, DateRangeFilter,
 	 * RelationshipTypeFilter
@@ -794,12 +798,12 @@ public List<AccountDeviceInstance> getAccountDeviceInstancesWithRelationships(Co
 	}
 
 	/**
-	 * Get the number of unique relationship sources found for the given account
-	 * device instance.
-	 *
+	 * Get the number of unique relationship sources (such as EMAIL artifacts) associated with
+     * an account on a given device (AccountDeviceInstance) that meet the filter criteria.
+     *
 	 * Applicable filters: RelationshipTypeFilter, DateRangeFilter
 	 *
-	 * @param accountDeviceInstance Account Device.
+	 * @param accountDeviceInstance Account of interest
 	 * @param filter                Filters to apply.
 	 *
 	 * @return number of account relationships found for this account.
@@ -852,8 +856,8 @@ public long getRelationshipSourcesCount(AccountDeviceInstance accountDeviceInsta
 	}
 
 	/**
-	 * Get the unique relationship sources found for the given account device
-	 * instances.
+     * Get the unique relationship sources (such as EMAIL artifacts) associated with an
+     * account on a given device (AccountDeviceInstance) that meet the filter criteria.
 	 *
 	 * Applicable filters: RelationshipTypeFilter, DateRangeFilter
 	 *