Files
github-api/apidocs/org/kohsuke/github/RateLimitChecker.html
2020-03-04 17:06:31 -08:00

454 lines
20 KiB
HTML

<!DOCTYPE HTML>
<!-- NewPage -->
<html lang="en">
<head>
<!-- Generated by javadoc (11.0.5) on Wed Mar 04 17:02:05 PST 2020 -->
<title>RateLimitChecker (GitHub API for Java 1.108 API)</title>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta name="dc.created" content="2020-03-04">
<link rel="stylesheet" type="text/css" href="../../../stylesheet.css" title="Style">
<link rel="stylesheet" type="text/css" href="../../../jquery/jquery-ui.css" title="Style">
<script type="text/javascript" src="../../../script.js"></script>
<script type="text/javascript" src="../../../jquery/jszip/dist/jszip.min.js"></script>
<script type="text/javascript" src="../../../jquery/jszip-utils/dist/jszip-utils.min.js"></script>
<!--[if IE]>
<script type="text/javascript" src="../../../jquery/jszip-utils/dist/jszip-utils-ie.min.js"></script>
<![endif]-->
<script type="text/javascript" src="../../../jquery/jquery-3.4.1.js"></script>
<script type="text/javascript" src="../../../jquery/jquery-ui.js"></script>
</head>
<body>
<script type="text/javascript"><!--
try {
if (location.href.indexOf('is-external=true') == -1) {
parent.document.title="RateLimitChecker (GitHub API for Java 1.108 API)";
}
}
catch(err) {
}
//-->
var data = {"i0":10,"i1":10};
var tabs = {65535:["t0","All Methods"],2:["t2","Instance Methods"],8:["t4","Concrete Methods"]};
var altColor = "altColor";
var rowColor = "rowColor";
var tableTab = "tableTab";
var activeTableTab = "activeTableTab";
var pathtoroot = "../../../";
var useModuleDirectories = true;
loadScripts(document, 'script');</script>
<noscript>
<div>JavaScript is disabled on your browser.</div>
</noscript>
<header role="banner">
<nav role="navigation">
<div class="fixedNav">
<!-- ========= START OF TOP NAVBAR ======= -->
<div class="topNav"><a id="navbar.top">
<!-- -->
</a>
<div class="skipNav"><a href="#skip.navbar.top" title="Skip navigation links">Skip navigation links</a></div>
<a id="navbar.top.firstrow">
<!-- -->
</a>
<ul class="navList" title="Navigation">
<li><a href="../../../index.html">Overview</a></li>
<li><a href="package-summary.html">Package</a></li>
<li class="navBarCell1Rev">Class</li>
<li><a href="class-use/RateLimitChecker.html">Use</a></li>
<li><a href="package-tree.html">Tree</a></li>
<li><a href="../../../deprecated-list.html">Deprecated</a></li>
<li><a href="../../../index-all.html">Index</a></li>
<li><a href="../../../help-doc.html">Help</a></li>
</ul>
</div>
<div class="subNav">
<ul class="navList" id="allclasses_navbar_top">
<li><a href="../../../allclasses.html">All&nbsp;Classes</a></li>
</ul>
<ul class="navListSearch">
<li><label for="search">SEARCH:</label>
<input type="text" id="search" value="search" disabled="disabled">
<input type="reset" id="reset" value="reset" disabled="disabled">
</li>
</ul>
<div>
<script type="text/javascript"><!--
allClassesLink = document.getElementById("allclasses_navbar_top");
if(window==top) {
allClassesLink.style.display = "block";
}
else {
allClassesLink.style.display = "none";
}
//-->
</script>
<noscript>
<div>JavaScript is disabled on your browser.</div>
</noscript>
</div>
<div>
<ul class="subNavList">
<li>Summary:&nbsp;</li>
<li><a href="#nested.class.summary">Nested</a>&nbsp;|&nbsp;</li>
<li><a href="#field.summary">Field</a>&nbsp;|&nbsp;</li>
<li><a href="#constructor.summary">Constr</a>&nbsp;|&nbsp;</li>
<li><a href="#method.summary">Method</a></li>
</ul>
<ul class="subNavList">
<li>Detail:&nbsp;</li>
<li><a href="#field.detail">Field</a>&nbsp;|&nbsp;</li>
<li><a href="#constructor.detail">Constr</a>&nbsp;|&nbsp;</li>
<li><a href="#method.detail">Method</a></li>
</ul>
</div>
<a id="skip.navbar.top">
<!-- -->
</a></div>
<!-- ========= END OF TOP NAVBAR ========= -->
</div>
<div class="navPadding">&nbsp;</div>
<script type="text/javascript"><!--
$('.navPadding').css('padding-top', $('.fixedNav').css("height"));
//-->
</script>
</nav>
</header>
<!-- ======== START OF CLASS DATA ======== -->
<main role="main">
<div class="header">
<div class="subTitle"><span class="packageLabelInType">Package</span>&nbsp;<a href="package-summary.html">org.kohsuke.github</a></div>
<h2 title="Class RateLimitChecker" class="title">Class RateLimitChecker</h2>
</div>
<div class="contentContainer">
<ul class="inheritance">
<li><a href="https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html?is-external=true" title="class or interface in java.lang" class="externalLink">java.lang.Object</a></li>
<li>
<ul class="inheritance">
<li>org.kohsuke.github.RateLimitChecker</li>
</ul>
</li>
</ul>
<div class="description">
<ul class="blockList">
<li class="blockList">
<dl>
<dt>Direct Known Subclasses:</dt>
<dd><code><a href="RateLimitChecker.LiteralValue.html" title="class in org.kohsuke.github">RateLimitChecker.LiteralValue</a></code></dd>
</dl>
<hr>
<pre>public abstract class <span class="typeNameLabel">RateLimitChecker</span>
extends <a href="https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html?is-external=true" title="class or interface in java.lang" class="externalLink">Object</a></pre>
<div class="block">A GitHub API Rate Limit Checker called before each request
<p>
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
<a href="GitHub.html#getRateLimit()"><code>GitHub.getRateLimit()</code></a>. This requests per interval is referred to as the "rate limit".
</p>
<p>
GitHub prefers that clients stop before exceeding their rate limit rather than stopping after they exceed it. The
<a href="RateLimitChecker.html" title="class in org.kohsuke.github"><code>RateLimitChecker</code></a> is called before each request to check the rate limit and wait if the checker criteria are
met.
</p>
<p>
Checking your rate limit using <a href="GitHub.html#getRateLimit()"><code>GitHub.getRateLimit()</code></a> does not effect your rate limit, but each <a href="GitHub.html" title="class in org.kohsuke.github"><code>GitHub</code></a>
instance will attempt to cache and reuse the last see rate limit rather than making a new request.
</p></div>
</li>
</ul>
</div>
<div class="summary">
<ul class="blockList">
<li class="blockList">
<!-- ======== NESTED CLASS SUMMARY ======== -->
<section role="region">
<ul class="blockList">
<li class="blockList"><a id="nested.class.summary">
<!-- -->
</a>
<h3>Nested Class Summary</h3>
<table class="memberSummary">
<caption><span>Nested Classes</span><span class="tabEnd">&nbsp;</span></caption>
<tr>
<th class="colFirst" scope="col">Modifier and Type</th>
<th class="colSecond" scope="col">Class</th>
<th class="colLast" scope="col">Description</th>
</tr>
<tr class="altColor">
<td class="colFirst"><code>static class&nbsp;</code></td>
<th class="colSecond" scope="row"><code><span class="memberNameLink"><a href="RateLimitChecker.LiteralValue.html" title="class in org.kohsuke.github">RateLimitChecker.LiteralValue</a></span></code></th>
<td class="colLast">
<div class="block">A <a href="RateLimitChecker.html" title="class in org.kohsuke.github"><code>RateLimitChecker</code></a> with a simple number as the limit.</div>
</td>
</tr>
</table>
</li>
</ul>
</section>
<!-- =========== FIELD SUMMARY =========== -->
<section role="region">
<ul class="blockList">
<li class="blockList"><a id="field.summary">
<!-- -->
</a>
<h3>Field Summary</h3>
<table class="memberSummary">
<caption><span>Fields</span><span class="tabEnd">&nbsp;</span></caption>
<tr>
<th class="colFirst" scope="col">Modifier and Type</th>
<th class="colSecond" scope="col">Field</th>
<th class="colLast" scope="col">Description</th>
</tr>
<tr class="altColor">
<td class="colFirst"><code>static <a href="RateLimitChecker.html" title="class in org.kohsuke.github">RateLimitChecker</a></code></td>
<th class="colSecond" scope="row"><code><span class="memberNameLink"><a href="#NONE">NONE</a></span></code></th>
<td class="colLast">&nbsp;</td>
</tr>
</table>
</li>
</ul>
</section>
<!-- ======== CONSTRUCTOR SUMMARY ======== -->
<section role="region">
<ul class="blockList">
<li class="blockList"><a id="constructor.summary">
<!-- -->
</a>
<h3>Constructor Summary</h3>
<table class="memberSummary">
<caption><span>Constructors</span><span class="tabEnd">&nbsp;</span></caption>
<tr>
<th class="colFirst" scope="col">Constructor</th>
<th class="colLast" scope="col">Description</th>
</tr>
<tr class="altColor">
<th class="colConstructorName" scope="row"><code><span class="memberNameLink"><a href="#%3Cinit%3E()">RateLimitChecker</a></span>()</code></th>
<td class="colLast">&nbsp;</td>
</tr>
</table>
</li>
</ul>
</section>
<!-- ========== METHOD SUMMARY =========== -->
<section role="region">
<ul class="blockList">
<li class="blockList"><a id="method.summary">
<!-- -->
</a>
<h3>Method Summary</h3>
<table class="memberSummary">
<caption><span id="t0" class="activeTableTab"><span>All Methods</span><span class="tabEnd">&nbsp;</span></span><span id="t2" class="tableTab"><span><a href="javascript:show(2);">Instance Methods</a></span><span class="tabEnd">&nbsp;</span></span><span id="t4" class="tableTab"><span><a href="javascript:show(8);">Concrete Methods</a></span><span class="tabEnd">&nbsp;</span></span></caption>
<tr>
<th class="colFirst" scope="col">Modifier and Type</th>
<th class="colSecond" scope="col">Method</th>
<th class="colLast" scope="col">Description</th>
</tr>
<tr id="i0" class="altColor">
<td class="colFirst"><code>protected boolean</code></td>
<th class="colSecond" scope="row"><code><span class="memberNameLink"><a href="#checkRateLimit(org.kohsuke.github.GHRateLimit.Record,long)">checkRateLimit</a></span>&#8203;(<a href="GHRateLimit.Record.html" title="class in org.kohsuke.github">GHRateLimit.Record</a>&nbsp;rateLimitRecord,
long&nbsp;count)</code></th>
<td class="colLast">
<div class="block">Decides whether the current request exceeds the allowed "rate limit" budget.</div>
</td>
</tr>
<tr id="i1" class="rowColor">
<td class="colFirst"><code>protected boolean</code></td>
<th class="colSecond" scope="row"><code><span class="memberNameLink"><a href="#sleepUntilReset(org.kohsuke.github.GHRateLimit.Record)">sleepUntilReset</a></span>&#8203;(<a href="GHRateLimit.Record.html" title="class in org.kohsuke.github">GHRateLimit.Record</a>&nbsp;record)</code></th>
<td class="colLast">&nbsp;</td>
</tr>
</table>
<ul class="blockList">
<li class="blockList"><a id="methods.inherited.from.class.java.lang.Object">
<!-- -->
</a>
<h3>Methods inherited from class&nbsp;java.lang.<a href="https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html?is-external=true" title="class or interface in java.lang" class="externalLink">Object</a></h3>
<code><a href="https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html?is-external=true#clone()" title="class or interface in java.lang" class="externalLink">clone</a>, <a href="https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html?is-external=true#equals(java.lang.Object)" title="class or interface in java.lang" class="externalLink">equals</a>, <a href="https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html?is-external=true#finalize()" title="class or interface in java.lang" class="externalLink">finalize</a>, <a href="https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html?is-external=true#getClass()" title="class or interface in java.lang" class="externalLink">getClass</a>, <a href="https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html?is-external=true#hashCode()" title="class or interface in java.lang" class="externalLink">hashCode</a>, <a href="https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html?is-external=true#notify()" title="class or interface in java.lang" class="externalLink">notify</a>, <a href="https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html?is-external=true#notifyAll()" title="class or interface in java.lang" class="externalLink">notifyAll</a>, <a href="https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html?is-external=true#toString()" title="class or interface in java.lang" class="externalLink">toString</a>, <a href="https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html?is-external=true#wait()" title="class or interface in java.lang" class="externalLink">wait</a>, <a href="https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html?is-external=true#wait(long)" title="class or interface in java.lang" class="externalLink">wait</a>, <a href="https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html?is-external=true#wait(long,int)" title="class or interface in java.lang" class="externalLink">wait</a></code></li>
</ul>
</li>
</ul>
</section>
</li>
</ul>
</div>
<div class="details">
<ul class="blockList">
<li class="blockList">
<!-- ============ FIELD DETAIL =========== -->
<section role="region">
<ul class="blockList">
<li class="blockList"><a id="field.detail">
<!-- -->
</a>
<h3>Field Detail</h3>
<a id="NONE">
<!-- -->
</a>
<ul class="blockListLast">
<li class="blockList">
<h4>NONE</h4>
<pre>public static final&nbsp;<a href="RateLimitChecker.html" title="class in org.kohsuke.github">RateLimitChecker</a> NONE</pre>
</li>
</ul>
</li>
</ul>
</section>
<!-- ========= CONSTRUCTOR DETAIL ======== -->
<section role="region">
<ul class="blockList">
<li class="blockList"><a id="constructor.detail">
<!-- -->
</a>
<h3>Constructor Detail</h3>
<a id="&lt;init&gt;()">
<!-- -->
</a>
<ul class="blockListLast">
<li class="blockList">
<h4>RateLimitChecker</h4>
<pre>public&nbsp;RateLimitChecker()</pre>
</li>
</ul>
</li>
</ul>
</section>
<!-- ============ METHOD DETAIL ========== -->
<section role="region">
<ul class="blockList">
<li class="blockList"><a id="method.detail">
<!-- -->
</a>
<h3>Method Detail</h3>
<a id="checkRateLimit(org.kohsuke.github.GHRateLimit.Record,long)">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>checkRateLimit</h4>
<pre class="methodSignature">protected&nbsp;boolean&nbsp;checkRateLimit&#8203;(<a href="GHRateLimit.Record.html" title="class in org.kohsuke.github">GHRateLimit.Record</a>&nbsp;rateLimitRecord,
long&nbsp;count)
throws <a href="https://docs.oracle.com/javase/8/docs/api/java/lang/InterruptedException.html?is-external=true" title="class or interface in java.lang" class="externalLink">InterruptedException</a></pre>
<div class="block">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 <code>true</code>. Implementers are
free to choose whatever strategy they prefer for what is considered to exceed the budget and how long to sleep.
<p>
The caller of this method figures out which <a href="GHRateLimit.Record.html" title="class in org.kohsuke.github"><code>GHRateLimit.Record</code></a> applies for the current request add
provides it to this method.
</p>
<p>
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
<code>GitHubRateLimitChecker</code> may choose to add more sleep times when a checker indicates the rate limit was
exceeded.
</p>
<p>
As long as this method returns <code>true</code> it is guaranteed that <code>GitHubRateLimitChecker</code> will get updated
rate limit information and call this method again with <code>count</code> incremented by one. After this method
returns <code>true</code> at least once, the calling <code>GitHubRateLimitChecker</code> may choose to wait some additional
period of time between calls to this checker.
</p>
<p>
After this checker returns <code>false</code>, the calling <code>GitHubRateLimitChecker</code> will let the request
continue. If this method returned <code>true</code> at least once for a particular request, the calling
<code>GitHubRateLimitChecker</code> may choose to wait some additional period of time before letting the request be
sent.
</p></div>
<dl>
<dt><span class="paramLabel">Parameters:</span></dt>
<dd><code>rateLimitRecord</code> - the current <a href="GHRateLimit.Record.html" title="class in org.kohsuke.github"><code>GHRateLimit.Record</code></a> to check against.</dd>
<dd><code>count</code> - the number of times in a row this method has been called for the current request</dd>
<dt><span class="returnLabel">Returns:</span></dt>
<dd><code>false</code> if the current request does not exceed the allowed budget, <code>true</code> if the current
request exceeded the budget.</dd>
<dt><span class="throwsLabel">Throws:</span></dt>
<dd><code><a href="https://docs.oracle.com/javase/8/docs/api/java/lang/InterruptedException.html?is-external=true" title="class or interface in java.lang" class="externalLink">InterruptedException</a></code> - if the thread is interrupted while sleeping</dd>
</dl>
</li>
</ul>
<a id="sleepUntilReset(org.kohsuke.github.GHRateLimit.Record)">
<!-- -->
</a>
<ul class="blockListLast">
<li class="blockList">
<h4>sleepUntilReset</h4>
<pre class="methodSignature">protected final&nbsp;boolean&nbsp;sleepUntilReset&#8203;(<a href="GHRateLimit.Record.html" title="class in org.kohsuke.github">GHRateLimit.Record</a>&nbsp;record)
throws <a href="https://docs.oracle.com/javase/8/docs/api/java/lang/InterruptedException.html?is-external=true" title="class or interface in java.lang" class="externalLink">InterruptedException</a></pre>
<dl>
<dt><span class="throwsLabel">Throws:</span></dt>
<dd><code><a href="https://docs.oracle.com/javase/8/docs/api/java/lang/InterruptedException.html?is-external=true" title="class or interface in java.lang" class="externalLink">InterruptedException</a></code></dd>
</dl>
</li>
</ul>
</li>
</ul>
</section>
</li>
</ul>
</div>
</div>
</main>
<!-- ========= END OF CLASS DATA ========= -->
<footer role="contentinfo">
<nav role="navigation">
<!-- ======= START OF BOTTOM NAVBAR ====== -->
<div class="bottomNav"><a id="navbar.bottom">
<!-- -->
</a>
<div class="skipNav"><a href="#skip.navbar.bottom" title="Skip navigation links">Skip navigation links</a></div>
<a id="navbar.bottom.firstrow">
<!-- -->
</a>
<ul class="navList" title="Navigation">
<li><a href="../../../index.html">Overview</a></li>
<li><a href="package-summary.html">Package</a></li>
<li class="navBarCell1Rev">Class</li>
<li><a href="class-use/RateLimitChecker.html">Use</a></li>
<li><a href="package-tree.html">Tree</a></li>
<li><a href="../../../deprecated-list.html">Deprecated</a></li>
<li><a href="../../../index-all.html">Index</a></li>
<li><a href="../../../help-doc.html">Help</a></li>
</ul>
</div>
<div class="subNav">
<ul class="navList" id="allclasses_navbar_bottom">
<li><a href="../../../allclasses.html">All&nbsp;Classes</a></li>
</ul>
<div>
<script type="text/javascript"><!--
allClassesLink = document.getElementById("allclasses_navbar_bottom");
if(window==top) {
allClassesLink.style.display = "block";
}
else {
allClassesLink.style.display = "none";
}
//-->
</script>
<noscript>
<div>JavaScript is disabled on your browser.</div>
</noscript>
</div>
<div>
<ul class="subNavList">
<li>Summary:&nbsp;</li>
<li><a href="#nested.class.summary">Nested</a>&nbsp;|&nbsp;</li>
<li><a href="#field.summary">Field</a>&nbsp;|&nbsp;</li>
<li><a href="#constructor.summary">Constr</a>&nbsp;|&nbsp;</li>
<li><a href="#method.summary">Method</a></li>
</ul>
<ul class="subNavList">
<li>Detail:&nbsp;</li>
<li><a href="#field.detail">Field</a>&nbsp;|&nbsp;</li>
<li><a href="#constructor.detail">Constr</a>&nbsp;|&nbsp;</li>
<li><a href="#method.detail">Method</a></li>
</ul>
</div>
<a id="skip.navbar.bottom">
<!-- -->
</a></div>
<!-- ======== END OF BOTTOM NAVBAR ======= -->
</nav>
<p class="legalCopy"><small>Copyright &#169; 2020. All rights reserved.</small></p>
</footer>
</body>
</html>