Add documentation to the alert system, and refactor to use the

TwitterClient

src/com/uncc/gameday/alerts/Alert.java

@@ -59,6 +59,11 @@ public class Alert {
 		return this.message;
 	}
 	
+	/**
+	 * Helper method to make displaying an alert on the statusbar easy
+	 *
+	 * @param ctx - The context needed to display the alert.
+	 */
 	public void displayNotification(Context ctx) {
 		NotificationCompat.Builder builder = new NotificationCompat.Builder(ctx)
 			.setSmallIcon(R.drawable.ic_launcher)

src/com/uncc/gameday/alerts/AlertDB.java

@@ -12,22 +12,45 @@ import android.database.sqlite.SQLiteOpenHelper;
 
 /* Responsible for handling persistence/fetching of alerts */
 
+/**
+ * The Class AlertDB.
+ */
 public class AlertDB extends SQLiteOpenHelper {
 	
+	/** The Constant DATABASE_VERSION. */
 	private static final int DATABASE_VERSION = 1;
+	
+	/** The Constant DATABASE_NAME. */
 	private static final String DATABASE_NAME = "AlertDataBase";
+	
+	/** The Constant TABLE_ALERTS. */
 	private static final String TABLE_ALERTS = "alerts";
 
+	/** The Constant KEY_ALARM_DATE. */
 	private static final String KEY_ALARM_DATE = "alarm_date";
+	
+	/** The Constant KEY_MESSAGE. */
 	private static final String KEY_MESSAGE = "message";
+	
+	/** The Constant KEY_SHOWN. */
 	private static final String KEY_SHOWN = "shown";
+	
+	/** The Constant KEY_TYPE. */
 	private static final String KEY_TYPE = "type";
 	
 
+	/**
+	 * Instantiates our wrapper around the SQLiteOpenHelper
+	 *
+	 * @param context - The context to open the database in
+	 */
 	public AlertDB(Context context){
 		super(context, DATABASE_NAME, null, DATABASE_VERSION);
-		
 	}
+	
+	/**
+	 * Create the initial Database
+	 */
 	@Override
 	public void onCreate(SQLiteDatabase db) {
 		String CREATE_ALERTS_TABLE = "CREATE TABLE " + TABLE_ALERTS + "("
@@ -35,6 +58,10 @@ public class AlertDB extends SQLiteOpenHelper {
 				+ KEY_SHOWN + " INT," + KEY_TYPE + " STRING" + ")";
 		db.execSQL(CREATE_ALERTS_TABLE);
 	}
+	
+	/**
+	 * Upgrade the database on application update
+	 */
 	@Override
 	public void onUpgrade(SQLiteDatabase db, int oldVersion, int newVersion) {
 		//drop older table if it exists
@@ -45,7 +72,11 @@ public class AlertDB extends SQLiteOpenHelper {
 		
 	}
 
-	//persist alert into Database
+	/**
+	 * Persist an alert into the database
+	 *
+	 * @param a - The Alert to persist
+	 */
 	public void persist(Alert a) {
 		
 		SQLiteDatabase db = this.getWritableDatabase();
@@ -62,8 +93,12 @@ public class AlertDB extends SQLiteOpenHelper {
 		db.close();
 	}
 	
-	//persist list of alerts by looping through list
-	//and calling persist
+	/**
+	 * Persist a list of alerts into the database -
+	 * helper method for easy iteration
+	 *
+	 * @param alerts - The alerts to store
+	 */
 	public void persistMultiple(List<Alert> alerts) {
     	
 		for(int i = 0; i < alerts.size(); i++)
@@ -73,17 +108,35 @@ public class AlertDB extends SQLiteOpenHelper {
 		
 	}
 	
+	/**
+	 * Fetch an alert by date
+	 * TODO: Unused. Remove?
+	 *
+	 * @param d - The date to fetch an alert from
+	 * @return the Alert
+	 */
 	public Alert fetch(Date d) {
 		
 		return null;
 	}
 	
+	/**
+	 * Fetch multiple alerts from the Database
+	 * TODO: Unused. Remove?
+	 *
+	 * @param dates the dates to fetch alerts from
+	 * @return the list
+	 */
 	public List<Alert> fetchMultiple(List<Date> dates) {
 		
 		return null;
 	}
 	
-	//delete specified alert from DB
+	/**
+	 * Delete an alert from the Database whenever the Alert message matches
+	 *
+	 * @param alert the alert
+	 */
 	public void deleteAlert(Alert alert) {
 		SQLiteDatabase db = this.getWritableDatabase();
 		db.delete(TABLE_ALERTS, KEY_MESSAGE + " = ?", 
@@ -94,9 +147,11 @@ public class AlertDB extends SQLiteOpenHelper {
 
 	
 	
-	//get all alerts from Database
-	//regardless of type, or if it has been shown
-	//update each alert in DB as being shown
+	/**
+	 * Fetch all alerts from the Database, and mark as read
+	 *
+	 * @return the list
+	 */
 	public List<Alert> fetchAll() {
 		
 		List<Alert> alertList = new ArrayList<Alert>();
@@ -127,7 +182,11 @@ public class AlertDB extends SQLiteOpenHelper {
 		return alertList;
 	}
 	
-	//fetch just unread alerts from database
+	/**
+	 * Fetch unread alerts from the database, and mark them as read
+	 *
+	 * @return the list
+	 */
 	public List<Alert> fetchUnread() {
 		
 		List<Alert> alertList = new ArrayList<Alert>();
@@ -161,7 +220,12 @@ public class AlertDB extends SQLiteOpenHelper {
 		return alertList;
 	}
 
-	//update alert in DB to be classified as shown
+	/**
+	 * Update an alert to be marked as shown
+	 *
+	 * @param alert the alert
+	 * @return the int
+	 */
 	private int updateAlert(Alert alert) {
 		
 		SQLiteDatabase db = this.getWritableDatabase();

src/com/uncc/gameday/alerts/AlertFetcher.java

@@ -10,20 +10,16 @@ import twitter4j.Twitter;
 import twitter4j.TwitterException;
 import twitter4j.TwitterFactory;
 import twitter4j.conf.ConfigurationBuilder;
-import android.app.Activity;
-import android.app.Application;
 import android.content.Context;
 import android.content.SharedPreferences;
 import android.util.Log;
 
 import com.uncc.gameday.R;
+import com.uncc.gameday.twitter.TwitterClient;
 
-// TODO: Auto-generated Javadoc
 /**
  * The Class AlertFetcher.
  */
-
-
 public class AlertFetcher {
         // Class responsible for fetching all alerts as necessary.
         
@@ -31,7 +27,7 @@ public class AlertFetcher {
         private int maxTweets = 5;
         
         /**
-         * Fetch alerts.
+         * Fetch all alerts - Twitter, timed, etc.
          *
          * @param ctx the ctx
          */
@@ -57,33 +53,22 @@ public class AlertFetcher {
         }
     
         /**
-         * Fetch organization alerts.
+         * Fetch all Organization alerts from Twitter
          * 
-         * @param ctx the ctx
-         * @throws TwitterException the twitter exception
+         * @param ctx - The Context needed to access the Internet
+         * @throws TwitterException - Error in using the Twitter API
          */
         private void fetchOrganizationAlerts(Context ctx) throws TwitterException {            
-        	
-    	    //creates configuration for twitter access
-    	    ConfigurationBuilder cb = new ConfigurationBuilder();
-    	    
-            cb.setDebugEnabled(true)
-            	.setOAuthConsumerKey("vfRa3Tr5QYaU8Jr2pKHtiA")
-            	.setOAuthConsumerSecret("gGRdIrhPdX2Vrg296xOvTqE4sgOISMphRmPdrGirbU")
-            	.setOAuthAccessToken("1912299896-uqrhDiif3oX9Ybkf8rM5pQDWN6mW4Y7vRLK47C7")
-            	.setOAuthAccessTokenSecret("kZ11I74dcA00pWgQDZelFQz1ADJJMK0ejr6snnU34jUVT");
-            
-            TwitterFactory tf = new TwitterFactory(cb.build());
-            
             // Process fetching organization alerts (alerts retweeted by us)
-                // Will not necessarily fetch `maxTweets` tweets.
+            // Guaranteed to return <= maxTweets
             String handle = ctx.getString(R.string.gameday_handle);
-                Twitter twitter = tf.getInstance();
-                List<Status> statuses = twitter.getUserTimeline(handle, new Paging(1, maxTweets));
+            TwitterClient tc = new TwitterClient();
+            List<Status> statuses = tc.fetchTweets(handle, maxTweets);
             
             // Filter for anything created by us (retweet)
             for (Iterator<Status> it = statuses.iterator(); it.hasNext();){
-                        // May need to switch to isRetweetByMe (documentation is awful)
+                // May need to switch to isRetweetByMe, not sure if
+        		// We're using the right function (documentation is awful)
                 if (!it.next().isRetweet())
                         it.remove();
             }
@@ -96,29 +81,18 @@ public class AlertFetcher {
         }
         
         /**
-         * Fetch university alerts.
+         * Fetch alerts from the University Twitter
          *
-         * @param ctx the ctx
-         * @throws TwitterException the twitter exception
+         * @param ctx - The Context for accessing the Internet
+         * @throws TwitterException - Throws an exception for misuse of Twitter API
          */
         private void fetchUniversityAlerts(Context ctx) throws TwitterException {
             // Process fetching university alerts
             // Guaranteed to get `maxTweets` tweets
             
-    	    //creates configuration for twitter access
-    	    ConfigurationBuilder cb = new ConfigurationBuilder();
-    	    
-            cb.setDebugEnabled(true)
-            	.setOAuthConsumerKey("vfRa3Tr5QYaU8Jr2pKHtiA")
-            	.setOAuthConsumerSecret("gGRdIrhPdX2Vrg296xOvTqE4sgOISMphRmPdrGirbU")
-            	.setOAuthAccessToken("1912299896-uqrhDiif3oX9Ybkf8rM5pQDWN6mW4Y7vRLK47C7")
-            	.setOAuthAccessTokenSecret("kZ11I74dcA00pWgQDZelFQz1ADJJMK0ejr6snnU34jUVT");
-            
-            TwitterFactory tf = new TwitterFactory(cb.build());
-            
             String handle = ctx.getString(R.string.university_handle);
-                Twitter twitter = tf.getInstance();
-                List<Status> statuses = twitter.getUserTimeline(handle, new Paging(1, maxTweets));
+            TwitterClient tc = new TwitterClient();
+            List<Status> statuses = tc.fetchTweets(handle, maxTweets);
             
             String type = AlertType.getValue(AlertType.UNIVERSITY);
             pushToDatabase(statuses, type, ctx);
@@ -137,20 +111,9 @@ public class AlertFetcher {
                 // Process fetching alerts generated by staff of UNCCGameDay
                 // Not guaranteed to get `maxTweets` tweets
             
-        	    //creates configuration for twitter access
-        	    ConfigurationBuilder cb = new ConfigurationBuilder();
-        	    
-                cb.setDebugEnabled(true)
-                	.setOAuthConsumerKey("vfRa3Tr5QYaU8Jr2pKHtiA")
-                	.setOAuthConsumerSecret("gGRdIrhPdX2Vrg296xOvTqE4sgOISMphRmPdrGirbU")
-                	.setOAuthAccessToken("1912299896-uqrhDiif3oX9Ybkf8rM5pQDWN6mW4Y7vRLK47C7")
-                	.setOAuthAccessTokenSecret("kZ11I74dcA00pWgQDZelFQz1ADJJMK0ejr6snnU34jUVT");
-                
-                TwitterFactory tf = new TwitterFactory(cb.build());
-            
                 String handle = ctx.getString(R.string.gameday_handle);
-                Twitter twitter = tf.getInstance();
-                List<Status> statuses = twitter.getUserTimeline(handle, new Paging(1, maxTweets));
+                TwitterClient tc = new TwitterClient();
+                List<Status> statuses = tc.fetchTweets(handle, maxTweets);
                 
                 // Filter out anything not from us
                 for (Iterator<Status> it = statuses.iterator(); it.hasNext();){

src/com/uncc/gameday/alerts/AlertService.java

@@ -6,15 +6,30 @@ import android.app.IntentService;
 import android.content.Intent;
 import android.content.SharedPreferences;
 
+// TODO: Auto-generated Javadoc
+/**
+ * The Class AlertService.
+ */
 public class AlertService extends IntentService {
+	
+	/** The Constant name. */
 	private static final String name = "AlertService";
 	
+	/** The prefs. */
 	SharedPreferences prefs = null;
 
+	/**
+	 * Instantiates a new alert service.
+	 */
 	public AlertService() {
 		super(name);
 	}
 
+	/**
+	 * Start the actual alert service
+	 * 
+	 * @param intent - The incoming intent that started us
+	 */
 	@Override
 	protected void onHandleIntent(Intent intent) {
 		// Go fetch all the alerts!
@@ -38,8 +53,10 @@ public class AlertService extends IntentService {
 
 	}
 	
-	//Creates timed alerts and adds them to AlertDB
-	//Only runs on first application startup
+	/**
+	 * Creates timed alerts and adds them to AlertDB
+	 * Only runs on first application startup
+	 */
 	protected void onFirstRun()
 	{
 		@SuppressWarnings("deprecation")
@@ -55,7 +72,4 @@ public class AlertService extends IntentService {
 		db.persist(b);
 		db.persist(c);
 	}
-	
-	
-
 }

src/com/uncc/gameday/twitter/TwitterClient.java

@@ -11,7 +11,6 @@ import twitter4j.TwitterFactory;
 import twitter4j.conf.Configuration;
 import twitter4j.conf.ConfigurationBuilder;
 
-// TODO: Auto-generated Javadoc
 /**
  * The Class TwitterClient.
  */
@@ -63,7 +62,7 @@ public class TwitterClient {
 	 * Fetch tweets.
 	 *
 	 * @param handle the handle
-	 * @param count the count
+	 * @param count The maximum number of tweets to fetch
 	 * @return the list
 	 */
 	public List<Status> fetchTweets(String handle, int count) {