org.eclipse.egit.github.core.client
Class GitHubClient

java.lang.Object
  extended by org.eclipse.egit.github.core.client.GitHubClient

public class GitHubClient
extends Object

Client class for interacting with GitHub HTTP/JSON API.


Field Summary
protected  String baseUri
          Base URI
protected  com.google.gson.Gson gson
          Gson instance
protected static String HEADER_ACCEPT
          Accept header
protected static String HEADER_AUTHORIZATION
          Authorization header
protected static String HEADER_CONTENT_TYPE
          Content-Type header
protected static String HEADER_USER_AGENT
          User-Agent header
protected static int HTTP_UNPROCESSABLE_ENTITY
          422 status code for unprocessable entity
protected static String METHOD_DELETE
          METHOD_DELETE
protected static String METHOD_GET
          METHOD_GET
protected static String METHOD_POST
          METHOD_POST
protected static String METHOD_PUT
          METHOD_PUT
protected  String prefix
          Prefix to apply to base URI
protected static String USER_AGENT
          Default user agent request header value
 
Constructor Summary
GitHubClient()
          Create default client
GitHubClient(String hostname)
          Create client for host name
GitHubClient(String hostname, int port, String scheme)
          Create client for host, port, and scheme
 
Method Summary
protected  HttpURLConnection configureRequest(HttpURLConnection request)
          Configure request with standard headers
protected  String configureUri(String uri)
          Configure request URI
static GitHubClient createClient(String url)
          Create API v3 client from URL.
protected  HttpURLConnection createConnection(String uri)
          Create connection to URI
protected  HttpURLConnection createConnection(String uri, String method)
          Create connection to URI
protected  HttpURLConnection createDelete(String uri)
          Create a DELETE request connection to the URI
protected  IOException createException(InputStream response, int code, String status)
          Create error exception from response and throw it
protected  HttpURLConnection createGet(String uri)
          Create a GET request connection to the URI
protected  HttpURLConnection createPost(String uri)
          Create a POST request connection to the URI
protected  HttpURLConnection createPut(String uri)
          Create a PUT request connection to the URI
protected  String createUri(String path)
          Create full URI from path
 void delete(String uri)
          Delete resource at URI.
 void delete(String uri, Object params)
          Delete resource at URI.
 GitHubResponse get(GitHubRequest request)
          Get response from URI and bind to specified type
protected  Object getBody(GitHubRequest request, InputStream stream)
          Get body from response inputs stream
 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
 InputStream getStream(GitHubRequest request)
          Get response stream from URI.
protected  InputStream getStream(HttpURLConnection request)
          Get stream from request
 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(InputStream response)
          Parse error from response
protected
<V> V
parseJson(InputStream stream, Type type)
          Parse JSON to specified type
 void post(String uri)
          Post to URI
<V> V
post(String uri, Object params, Type type)
          Post data to URI
 void put(String uri)
          Put to URI
<V> V
put(String uri, Object params, Type type)
          Put data to URI
protected  void sendParams(HttpURLConnection request, 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(String user, String password)
          Set credentials
 GitHubClient setOAuth2Token(String token)
          Set OAuth2 token
 GitHubClient setSerializeNulls(boolean serializeNulls)
          Set whether or not serialized data should include fields that are null.
 GitHubClient setUserAgent(String agent)
          Set the value to set as the user agent header on every request created.
protected  String toJson(Object object)
          Convert object to a JSON string
protected  GitHubClient updateRateLimits(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 String HEADER_CONTENT_TYPE
Content-Type header

See Also:
Constant Field Values

HEADER_ACCEPT

protected static final String HEADER_ACCEPT
Accept header

See Also:
Constant Field Values

HEADER_AUTHORIZATION

protected static final String HEADER_AUTHORIZATION
Authorization header

See Also:
Constant Field Values

HEADER_USER_AGENT

protected static final String HEADER_USER_AGENT
User-Agent header

See Also:
Constant Field Values

METHOD_GET

protected static final String METHOD_GET
METHOD_GET

See Also:
Constant Field Values

METHOD_PUT

protected static final String METHOD_PUT
METHOD_PUT

See Also:
Constant Field Values

METHOD_POST

protected static final String METHOD_POST
METHOD_POST

See Also:
Constant Field Values

METHOD_DELETE

protected static final String METHOD_DELETE
METHOD_DELETE

See Also:
Constant Field Values

USER_AGENT

protected static final 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 String baseUri
Base URI


prefix

protected final 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(String hostname)
Create client for host name

Parameters:
hostname -

GitHubClient

public GitHubClient(String hostname,
                    int port,
                    String scheme)
Create client for host, port, and scheme

Parameters:
hostname -
port -
scheme -
Method Detail

createClient

public static GitHubClient createClient(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(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

configureRequest

protected HttpURLConnection configureRequest(HttpURLConnection request)
Configure request with standard headers

Parameters:
request -
Returns:
configured request

configureUri

protected String configureUri(String uri)
Configure request URI

Parameters:
uri -
Returns:
configured URI

createConnection

protected HttpURLConnection createConnection(String uri)
                                      throws IOException
Create connection to URI

Parameters:
uri -
Returns:
connection
Throws:
IOException

createConnection

protected HttpURLConnection createConnection(String uri,
                                             String method)
                                      throws IOException
Create connection to URI

Parameters:
uri -
method -
Returns:
connection
Throws:
IOException

createGet

protected HttpURLConnection createGet(String uri)
                               throws IOException
Create a GET request connection to the URI

Parameters:
uri -
Returns:
connection
Throws:
IOException

createPost

protected HttpURLConnection createPost(String uri)
                                throws IOException
Create a POST request connection to the URI

Parameters:
uri -
Returns:
connection
Throws:
IOException

createPut

protected HttpURLConnection createPut(String uri)
                               throws IOException
Create a PUT request connection to the URI

Parameters:
uri -
Returns:
connection
Throws:
IOException

createDelete

protected HttpURLConnection createDelete(String uri)
                                  throws IOException
Create a DELETE request connection to the URI

Parameters:
uri -
Returns:
connection
Throws:
IOException

setCredentials

public GitHubClient setCredentials(String user,
                                   String password)
Set credentials

Parameters:
user -
password -
Returns:
this client

setOAuth2Token

public GitHubClient setOAuth2Token(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 String getUser()
Get the user that this client is currently authenticating as

Returns:
user or null if not authentication

toJson

protected String toJson(Object object)
                 throws IOException
Convert object to a JSON string

Parameters:
object -
Returns:
JSON string
Throws:
IOException

parseJson

protected <V> V parseJson(InputStream stream,
                          Type type)
               throws IOException
Parse JSON to specified type

Type Parameters:
V -
Parameters:
stream -
type -
Returns:
parsed type
Throws:
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(InputStream response)
                           throws IOException
Parse error from response

Parameters:
response -
Returns:
request error
Throws:
IOException

getBody

protected Object getBody(GitHubRequest request,
                         InputStream stream)
                  throws IOException
Get body from response inputs stream

Parameters:
request -
stream -
Returns:
parsed body
Throws:
IOException

createException

protected IOException createException(InputStream response,
                                      int code,
                                      String status)
Create error exception from response and throw it

Parameters:
response -
code -
status -
Returns:
non-null newly created IOException

post

public void post(String uri)
          throws IOException
Post to URI

Parameters:
uri -
Throws:
IOException

put

public void put(String uri)
         throws IOException
Put to URI

Parameters:
uri -
Throws:
IOException

delete

public void delete(String uri)
            throws IOException
Delete resource at URI. This method will throw an IOException when the response status is not a 204 (No Content).

Parameters:
uri -
Throws:
IOException

sendParams

protected void sendParams(HttpURLConnection request,
                          Object params)
                   throws IOException
Send parameters to output stream of request

Parameters:
request -
params -
Throws:
IOException

createUri

protected String createUri(String path)
Create full URI from path

Parameters:
path -
Returns:
uri

getStream

public InputStream getStream(GitHubRequest request)
                      throws IOException
Get response stream from URI. It is the responsibility of the calling method to close the returned stream.

Parameters:
request -
Returns:
stream
Throws:
IOException

getStream

protected InputStream getStream(HttpURLConnection request)
                         throws IOException
Get stream from request

Parameters:
request -
Returns:
stream
Throws:
IOException

get

public GitHubResponse get(GitHubRequest request)
                   throws IOException
Get response from URI and bind to specified type

Parameters:
request -
Returns:
response
Throws:
IOException

post

public <V> V post(String uri,
                  Object params,
                  Type type)
       throws IOException
Post data to URI

Type Parameters:
V -
Parameters:
uri -
params -
type -
Returns:
response
Throws:
IOException

put

public <V> V put(String uri,
                 Object params,
                 Type type)
      throws IOException
Put data to URI

Type Parameters:
V -
Parameters:
uri -
params -
type -
Returns:
response
Throws:
IOException

delete

public void delete(String uri,
                   Object params)
            throws 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:
IOException

updateRateLimits

protected GitHubClient updateRateLimits(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


Copyright © 2012. All Rights Reserved.