Functionally finished; begin working on documentation

Author: spencerng

.gitignore

@@ -59,3 +59,4 @@ local.properties
 .classpath
 
 # End of https://www.gitignore.io/api/eclipse
+/.gradle/

README.md

@@ -1,5 +1,72 @@
 # TBA-API-Java-Library
 
-Java library for The Blue Alliance API v3
+Java client library to retrieve data from The Blue Alliance using TBA API v3
 
-Work in progress
+The library is essentially complete, but documentation is in progress.
+
+## Usage
+
+Begin by creating a TBA object with your Read TBA API Key. This can be found or generated on your [account dashboard](https://www.thebluealliance.com/account).
+
+    String authKey = // your TBA API read key
+    TBA tba = new TBA(authKey);
+
+### Regular Usage
+
+The library allows access to almost all of the calls in [The Blue Alliance API v3 documentation](https://www.thebluealliance.com/apidocs/v3). They are grouped into requests with team, event, district, or match parameters:
+
+**`tba.teamRequest`**
+
+ * `getTeam(teamNumber)`: Gets a `Team` object for the team referenced by the given number (an `int`).
+ * `getSimpleTeam(teamNumber): Gets a `SimpleTeam` object for the team referenced by the given number.
+ * `getYearsParticipated(teamNumber): Gets a list of years in which the team participated in at least one competition.
+ * getDistricts(teamNumber): Gets a list of `District` objects for each year the team was in a district. Will return `null` if the team was never in a district.
+ * to be continued
+
+**`tba.eventRequest`**
+
+ * to be continued
+
+**`tba.districtRequest`**
+ 
+ * to be continued
+
+**`tba.matchRequest`**
+
+ * to be continued
+
+### Advance Usage
+
+If you want to utilize the `If-Modified-Since` and `Last-Modified` headers, you will need to make a direct URL request (following the documentation). This will return an `APIResponse` object with JSON data, the HTTP response code, and the `Last-Modified` header. 
+
+The JSON data will need to be deserialized into an object model with a method in the `Deserializer` class before being used.
+
+Here is an (extremely inefficient) example of continuously fetching the `Team` objects for an event (`2017njfla`), if they have been updated.
+
+    TBA tba = new TBA(authKey);
+	APIResponse resp = tba.dataRequest.getDataTBA("/event/2017njfla/teams");
+	String lastModified = resp.getLastModified();
+	Team[] teamList = Deserializer.toTeamArray(resp.getJson());
+		while(true){
+			resp = tba.dataRequest.getDataTBA("/event/2017njfla/teams", lastModified);
+			if(resp.getResponseCode()!=304){
+				teamList = Deserializer.jsonToTeamArray(resp.getJson());
+				lastModified = resp.getLastModified();
+			}
+		}
+
+## Models
+
+Most of the object models follow those on The Blue Alliance API documentation, with appropriately named getter methods:
+
+**Award**
+
+ * `String getName()`: The name of the award as provided by FIRST. May vary for the same award type.
+ * `int getAwardType()`: Type of award given. See [here](https://github.com/the-blue-alliance/the-blue-alliance/blob/master/consts/award_type.py#L6) for details.
+ * `String getEventKey()`: The `event_key` of the event the award was won at.
+ * `AwardRecipient[] getRecipientList()`: A list of recipients of the award at the event. Either team_key and/or awardee for individual awards.
+ * `int getYear()`: The year this award was won.
+
+## Contact
+
+Feel free to contact me at sng1488@gmail.com or create a pull request if you have any questions, fixes, or suggestions. This library is (currently) unaffiliated with [FRC Team 25](http://raiderrobotix.org).

src/main/java/com/thebluealliance/Deserializer.java

@@ -7,39 +7,114 @@ public class Deserializer {
 
 	final static Gson gson = new Gson();
 
-	public static Team jsonToTeam(String jsonData){
+	public static Team toTeam(String jsonData){
 		Team team = gson.fromJson(jsonData, Team.class);
 		return team;
 	}
 
-	public static SimpleTeam jsonToSimpleTeam(String jsonData){
+	public static Team[] toTeamArray(String jsonData){
+		Team[] teamArray = gson.fromJson(jsonData, Team[].class);
+		return teamArray;
+	}
+	
+	public static SimpleTeam toSimpleTeam(String jsonData){
 		SimpleTeam team = gson.fromJson(jsonData, SimpleTeam.class);
 		return team;
 	}
 
-	public static int[] jsonToIntArray(String jsonData){
+	public static SimpleTeam[] toSimpleTeamArray(String jsonData){
+		SimpleTeam[] simpleTeamArray = gson.fromJson(jsonData, SimpleTeam[].class);
+		return simpleTeamArray;
+	}
+	
+	public static int[] toIntArray(String jsonData){
 		int[] intArray = gson.fromJson(jsonData, int[].class);
 		return intArray;
 	}
 
-	public static DistrictEntry[] jsonToDistrictEntryArray(String jsonData){
-		DistrictEntry[] districtEntryArray = gson.fromJson(jsonData, DistrictEntry[].class);
+	public static District[] toDistrictEntryArray(String jsonData){
+		District[] districtEntryArray = gson.fromJson(jsonData, District[].class);
 		return districtEntryArray;
 	}
 
-	public static Robot[] jsonToRobotArray(String jsonData){
+	public static Robot[] toRobotArray(String jsonData){
 		Robot[] robotArray = gson.fromJson(jsonData, Robot[].class);
 		return robotArray;
 	}
 
-	public static Event[] jsonToEventArray(String jsonData){
+	public static Event[] toEventArray(String jsonData){
 		Event[] eventArray = gson.fromJson(jsonData, Event[].class);
 		return eventArray;
 	}
 
-	public static SimpleEvent[] jsonToSimpleEventArray(String jsonData){
+	public static SimpleEvent[] toSimpleEventArray(String jsonData){
 		SimpleEvent[] eventArray = gson.fromJson(jsonData, SimpleEvent[].class);
 		return eventArray;
 	}
+	
+	public static String[] toStringArray(String jsonData){
+		String[] stringArray = gson.fromJson(jsonData, String[].class);
+		return stringArray;
+	}
+	
+	public static Match[] toMatchArray(String jsonData){
+		Match[] matchArray = gson.fromJson(jsonData, Match[].class);
+		return matchArray;
+	}
+	
+	public static SimpleMatch[] toSimpleMatchArray(String jsonData){
+		SimpleMatch[] matchArray = gson.fromJson(jsonData, SimpleMatch[].class);
+		return matchArray;
+	}
+	
+	public static Award[] toAwardArray(String jsonData){
+		Award[] awardArray = gson.fromJson(jsonData, Award[].class);
+		return awardArray;
+	}
+	
+	public static Media[] toMediaArray(String jsonData){
+		Media[] mediaArray = gson.fromJson(jsonData, Media[].class);
+		return mediaArray;
+	}
+	
+	public static TeamEventStatus toTeamEventStatus(String jsonData){
+		TeamEventStatus teamEventStatus = gson.fromJson(jsonData, TeamEventStatus.class);
+		return teamEventStatus;
+	}
+	
+	public static DistrictRanking[] toDistrictRankingArray(String jsonData){
+		DistrictRanking[] districtRankingArray = gson.fromJson(jsonData, DistrictRanking[].class);
+		return districtRankingArray;
+	}
+
+	public static EventDistrictPoints toEventDistrictPoints(String jsonData) {
+		EventDistrictPoints eventDistrictPoints = gson.fromJson(jsonData, EventDistrictPoints.class);
+		return eventDistrictPoints;
+	}
+
+	public static EliminationAlliance[] toEliminationAllianceArray(String jsonContent) {
+		EliminationAlliance[] eliminationAllianceArray = gson.fromJson(jsonContent, EliminationAlliance[].class);
+		return eliminationAllianceArray;
+	}
+	
+	public static OPRs toOPRs(String jsonData) {
+		OPRs oprs = gson.fromJson(jsonData, OPRs.class);
+		return oprs;
+	}
+	
+	public static EventRankings toEventRankings(String jsonData) {
+		EventRankings eventRankings = gson.fromJson(jsonData, EventRankings.class);
+		return eventRankings;
+	}
+	
+	public static Match toMatch(String jsonData){
+		Match match = gson.fromJson(jsonData, Match.class);
+		return match;
+	}
+	
+	public static SimpleMatch toSimpleMatch(String jsonData){
+		SimpleMatch match = gson.fromJson(jsonData, SimpleMatch.class);
+		return match;
+	}
 
 }

src/main/java/com/thebluealliance/Main.java

@@ -0,0 +1,28 @@
+package com.thebluealliance;
+
+import com.thebluealliance.requests.DataRequest;
+import com.thebluealliance.requests.DistrictRequest;
+import com.thebluealliance.requests.EventRequest;
+import com.thebluealliance.requests.MatchRequest;
+import com.thebluealliance.requests.TeamRequest;
+
+public class TBA {
+	
+	public static String AUTH_KEY;
+	public final DataRequest dataRequest;
+	public final TeamRequest teamRequest;
+	public final EventRequest eventRequest;
+	public final DistrictRequest districtRequest;
+	public final MatchRequest matchRequest;
+	
+	
+	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/TBA.java

@@ -0,0 +1,41 @@
+package com.thebluealliance.models;
+
+public class Award {
+	
+	private String name, event_key;
+	private int award_type, year;
+	private AwardRecipient[] recipient_list;
+	
+	public class AwardRecipient{
+		private String team_key, awardee;
+
+		public String getTeam_key() {
+			return team_key;
+		}
+
+		public String getAwardee() {
+			return awardee;
+		}
+	}
+
+	public String getName() {
+		return name;
+	}
+
+	public String getEventKey() {
+		return event_key;
+	}
+
+	public int getAwardType() {
+		return award_type;
+	}
+
+	public int getYear() {
+		return year;
+	}
+
+	public AwardRecipient[] getRecipientList() {
+		return recipient_list;
+	}
+
+}

src/main/java/com/thebluealliance/models/Award.java

@@ -1,6 +1,6 @@
 package com.thebluealliance.models;
 
-public class DistrictEntry {
+public class District {
 
 	private String abbreviation, display_name, key;
 	private int year;

…hebluealliance/models/DistrictEntry.java …com/thebluealliance/models/District.javasrc/main/java/com/thebluealliance/models/DistrictEntry.java renamed to src/main/java/com/thebluealliance/models/District.java src/main/java/com/thebluealliance/models/DistrictEntry.java renamed to src/main/java/com/thebluealliance/models/District.java

@@ -0,0 +1,31 @@
+package com.thebluealliance.models;
+
+public class DistrictRanking {
+	
+	private String teamKey; 
+	private int rank, rookie_bonus, point_total;
+	private EventPoints event_points;
+	
+
+
+	public String getTeamKey() {
+		return teamKey;
+	}
+
+	public int getRank() {
+		return rank;
+	}
+
+	public int getRookieBonus() {
+		return rookie_bonus;
+	}
+
+	public int getPointTotal() {
+		return point_total;
+	}
+
+	public EventPoints getEventPoints() {
+		return event_points;
+	}
+
+}