Javadocs and unit tests.

components/net/sf/briar/db/DatabaseComponentImpl.java

@@ -15,6 +15,10 @@ import net.sf.briar.api.protocol.MessageId;
 
 import com.google.inject.Provider;
 
+/**
+ * Abstract superclass containing code shared by ReadWriteLockDatabaseComponent
+ * and SynchronizedDatabaseComponent.
+ */
 abstract class DatabaseComponentImpl<Txn> implements DatabaseComponent {
 
 	private static final Logger LOG =
@@ -35,9 +39,17 @@ abstract class DatabaseComponentImpl<Txn> implements DatabaseComponent {
 		startCleaner();
 	}
 
+	/**
+	 * Removes the oldest messages from the database, with a total size less
+	 * than or equal to the given size.
+	 */
 	protected abstract void expireMessages(long size) throws DbException;
 
-	// Locking: messages write
+	/**
+	 * Calculates and returns the sendability score of a message.
+	 * <p>
+	 * Locking: messages write.
+	 */
 	private int calculateSendability(Txn txn, Message m) throws DbException {
 		int sendability = 0;
 		// One point for a good rating
@@ -51,6 +63,12 @@ abstract class DatabaseComponentImpl<Txn> implements DatabaseComponent {
 		return sendability;
 	}
 
+	/**
+	 * Checks how much free storage space is available to the database, and if
+	 * necessary expires old messages until the free space is at least
+	 * MIN_FREE_SPACE. While the free space is less than CRITICAL_FREE_SPACE,
+	 * operations that attempt to store messages in the database will block.
+	 */
 	private void checkFreeSpaceAndClean() throws DbException {
 		long freeSpace = db.getFreeSpace();
 		while(freeSpace < MIN_FREE_SPACE) {
@@ -74,7 +92,11 @@ abstract class DatabaseComponentImpl<Txn> implements DatabaseComponent {
 		}
 	}
 
-	// Locking: contacts read
+	/**
+	 * Returns true iff the database contains the given contact.
+	 * <p>
+	 * Locking: contacts read.
+	 */
 	protected boolean containsContact(ContactId c) throws DbException {
 		Txn txn = db.startTransaction();
 		try {
@@ -87,14 +109,24 @@ abstract class DatabaseComponentImpl<Txn> implements DatabaseComponent {
 		}
 	}
 
-	// Locking: contacts read, messages write, messageStatuses write
+	/**
+	 * Removes the given message (and all associated state) from the database. 
+	 * <p>
+	 * Locking: contacts read, messages write, messageStatuses write.
+	 */
 	protected void removeMessage(Txn txn, MessageId id) throws DbException {
 		Integer sendability = db.getSendability(txn, id);
 		assert sendability != null;
+		// If the message is sendable, deleting it may affect its ancestors'
+		// sendability (backward inclusion)
 		if(sendability > 0) updateAncestorSendability(txn, id, false);
 		db.removeMessage(txn, id);
 	}
 
+	/**
+	 * Returns true iff the amount of free storage space available to the
+	 * database should be checked.
+	 */
 	private boolean shouldCheckFreeSpace() {
 		synchronized(spaceLock) {
 			long now = System.currentTimeMillis();
@@ -117,6 +149,12 @@ abstract class DatabaseComponentImpl<Txn> implements DatabaseComponent {
 		return false;
 	}
 
+	/**
+	 * Starts a new thread to monitor the amount of free storage space
+	 * available to the database and expire old messages as necessary.
+	 * <p>
+	 * FIXME: The thread implementation should be factored out.
+	 */
 	private void startCleaner() {
 		Runnable cleaner = new Runnable() {
 			public void run() {
@@ -140,7 +178,14 @@ abstract class DatabaseComponentImpl<Txn> implements DatabaseComponent {
 		new Thread(cleaner).start();
 	}
 
-	// Locking: contacts read, messages write, messageStatuses write
+	/**
+	 * If the given message is already in the database, marks it as seen by the
+	 * sender and returns false. Otherwise stores the message, updates the
+	 * sendability of its ancestors if necessary, marks the message as seen by
+	 * the sender and unseen by all other contacts, and returns true.
+	 * <p>
+	 * Locking: contacts read, messages write, messageStatuses write.
+	 */
 	protected boolean storeMessage(Txn txn, Message m, ContactId sender)
 	throws DbException {
 		boolean added = db.addMessage(txn, m);
@@ -164,7 +209,15 @@ abstract class DatabaseComponentImpl<Txn> implements DatabaseComponent {
 		return added;
 	}
 
-	// Locking: messages write
+	/**
+	 * Iteratively updates the sendability of a message's ancestors to reflect
+	 * a change in the message's sendability. Returns the number of ancestors
+	 * that have changed from sendable to not sendable, or vice versa.
+	 * <p>
+	 * Locking: messages write.
+	 * @param increment True if the message's sendability has changed from 0 to
+	 * greater than 0, or false if it has changed from greater than 0 to 0.
+	 */
 	private int updateAncestorSendability(Txn txn, MessageId m,
 			boolean increment) throws DbException {
 		int affected = 0;
@@ -191,7 +244,14 @@ abstract class DatabaseComponentImpl<Txn> implements DatabaseComponent {
 		return affected;
 	}
 
-	// Locking: messages write
+	/**
+	 * Updates the sendability of all messages written by the given author, and
+	 * the ancestors of those messages if necessary.
+	 * <p>
+	 * Locking: messages write.
+	 * @param increment True if the user's rating for the author has changed
+	 * from not good to good, or false if it has changed from good to not good.
+	 */
 	protected void updateAuthorSendability(Txn txn, AuthorId a,
 			boolean increment) throws DbException {
 		int direct = 0, indirect = 0;
@@ -217,6 +277,11 @@ abstract class DatabaseComponentImpl<Txn> implements DatabaseComponent {
 				+ indirect + " indirectly");
 	}
 
+	/**
+	 * Blocks until messages are allowed to be stored in the database. The
+	 * storage of messages is not allowed while the amount of free storage
+	 * space available to the database is less than CRITICAL_FREE_SPACE.
+	 */
 	protected void waitForPermissionToWrite() {
 		synchronized(writeLock) {
 			while(!writesAllowed) {