raiderrobotix / blue-alliance-api-java-library

Java library for The Blue Alliance APIv3

The Blue Alliance API Java Library

Java client library to retrieve data from The Blue Alliance using TBA API v3

Full Javadoc documentation can be found here

Usage

Begin by creating a TBA object with your Read TBA API Key. This can be found or generated on your account dashboard.

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.

They are grouped into requests with team, event, district, or match parameters, and you will need to use the teamRequest, eventRequest, or matchRequest instance variables found in the TBA class.

Here is an example of retrieving an array of teams in the FIRST Mid-Atlantic district in 2017:

Team[] midAtlanticTeams = tba.districtRequest.getTeams("2017mar");

A list of request methods for each request object can be found here.

Advanced Usage

If you want to utilize the If-Modified-Since and Last-Modified headers, you will need to make a direct URL request with the getDataTBA(String urlDirectory, String ifModifiedSince) method in the DataRequest class. 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 example of fetching the Match objects for the 2017 Mount Olive District Event, if they have been updated.

APIResponse resp = tba.dataRequest.getDataTBA("/event/2017njfla/matches");
String lastModified = resp.getLastModified();
Match[] matchList = Deserializer.toMatchArray(resp.getJson());

// Execute the following code block after waiting or in a separate method

resp = tba.dataRequest.getDataTBA("/event/2017njfla/matches", lastModified);

if(resp.getResponseCode()!=304){ // HTTP code 304 indicates no change
	teamList = Deserializer.jsonToTeamArray(resp.getJson());
	lastModified = resp.getLastModified();
	}
}

Models

A list of object model classes and their getter methods for instance variables can be found here. Please note that the master branch of this repository contains updated object models for the current season's code, and object models for past seasons can be found in other branches.

Dependencies

You will need Gson to use the released compiled TBA API JAR file in your project. Gson can be installed with Maven, via a JAR file, or with Gradle if you include the following in your build.gradle

dependencies {
	compile 'com.google.code.gson:gson:2.2.4'
}

Note that you will need Gradle to compile this repository's source code if you do not get Gson.

Contact

Feel free to contact Spencer Ng at sng1488 (at) gmail (dot) com or create a pull request if you have any questions, fixes, or suggestions.

blue-alliance-api-java-library's Issues

Unhandled NullPointerException if a team number or event code does not exist

When passing in a team number to TeamRequest.getTeam(), the method .getJson() is called on the API response, which will cause a NullPointerException if the team number does not exist. The same result will happen if an invalid event code is provided, or any other similar invalid parameter. Since the method does not handle the exception, there is no way for the implementer to handle the exception. Perhaps the methods should throw NullPointerException, that way the implementer can catch the Exception in the event the team number does not exist.

https://github.com/RaiderRobotix/blue-alliance-api-java-library/blob/master/src/main/java/com/thebluealliance/api/v3/requests/TeamRequest.java#L34

NullPointerException with team requests

 Caused by: java.lang.NullPointerException: Attempt to invoke virtual method 'java.lang.String com.thebluealliance.api.v3.requests.APIResponse.getJson()' on a null object reference

My code:

TBA tba = new TBA("key");
Team robot = new Team();
TeamRequest c = tba.teamRequest;
Event[] e = c.getEvents(2658);(the error seems to be directed to this line)
robot = c.getTeam(2658);

Trying to get teams from an event throws IllegalAccessException

When calling getTeams on an EventRequest, the JSON parser will invoke the wrong constructor for Team and result in an IllegalAccessException.

https://github.com/RaiderRobotix/blue-alliance-api-java-library/blob/master/src/main/java/com/thebluealliance/api/v3/requests/EventRequest.java#L57
https://github.com/RaiderRobotix/blue-alliance-api-java-library/blob/master/src/main/java/com/thebluealliance/api/v3/models/Team.java#L17

java.lang.RuntimeException: Failed to invoke com.thebluealliance.api.v3.models.Team() throws java.lang.IllegalAccessException with no args
    at com.google.gson.internal.ConstructorConstructor$3.construct(ConstructorConstructor.java:118)
Caused by: java.lang.IllegalAccessException: You've called the constructor of Team
    at com.thebluealliance.api.v3.models.Team.<init>(Team.java:17)

TeamEventStatus model class is missing @Value tag, values cannot be accessed

It appears that the TeamEventStatus class should have the @Value annotation in order to automatically generated getter methods. The values of that model class are currently not able to be accessed outside of the package.

https://github.com/RaiderRobotix/blue-alliance-api-java-library/blob/master/src/main/java/com/thebluealliance/api/v3/models/TeamEventStatus.java#L8

District rankings deserialization