com.jdroid.github.client

Class GitHubClient

java.lang.Object

com.jdroid.github.client.GitHubClient

public class GitHubClient
extends java.lang.Object

Client class for interacting with GitHub HTTP/JSON API.

Field Summary

Fields

Modifier and Type	Field and Description
protected java.lang.String	baseUri Base URI
protected com.google.gson.Gson	gson Gson instance
protected static java.lang.String	HEADER_ACCEPT Accept header
protected static java.lang.String	HEADER_AUTHORIZATION Authorization header
protected static java.lang.String	HEADER_CONTENT_TYPE Content-Type header
protected static java.lang.String	HEADER_USER_AGENT User-Agent header
protected static int	HTTP_UNPROCESSABLE_ENTITY 422 status code for unprocessable entity
protected static java.lang.String	METHOD_DELETE METHOD_DELETE
protected static java.lang.String	METHOD_GET METHOD_GET
protected static java.lang.String	METHOD_POST METHOD_POST
protected static java.lang.String	METHOD_PUT METHOD_PUT
protected java.lang.String	prefix Prefix to apply to base URI
protected static java.lang.String	USER_AGENT Default user agent request header value

Constructor Summary

Constructors

Constructor and Description
GitHubClient() Create default client
GitHubClient(java.lang.String hostname) Create client for host name
GitHubClient(java.lang.String hostname, int port, java.lang.String scheme) Create client for host, port, and scheme

Method Summary

Modifier and Type	Method and Description
protected java.net.HttpURLConnection	configureRequest(java.net.HttpURLConnection request) Configure request with standard headers
protected java.lang.String	configureUri(java.lang.String uri) Configure request URI
static GitHubClient	createClient(java.lang.String url) Create API v3 client from URL.
protected java.net.HttpURLConnection	createConnection(java.lang.String uri) Create connection to URI
protected java.net.HttpURLConnection	createConnection(java.lang.String uri, java.lang.String method) Create connection to URI
protected java.net.HttpURLConnection	createDelete(java.lang.String uri) Create a DELETE request connection to the URI
protected java.io.IOException	createException(java.io.InputStream response, int code, java.lang.String status) Create error exception from response and throw it
protected java.net.HttpURLConnection	createGet(java.lang.String uri) Create a GET request connection to the URI
protected java.net.HttpURLConnection	createPost(java.lang.String uri) Create a POST request connection to the URI
protected java.net.HttpURLConnection	createPut(java.lang.String uri) Create a PUT request connection to the URI
protected java.lang.String	createUri(java.lang.String path) Create full URI from path
void	delete(java.lang.String uri) Delete resource at URI.
void	delete(java.lang.String uri, java.lang.Object params) Delete resource at URI.
GitHubResponse	get(GitHubRequest request) Get response from URI and bind to specified type
protected java.lang.Object	getBody(GitHubRequest request, java.io.InputStream stream) Get body from response inputs stream
java.lang.String	getHeaderAccept() Returns the accept header currently used for all requests.
int	getRemainingRequests() Get number of requests remaining before rate limiting occurs
int	getRequestLimit() Get number of requests that getRemainingRequests() counts down from as each request is made
protected java.io.InputStream	getResponseStream(java.net.HttpURLConnection request) Get response stream for request
java.io.InputStream	getStream(GitHubRequest request) Get response stream from GET to URI.
protected java.io.InputStream	getStream(java.net.HttpURLConnection request) Get stream from request
java.lang.String	getUser() Get the user that this client is currently authenticating as
protected boolean	isEmpty(int code) Is the response empty?
protected boolean	isError(int code) Does status code denote an error
protected boolean	isOk(int code) Does status code denote a non-error response?
protected RequestError	parseError(java.io.InputStream response) Parse error from response
protected <V> V	parseJson(java.io.InputStream stream, java.lang.reflect.Type type) Parse JSON to specified type
protected <V> V	parseJson(java.io.InputStream stream, java.lang.reflect.Type type, java.lang.reflect.Type listType) Parse JSON to specified type
void	post(java.lang.String uri) Post to URI
<V> V	post(java.lang.String uri, java.lang.Object params, java.lang.reflect.Type type) Post data to URI
java.io.InputStream	postStream(java.lang.String uri, java.lang.Object params) Get response stream from POST to URI.
void	put(java.lang.String uri) Put to URI
<V> V	put(java.lang.String uri, java.lang.Object params, java.lang.reflect.Type type) Put data to URI
protected void	sendParams(java.net.HttpURLConnection request, java.lang.Object params) Send parameters to output stream of request
GitHubClient	setBufferSize(int bufferSize) Set buffer size used to send the request and read the response
GitHubClient	setCredentials(java.lang.String user, java.lang.String password) Set credentials
GitHubClient	setHeaderAccept(java.lang.String header) Set the value to set as the accept header on every request created.
GitHubClient	setOAuth2Token(java.lang.String token) Set OAuth2 token
GitHubClient	setSerializeNulls(boolean serializeNulls) Set whether or not serialized data should include fields that are null.
GitHubClient	setUserAgent(java.lang.String agent) Set the value to set as the user agent header on every request created.
protected java.lang.String	toJson(java.lang.Object object) Convert object to a JSON string
protected GitHubClient	updateRateLimits(java.net.HttpURLConnection request) Update rate limits present in response headers

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

HEADER_CONTENT_TYPE

protected static final java.lang.String HEADER_CONTENT_TYPE

Content-Type header

See Also:

Constant Field Values

HEADER_ACCEPT

protected static final java.lang.String HEADER_ACCEPT

Accept header

See Also:

Constant Field Values

HEADER_AUTHORIZATION

protected static final java.lang.String HEADER_AUTHORIZATION

Authorization header

See Also:

Constant Field Values

HEADER_USER_AGENT

protected static final java.lang.String HEADER_USER_AGENT

User-Agent header

See Also:

Constant Field Values

METHOD_GET

protected static final java.lang.String METHOD_GET

METHOD_GET

See Also:

Constant Field Values

METHOD_PUT

protected static final java.lang.String METHOD_PUT

METHOD_PUT

See Also:

Constant Field Values

METHOD_POST

protected static final java.lang.String METHOD_POST

METHOD_POST

See Also:

Constant Field Values

METHOD_DELETE

protected static final java.lang.String METHOD_DELETE

METHOD_DELETE

See Also:

Constant Field Values

USER_AGENT

protected static final java.lang.String USER_AGENT

Default user agent request header value

See Also:

Constant Field Values

HTTP_UNPROCESSABLE_ENTITY

protected static final int HTTP_UNPROCESSABLE_ENTITY

422 status code for unprocessable entity

See Also:

Constant Field Values

baseUri

protected final java.lang.String baseUri

Base URI

prefix

protected final java.lang.String prefix

Prefix to apply to base URI

gson

protected com.google.gson.Gson gson

Gson instance

Constructor Detail

GitHubClient

public GitHubClient()

Create default client

GitHubClient

public GitHubClient(java.lang.String hostname)

Create client for host name

Parameters:

hostname -

GitHubClient

public GitHubClient(java.lang.String hostname,
                    int port,
                    java.lang.String scheme)

Create client for host, port, and scheme

Parameters:

hostname -

port -

scheme -

Method Detail

createClient

public static GitHubClient createClient(java.lang.String url)

Create API v3 client from URL.

This creates an HTTPS-based client with a host that contains the host value of the given URL prefixed with 'api' if the given URL is github.com or gist.github.com

Parameters:

url -

Returns:

client

setSerializeNulls

public GitHubClient setSerializeNulls(boolean serializeNulls)

Set whether or not serialized data should include fields that are null.

Parameters:

serializeNulls -

Returns:

this client

setUserAgent

public GitHubClient setUserAgent(java.lang.String agent)

Set the value to set as the user agent header on every request created. Specifying a null or empty agent parameter will reset this client to use the default user agent header value.

Parameters:

agent -

Returns:

this client

setHeaderAccept

public GitHubClient setHeaderAccept(java.lang.String header)

Set the value to set as the accept header on every request created. Specifying a null or empty header parameter will reset this client to use the default accept header value.

Parameters:

header -

Returns:

this client

getHeaderAccept

public java.lang.String getHeaderAccept()

Returns the accept header currently used for all requests.

Returns:

header

Since:

4.2

configureRequest

protected java.net.HttpURLConnection configureRequest(java.net.HttpURLConnection request)

Configure request with standard headers

Parameters:

request -

Returns:

configured request

configureUri

protected java.lang.String configureUri(java.lang.String uri)

Configure request URI

Parameters:

uri -

Returns:

configured URI

createConnection

protected java.net.HttpURLConnection createConnection(java.lang.String uri)
                                               throws java.io.IOException

Create connection to URI

Parameters:

uri -

Returns:

connection

Throws:

java.io.IOException

createConnection

protected java.net.HttpURLConnection createConnection(java.lang.String uri,
                                                      java.lang.String method)
                                               throws java.io.IOException

Create connection to URI

Parameters:

uri -

method -

Returns:

connection

Throws:

java.io.IOException

createGet

protected java.net.HttpURLConnection createGet(java.lang.String uri)
                                        throws java.io.IOException

Create a GET request connection to the URI

Parameters:

uri -

Returns:

connection

Throws:

java.io.IOException

createPost

protected java.net.HttpURLConnection createPost(java.lang.String uri)
                                         throws java.io.IOException

Create a POST request connection to the URI

Parameters:

uri -

Returns:

connection

Throws:

java.io.IOException

createPut

protected java.net.HttpURLConnection createPut(java.lang.String uri)
                                        throws java.io.IOException

Create a PUT request connection to the URI

Parameters:

uri -

Returns:

connection

Throws:

java.io.IOException

createDelete

protected java.net.HttpURLConnection createDelete(java.lang.String uri)
                                           throws java.io.IOException

Create a DELETE request connection to the URI

Parameters:

uri -

Returns:

connection

Throws:

java.io.IOException

setCredentials

public GitHubClient setCredentials(java.lang.String user,
                                   java.lang.String password)

Set credentials

Parameters:

user -

password -

Returns:

this client

setOAuth2Token

public GitHubClient setOAuth2Token(java.lang.String token)

Set OAuth2 token

Parameters:

token -

Returns:

this client

setBufferSize

public GitHubClient setBufferSize(int bufferSize)

Set buffer size used to send the request and read the response

Parameters:

bufferSize -

Returns:

this client

getUser

public java.lang.String getUser()

Get the user that this client is currently authenticating as

Returns:

user or null if not authentication

toJson

protected java.lang.String toJson(java.lang.Object object)
                           throws java.io.IOException

Convert object to a JSON string

Parameters:

object -

Returns:

JSON string

Throws:

java.io.IOException

parseJson

protected <V> V parseJson(java.io.InputStream stream,
                          java.lang.reflect.Type type)
                   throws java.io.IOException

Parse JSON to specified type

Type Parameters:

V -

Parameters:

stream -

type -

Returns:

parsed type

Throws:

java.io.IOException

parseJson

protected <V> V parseJson(java.io.InputStream stream,
                          java.lang.reflect.Type type,
                          java.lang.reflect.Type listType)
                   throws java.io.IOException

Parse JSON to specified type

Type Parameters:

V -

Parameters:

stream -

type -

listType -

Returns:

parsed type

Throws:

java.io.IOException

isError

protected boolean isError(int code)

Does status code denote an error

Parameters:

code -

Returns:

true if error, false otherwise

isOk

protected boolean isOk(int code)

Does status code denote a non-error response?

Parameters:

code -

Returns:

true if okay, false otherwise

isEmpty

protected boolean isEmpty(int code)

Is the response empty?

Parameters:

code -

Returns:

true if empty, false otherwise

parseError

protected RequestError parseError(java.io.InputStream response)
                           throws java.io.IOException

Parse error from response

Parameters:

response -

Returns:

request error

Throws:

java.io.IOException

getBody

protected java.lang.Object getBody(GitHubRequest request,
                                   java.io.InputStream stream)
                            throws java.io.IOException

Get body from response inputs stream

Parameters:

request -

stream -

Returns:

parsed body

Throws:

java.io.IOException

createException

protected java.io.IOException createException(java.io.InputStream response,
                                              int code,
                                              java.lang.String status)

Create error exception from response and throw it

Parameters:

response -

code -

status -

Returns:

non-null newly created IOException

post

public void post(java.lang.String uri)
          throws java.io.IOException

Post to URI

Parameters:

uri -

Throws:

java.io.IOException

put

public void put(java.lang.String uri)
         throws java.io.IOException

Put to URI

Parameters:

uri -

Throws:

java.io.IOException

delete

public void delete(java.lang.String uri)
            throws java.io.IOException

Delete resource at URI. This method will throw an IOException when the response status is not a 204 (No Content).

Parameters:

uri -

Throws:

java.io.IOException

sendParams

protected void sendParams(java.net.HttpURLConnection request,
                          java.lang.Object params)
                   throws java.io.IOException

Send parameters to output stream of request

Parameters:

request -

params -

Throws:

java.io.IOException

createUri

protected java.lang.String createUri(java.lang.String path)

Create full URI from path

Parameters:

path -

Returns:

uri

getStream

public java.io.InputStream getStream(GitHubRequest request)
                              throws java.io.IOException

Get response stream from GET to URI. It is the responsibility of the calling method to close the returned stream.

Parameters:

request -

Returns:

stream

Throws:

java.io.IOException

postStream

public java.io.InputStream postStream(java.lang.String uri,
                                      java.lang.Object params)
                               throws java.io.IOException

Get response stream from POST to URI. It is the responsibility of the calling method to close the returned stream.

Parameters:

uri -

params -

Returns:

stream

Throws:

java.io.IOException

getResponseStream

protected java.io.InputStream getResponseStream(java.net.HttpURLConnection request)
                                         throws java.io.IOException

Get response stream for request

Parameters:

request -

Returns:

stream

Throws:

java.io.IOException

getStream

protected java.io.InputStream getStream(java.net.HttpURLConnection request)
                                 throws java.io.IOException

Get stream from request

Parameters:

request -

Returns:

stream

Throws:

java.io.IOException

get

public GitHubResponse get(GitHubRequest request)
                   throws java.io.IOException

Get response from URI and bind to specified type

Parameters:

request -

Returns:

response

Throws:

java.io.IOException

post

public <V> V post(java.lang.String uri,
                  java.lang.Object params,
                  java.lang.reflect.Type type)
           throws java.io.IOException

Post data to URI

Type Parameters:

V -

Parameters:

uri -

params -

type -

Returns:

response

Throws:

java.io.IOException

put

public <V> V put(java.lang.String uri,
                 java.lang.Object params,
                 java.lang.reflect.Type type)
          throws java.io.IOException

Put data to URI

Type Parameters:

V -

Parameters:

uri -

params -

type -

Returns:

response

Throws:

java.io.IOException

delete

public void delete(java.lang.String uri,
                   java.lang.Object params)
            throws java.io.IOException

Delete resource at URI. This method will throw an IOException when the response status is not a 204 (No Content).

Parameters:

uri -

params -

Throws:

java.io.IOException

updateRateLimits

protected GitHubClient updateRateLimits(java.net.HttpURLConnection request)

Update rate limits present in response headers

Parameters:

request -

Returns:

this client

getRemainingRequests

public int getRemainingRequests()

Get number of requests remaining before rate limiting occurs

This will be the value of the 'X-RateLimit-Remaining' header from the last request made

Returns:

remainingRequests or -1 if not present in the response

getRequestLimit

public int getRequestLimit()

Get number of requests that getRemainingRequests() counts down from as each request is made

This will be the value of the 'X-RateLimit-Limit' header from the last request made

Returns:

requestLimit or -1 if not present in the response