org.kohsuke.github

Class GitHubBuilder

java.lang.Object

org.kohsuke.github.GitHubBuilder

All Implemented Interfaces:

Cloneable

public class GitHubBuilder
extends Object
implements Cloneable

Configures connection details and produces GitHub.

Since:

1.59

Constructor Summary

Constructors

Constructor and Description
GitHubBuilder() Instantiates a new Git hub builder.

Method Summary

Modifier and Type	Method and Description
GitHub	build() Builds a GitHub instance.
GitHubBuilder	clone()
static GitHubBuilder	fromEnvironment() Creates GitHubBuilder by picking up coordinates from environment variables.
static GitHubBuilder	fromEnvironment(String loginVariableName, String passwordVariableName, String oauthVariableName) Deprecated. Use fromEnvironment() to pick up standard set of environment variables, so that different clients of this library will all recognize one consistent set of coordinates.
static GitHubBuilder	fromEnvironment(String loginVariableName, String passwordVariableName, String oauthVariableName, String endpointVariableName) Deprecated. Use fromEnvironment() to pick up standard set of environment variables, so that different clients of this library will all recognize one consistent set of coordinates.
static GitHubBuilder	fromProperties(Properties props) From properties git hub builder.
static GitHubBuilder	fromPropertyFile() From property file git hub builder.
static GitHubBuilder	fromPropertyFile(String propertyFileName) From property file git hub builder.
GitHubBuilder	withAbuseLimitHandler(AbuseLimitHandler handler) Adds a AbuseLimitHandler to this GitHubBuilder.
GitHubBuilder	withAppInstallationToken(String appInstallationToken) Configures GitHubBuilder with Installation Token generated by the GitHub Application
GitHubBuilder	withConnector(HttpConnector connector) With connector git hub builder.
GitHubBuilder	withEndpoint(String endpoint) With endpoint git hub builder.
GitHubBuilder	withJwtToken(String jwtToken) With jwt token git hub builder.
GitHubBuilder	withOAuthToken(String oauthToken) With o auth token git hub builder.
GitHubBuilder	withOAuthToken(String oauthToken, String user) With o auth token git hub builder.
GitHubBuilder	withPassword(String user, String password) With password git hub builder.
GitHubBuilder	withProxy(Proxy p) Configures connector that uses HTTP library in JRE but use a specific proxy, instead of the system default one.
GitHubBuilder	withRateLimitChecker(RateLimitChecker coreRateLimitChecker) Adds a RateLimitChecker to this GitHubBuilder.
GitHubBuilder	withRateLimitHandler(RateLimitHandler handler) Adds a RateLimitHandler to this GitHubBuilder.

Methods inherited from class java.lang.Object

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

Constructor Detail

GitHubBuilder

public GitHubBuilder()

Instantiates a new Git hub builder.

Method Detail

fromEnvironment

public static GitHubBuilder fromEnvironment(String loginVariableName,
                                            String passwordVariableName,
                                            String oauthVariableName)
                                     throws IOException

Deprecated. Use fromEnvironment() to pick up standard set of environment variables, so that different clients of this library will all recognize one consistent set of coordinates.

From environment git hub builder.

Parameters:

loginVariableName - the login variable name

passwordVariableName - the password variable name

oauthVariableName - the oauth variable name

Returns:

the git hub builder

Throws:

IOException - the io exception

fromEnvironment

public static GitHubBuilder fromEnvironment(String loginVariableName,
                                            String passwordVariableName,
                                            String oauthVariableName,
                                            String endpointVariableName)
                                     throws IOException

Deprecated. Use fromEnvironment() to pick up standard set of environment variables, so that different clients of this library will all recognize one consistent set of coordinates.

From environment git hub builder.

Parameters:

loginVariableName - the login variable name

passwordVariableName - the password variable name

oauthVariableName - the oauth variable name

endpointVariableName - the endpoint variable name

Returns:

the git hub builder

Throws:

IOException - the io exception

fromEnvironment

public static GitHubBuilder fromEnvironment()
                                     throws IOException

Creates GitHubBuilder by picking up coordinates from environment variables.

The following environment variables are recognized:

• GITHUB_LOGIN: username like 'kohsuke'
• GITHUB_PASSWORD: raw password
• GITHUB_OAUTH: OAuth token to login
• GITHUB_ENDPOINT: URL of the API endpoint
• GITHUB_JWT: JWT token to login

See class javadoc for the relationship between these coordinates.

For backward compatibility, the following environment variables are recognized but discouraged: login, password, oauth

Returns:

the git hub builder

Throws:

IOException - the io exception

fromPropertyFile

public static GitHubBuilder fromPropertyFile()
                                      throws IOException

From property file git hub builder.

Returns:

the git hub builder

Throws:

IOException - the io exception

fromPropertyFile

public static GitHubBuilder fromPropertyFile(String propertyFileName)
                                      throws IOException

From property file git hub builder.

Parameters:

propertyFileName - the property file name

Returns:

the git hub builder

Throws:

IOException - the io exception

fromProperties

public static GitHubBuilder fromProperties(Properties props)

From properties git hub builder.

Parameters:

props - the props

Returns:

the git hub builder

withEndpoint

public GitHubBuilder withEndpoint(String endpoint)

With endpoint git hub builder.

Parameters:

endpoint - The URL of GitHub (or GitHub enterprise) API endpoint, such as "https://api.github.com" or "http://ghe.acme.com/api/v3". Note that GitHub Enterprise has /api/v3 in the URL. For historical reasons, this parameter still accepts the bare domain name, but that's considered deprecated.

Returns:

the git hub builder

withPassword

public GitHubBuilder withPassword(String user,
                                  String password)

With password git hub builder.

Parameters:

user - the user

password - the password

Returns:

the git hub builder

withOAuthToken

public GitHubBuilder withOAuthToken(String oauthToken)

With o auth token git hub builder.

Parameters:

oauthToken - the oauth token

Returns:

the git hub builder

withOAuthToken

public GitHubBuilder withOAuthToken(String oauthToken,
                                    String user)

With o auth token git hub builder.

Parameters:

oauthToken - the oauth token

user - the user

Returns:

the git hub builder

withAppInstallationToken

public GitHubBuilder withAppInstallationToken(String appInstallationToken)

Configures GitHubBuilder with Installation Token generated by the GitHub Application

Parameters:

appInstallationToken - A string containing the GitHub App installation token

Returns:

the configured Builder from given GitHub App installation token.

See Also:

GHAppInstallation#createToken(java.util.Map)

withJwtToken

public GitHubBuilder withJwtToken(String jwtToken)

With jwt token git hub builder.

Parameters:

jwtToken - the jwt token

Returns:

the git hub builder

withConnector

public GitHubBuilder withConnector(HttpConnector connector)

With connector git hub builder.

Parameters:

connector - the connector

Returns:

the git hub builder

withRateLimitHandler

public GitHubBuilder withRateLimitHandler(RateLimitHandler handler)

Adds a RateLimitHandler to this GitHubBuilder.

GitHub allots a certain number of requests to each user or application per period of time (usually per hour). The number of requests remaining is returned in the response header and can also be requested using GitHub.getRateLimit(). This requests per interval is referred to as the "rate limit".

When the remaining number of requests reaches zero, the next request will return an error. If this happens, RateLimitHandler.onError(IOException, HttpURLConnection) will be called.

NOTE: GitHub treats clients that exceed their rate limit very harshly. If possible, clients should avoid exceeding their rate limit. Consider adding a RateLimitChecker to automatically check the rate limit for each request and wait if needed.

Parameters:

handler - the handler

Returns:

the git hub builder

See Also:

withRateLimitChecker(RateLimitChecker)

withAbuseLimitHandler

public GitHubBuilder withAbuseLimitHandler(AbuseLimitHandler handler)

Adds a AbuseLimitHandler to this GitHubBuilder.

When a client sends too many requests in a short time span, GitHub may return an error and set a header telling the client to not make any more request for some period of time. If this happens, AbuseLimitHandler.onError(IOException, HttpURLConnection) will be called.

Parameters:

handler - the handler

Returns:

the git hub builder

withRateLimitChecker

public GitHubBuilder withRateLimitChecker(@Nonnull
                                          RateLimitChecker coreRateLimitChecker)

Adds a RateLimitChecker to this GitHubBuilder.

GitHub allots a certain number of requests to each user or application per period of time (usually per hour). The number of requests remaining is returned in the response header and can also be requested using GitHub.getRateLimit(). This requests per interval is referred to as the "rate limit".

GitHub prefers that clients stop before exceeding their rate limit rather than stopping after they exceed it. The RateLimitChecker is called before each request to check the rate limit and wait if the checker criteria are met.

Checking your rate limit using GitHub.getRateLimit() does not effect your rate limit, but each GitHub instance will attempt to cache and reuse the last seen rate limit rather than making a new request.

Parameters:

coreRateLimitChecker - the RateLimitChecker for core GitHub API requests

Returns:

the git hub builder

withProxy

public GitHubBuilder withProxy(Proxy p)

Configures connector that uses HTTP library in JRE but use a specific proxy, instead of the system default one.

Parameters:

p - the p

Returns:

the git hub builder

build

public GitHub build()
             throws IOException

Builds a GitHub instance.

Returns:

the git hub

Throws:

IOException - the io exception

clone

public GitHubBuilder clone()

Overrides:

clone in class Object