org.kohsuke.github

Class RateLimitChecker

java.lang.Object

org.kohsuke.github.RateLimitChecker

Direct Known Subclasses:

RateLimitChecker.LiteralValue

public abstract class RateLimitChecker
extends Object

A GitHub API Rate Limit Checker called before each request

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 see rate limit rather than making a new request.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	RateLimitChecker.LiteralValue A RateLimitChecker with a simple number as the limit.

Field Summary

Fields

Modifier and Type	Field and Description
static RateLimitChecker	NONE

Constructor Summary

Constructors

Constructor and Description
RateLimitChecker()

Method Summary

Modifier and Type	Method and Description
protected boolean	checkRateLimit(GHRateLimit.Record rateLimitRecord, long count) Decides whether the current request exceeds the allowed "rate limit" budget.
protected boolean	sleepUntilReset(GHRateLimit.Record record)

Methods inherited from class java.lang.Object

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

Field Detail

NONE

public static final RateLimitChecker NONE

Constructor Detail

RateLimitChecker

public RateLimitChecker()

Method Detail

checkRateLimit

protected boolean checkRateLimit(GHRateLimit.Record rateLimitRecord,
                                 long count)
                          throws InterruptedException

Decides whether the current request exceeds the allowed "rate limit" budget. If this determines the rate limit will be exceeded, this method should sleep for some amount of time and must return true. Implementers are free to choose whatever strategy they prefer for what is considered to exceed the budget and how long to sleep.

The caller of this method figures out which GHRateLimit.Record applies for the current request add provides it to this method.

It is important to remember that rate limit reset times are only accurate to the second. Trying to sleep to exactly the reset time would be likely to produce worse behavior rather than better. For this reason GitHubRateLimitChecker may choose to add more sleep times when a checker indicates the rate limit was exceeded.

As long as this method returns true it is guaranteed that GitHubRateLimitChecker will get updated rate limit information and call this method again with count incremented by one. After this method returns true at least once, the calling GitHubRateLimitChecker may choose to wait some additional period of time between calls to this checker.

After this checker returns false, the calling GitHubRateLimitChecker will let the request continue. If this method returned true at least once for a particular request, the calling GitHubRateLimitChecker may choose to wait some additional period of time before letting the request be sent.

Parameters:

rateLimitRecord - the current GHRateLimit.Record to check against.

count - the number of times in a row this method has been called for the current request

Returns:

false if the current request does not exceed the allowed budget, true if the current request exceeded the budget.

Throws:

InterruptedException - if the thread is interrupted while sleeping

sleepUntilReset

protected final boolean sleepUntilReset(GHRateLimit.Record record)
                                 throws InterruptedException

Throws:

InterruptedException