Readme update

Author: spencerng

src/main/java/com/thebluealliance/TBA.java

@@ -0,0 +1,54 @@
+package com.thebluealliance.api.v3;
+
+import com.thebluealliance.api.v3.requests.DataRequest;
+import com.thebluealliance.api.v3.requests.DistrictRequest;
+import com.thebluealliance.api.v3.requests.EventRequest;
+import com.thebluealliance.api.v3.requests.MatchRequest;
+import com.thebluealliance.api.v3.requests.TeamRequest;
+
+/** Base class used to access the The Blue Alliance API.
+ * A TBA object must be created to use this client library.
+ *
+ */
+public class TBA {
+	
+	public static String AUTH_KEY;
+	
+	/** A {@link DataRequest} object to make direct calls to the API
+	 * 
+	 */
+	public final DataRequest dataRequest;
+	
+	/** A {@link TeamRequest} object to make calls in which a <code>teamNumber</code> is the primary argument
+	 * 
+	 */
+	public final TeamRequest teamRequest;
+	
+	/**  An {@link EventRequest} object to make calls in which an <code>eventKey</code> is the primary argument
+	 * 
+	 */
+	public final EventRequest eventRequest;
+	
+	/** A {@link DistrictRequest} object to make calls in which a <code>districtKey</code> is the primary argument
+	 */
+	public final DistrictRequest districtRequest;
+	
+	/** A {@link MatchRequest} object to make calls in which a <code>matchKey</code> is the primary argument
+	 * 
+	 */
+	public final MatchRequest matchRequest;
+	
+	/** Create a TBA object to make API requests
+	 * 
+	 * @param authKey The Read API Key, generated on your <a href="https://www.thebluealliance.com/account">Account Dashboard</a> on The Blue Alliance
+	 */
+	public TBA(String authKey){
+		AUTH_KEY = authKey;
+		dataRequest = new DataRequest(AUTH_KEY);
+		teamRequest = new TeamRequest(dataRequest);
+		eventRequest = new EventRequest(dataRequest);
+		districtRequest = new DistrictRequest(dataRequest);
+		matchRequest = new MatchRequest(dataRequest);
+	}
+
+}

src/main/java/com/thebluealliance/api/v3/TBA.java

@@ -1,31 +1,49 @@
-package com.thebluealliance.models;
+package com.thebluealliance.api.v3.models;
 
 import java.util.HashMap;
 
+/** Represents a FIRST Robotics Competition team
+ *
+ */
 public class Team extends SimpleTeam{
 
 	private String postal_code, website, motto;
 	private int rookie_year;
 
 	private HashMap<String, String> home_championship;
 
+	/**
+	 * @return Postal code from the team address.
+	 */
 	public String getPostalCode() {
 		return postal_code;
 	}
 
+	/**
+	 * @return Official website associated with the team.
+	 */
 	public String getWebsite() {
 		return website;
 	}
 
+	/**
+	 * @return Team’s motto as provided by FIRST.
+	 */
 	public String getMotto() {
 		return motto;
 	}
 
-	
+	/**
+	 * @return First year the team officially competed.
+	 */
 	public int getRookieYear() {
 		return rookie_year;
 	}
 
+	/**
+	 * @param year An year to query. Must be greater than or equal to 2017.
+	 * @return 	Location of the team’s home championship for the particular <code>year</code> 
+	 */
 	public String getHomeChampionship(int year) {
 		return home_championship.get(Integer.toString(year));
 	}

…ava/com/thebluealliance/models/Team.java …/thebluealliance/api/v3/models/Team.javasrc/main/java/com/thebluealliance/models/Team.java renamed to src/main/java/com/thebluealliance/api/v3/models/Team.java src/main/java/com/thebluealliance/models/Team.java renamed to src/main/java/com/thebluealliance/api/v3/models/Team.java

@@ -1,65 +1,100 @@
-package com.thebluealliance.models;
-
+package com.thebluealliance.api.v3.models;
 
+/** Represents a team's status during an event
+ *
+ */
 public class TeamEventStatus {
 
 	private Rank qual;
 	private Alliance alliance;
 	private PlayoffStatus playoff;
 	private String alliance_status_str, playoff_status_str, overall_status_str;
 
+	/** Holds rank information of a team during an event
+	 *
+	 */
 	public class Rank{
 		private int num_teams;
 		private String status;
 		private Ranking ranking;
 
 
+		/**
+		 * @return Number of teams ranked.
+		 */
 		public int getNumTeams() {
 			return num_teams;
 		}
 
 
+		/**
+		 * @return Either <code>completed</code> or <code>ongoing</code>
+		 */
 		public String getStatus() {
 			return status;
 		}
 
-
+		/**
+		 * @return A {@link Ranking} describing the team's status in the qualification tournament
+		 */
 		public Ranking getRanking() {
 			return ranking;
 		}
 
 	}
 
+	/** Describes a team's alliance during the playoff tournament
+	 */
 	public class Alliance{
 		private String name;
 		private int number, pick;
 		private AllianceBackup backup;
 
+		/** Describes the backup status of an alliance
+		 */
 		public class AllianceBackup{
 			private String out, in;
 
+			/**
+			 * @return TBA key for the team replaced by the backup.
+			 */
 			public String getOut() {
 				return out;
 			}
-
+			
+			/**
+			 * @return TBA key for the backup team called in.
+			 */
 			public String getIn() {
 				return in;
 			}
 
 		}
 
+		/**
+		 * @return Alliance name, may be null.
+		 */
 		public String getName() {
 			return name;
 		}
 
+		/**
+		 * @return Alliance number
+		 */
 		public int getNumber() {
 			return number;
 		}
 
+		/**
+		 * @return Order the team was picked in the alliance from 0-2, with 0 being alliance captain.
+		 */
 		public int getPick() {
 			return pick;
 		}
 
+		/**
+		 * @return Backup status, may be null
+		 */
 		public AllianceBackup getBackup() {
 			return backup;
 		}
@@ -82,26 +117,44 @@ public String getStatus() {
 		}
 	}
 
+	/**
+	 * @return The team's {@link Rank} during the qualification matches
+	 */
 	public Rank getQual() {
 		return qual;
 	}
 
+	/**
+	 * @return The team's alliance selection information
+	 */
 	public Alliance getAlliance() {
 		return alliance;
 	}
 
+	/**
+	 * @return Playoff status for this team, may be null if the team did not make playoffs, or playoffs have not begun.
+	 */
 	public PlayoffStatus getPlayoffStatus() {
 		return playoff;
 	}
 
+	/**
+	 * @return An HTML formatted string suitable for display to the user containing the team’s alliance pick status.
+	 */
 	public String getAllianceStatusStr() {
 		return alliance_status_str;
 	}
 
+	/**
+	 * @return An HTML formatter string suitable for display to the user containing the team’s playoff status.
+	 */
 	public String getPlayoffStatusStr() {
 		return playoff_status_str;
 	}
 
+	/**
+	 * @return An HTML formatted string suitable for display to the user containing the team’s overall status summary of the event.
+	 */
 	public String getOverallStatusStr() {
 		return overall_status_str;
 	}

…bluealliance/models/TeamEventStatus.java …iance/api/v3/models/TeamEventStatus.javasrc/main/java/com/thebluealliance/models/TeamEventStatus.java renamed to src/main/java/com/thebluealliance/api/v3/models/TeamEventStatus.java src/main/java/com/thebluealliance/models/TeamEventStatus.java renamed to src/main/java/com/thebluealliance/api/v3/models/TeamEventStatus.java

@@ -0,0 +1,29 @@
+package com.thebluealliance.api.v3.models;
+
+/** A Win-Loss-Tie record for a team, or an alliance.
+ *
+ */
+public class WLTRecord{
+	private int losses, wins, ties;
+
+	/**
+	 * @return Number of losses
+	 */
+	public int getLosses() {
+		return losses;
+	}
+
+	/**
+	 * @return Number of wins
+	 */
+	public int getWins() {
+		return wins;
+	}
+
+	/**
+	 * @return Number of ties
+	 */
+	public int getTies() {
+		return ties;
+	}
+}

src/main/java/com/thebluealliance/api/v3/models/WLTRecord.java

@@ -0,0 +1,5 @@
+/** Provides the classes necessary to access The Blue Alliance API
+ * and deserialize JSON data obtained from the API into object models
+ * 
+ */
+package com.thebluealliance.api.v3;

src/main/java/com/thebluealliance/api/v3/package-info.java

@@ -0,0 +1,47 @@
+package com.thebluealliance.api.v3.requests;
+
+/** Holds a response from The Blue Alliance API v3
+ *
+ */
+public class APIResponse {
+
+	private final String jsonContent, lastModified;
+	
+	/**
+	 * @return The JSON string returned by the API. May be null if the <code>
+	 * responseCode</code> is not 200.
+	 */
+	public String getJson() {
+		return jsonContent;
+	}
+
+	/**
+	 * @return 	The date and time the data returned was last updated. Used by clients in the `If-Modified-Since` request header.
+	 */
+	public String getLastModified() {
+		return lastModified;
+	}
+
+	/**
+	 * @return The HTTP response code given by the API. 
+	 * Value is 200 if the response is successful, 304 if data was not modified and the <code>If-Modified-Since</code>
+	 *  header is used, 401 if no TBA v3 API Key was provided, or it is not valid, or 404 if the URL or parameter(s) provided is invalid
+	 */
+	public int getResponseCode() {
+		return responseCode;
+	}
+
+	private final int responseCode;
+	
+	/** Creates an APIResponse object
+	 * @param jsonContent JSON data returned by the API
+	 * @param lastModified The <code>Last-Modified</code> response header
+	 * @param responseCode The HTTP response code
+	 */
+	public APIResponse(String jsonContent, String lastModified, int responseCode){
+		this.jsonContent = jsonContent;
+		this.lastModified = lastModified;
+		this.responseCode = responseCode;
+	}
+	
+}