1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> 2 <!--NewPage--> 3 <HTML> 4 <HEAD> 5 <!-- Generated by javadoc (build 1.6.0-google-internal) on Mon Jan 04 20:48:00 PST 2010 --> 6 <TITLE> 7 TimeLimiter (Guava Libraries 2010.01.04) 8 </TITLE> 9 10 <META NAME="date" CONTENT="2010-01-04"> 11 12 <LINK REL ="stylesheet" TYPE="text/css" HREF="../../../../../stylesheet.css" TITLE="Style"> 13 14 <SCRIPT type="text/javascript"> 15 function windowTitle() 16 { 17 if (location.href.indexOf('is-external=true') == -1) { 18 parent.document.title="TimeLimiter (Guava Libraries 2010.01.04)"; 19 } 20 } 21 </SCRIPT> 22 <NOSCRIPT> 23 </NOSCRIPT> 24 25 </HEAD> 26 27 <BODY BGCOLOR="white" onload="windowTitle();"> 28 <HR> 29 30 31 <!-- ========= START OF TOP NAVBAR ======= --> 32 <A NAME="navbar_top"><!-- --></A> 33 <A HREF="#skip-navbar_top" title="Skip navigation links"></A> 34 <TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0" SUMMARY=""> 35 <TR> 36 <TD COLSPAN=2 BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> 37 <A NAME="navbar_top_firstrow"><!-- --></A> 38 <TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3" SUMMARY=""> 39 <TR ALIGN="center" VALIGN="top"> 40 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A> </TD> 41 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-summary.html"><FONT CLASS="NavBarFont1"><B>Package</B></FONT></A> </TD> 42 <TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> <FONT CLASS="NavBarFont1Rev"><B>Class</B></FONT> </TD> 43 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="class-use/TimeLimiter.html"><FONT CLASS="NavBarFont1"><B>Use</B></FONT></A> </TD> 44 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A> </TD> 45 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A> </TD> 46 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A> </TD> 47 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A> </TD> 48 </TR> 49 </TABLE> 50 </TD> 51 <TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM> 52 </EM> 53 </TD> 54 </TR> 55 56 <TR> 57 <TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2"> 58 <A HREF="../../../../../com/google/common/util/concurrent/SimpleTimeLimiter.html" title="class in com.google.common.util.concurrent"><B>PREV CLASS</B></A> 59 <A HREF="../../../../../com/google/common/util/concurrent/UncheckedTimeoutException.html" title="class in com.google.common.util.concurrent"><B>NEXT CLASS</B></A></FONT></TD> 60 <TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2"> 61 <A HREF="../../../../../index.html?com/google/common/util/concurrent/TimeLimiter.html" target="_top"><B>FRAMES</B></A> 62 <A HREF="TimeLimiter.html" target="_top"><B>NO FRAMES</B></A> 63 <SCRIPT type="text/javascript"> 64 <!-- 65 if(window==top) { 66 document.writeln('<A HREF="../../../../../allclasses-noframe.html"><B>All Classes</B></A>'); 67 } 68 //--> 69 </SCRIPT> 70 <NOSCRIPT> 71 <A HREF="../../../../../allclasses-noframe.html"><B>All Classes</B></A> 72 </NOSCRIPT> 73 74 75 </FONT></TD> 76 </TR> 77 <TR> 78 <TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2"> 79 SUMMARY: NESTED | FIELD | CONSTR | <A HREF="#method_summary">METHOD</A></FONT></TD> 80 <TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2"> 81 DETAIL: FIELD | CONSTR | <A HREF="#method_detail">METHOD</A></FONT></TD> 82 </TR> 83 </TABLE> 84 <A NAME="skip-navbar_top"></A> 85 <!-- ========= END OF TOP NAVBAR ========= --> 86 87 <HR> 88 <!-- ======== START OF CLASS DATA ======== --> 89 <H2> 90 <FONT SIZE="-1"> 91 com.google.common.util.concurrent</FONT> 92 <BR> 93 Interface TimeLimiter</H2> 94 <DL> 95 <DT><B>All Known Implementing Classes:</B> <DD><A HREF="../../../../../com/google/common/util/concurrent/FakeTimeLimiter.html" title="class in com.google.common.util.concurrent">FakeTimeLimiter</A>, <A HREF="../../../../../com/google/common/util/concurrent/SimpleTimeLimiter.html" title="class in com.google.common.util.concurrent">SimpleTimeLimiter</A></DD> 96 </DL> 97 <HR> 98 <DL> 99 <DT><PRE>public interface <B>TimeLimiter</B></DL> 100 </PRE> 101 102 <P> 103 Produces proxies that impose a time limit on method 104 calls to the proxied object. For example, to return the value of 105 <code>target.someMethod()</code>, but substitute <code>DEFAULT_VALUE</code> if this 106 method call takes over 50 ms, you can use this code: 107 <pre> 108 TimeLimiter limiter = . . .; 109 TargetType proxy = limiter.newProxy( 110 target, TargetType.class, 50, TimeUnit.MILLISECONDS); 111 try { 112 return proxy.someMethod(); 113 } catch (UncheckedTimeoutException e) { 114 return DEFAULT_VALUE; 115 } 116 </pre> 117 Please see <code>SimpleTimeLimiterTest</code> for more usage examples. 118 <P> 119 120 <P> 121 <DL> 122 <DT><B>Since:</B></DT> 123 <DD>2009.09.15 <b>tentative</b></DD> 124 <DT><B>Author:</B></DT> 125 <DD>Kevin Bourrillion</DD> 126 </DL> 127 <HR> 128 129 <P> 130 131 <!-- ========== METHOD SUMMARY =========== --> 132 133 <A NAME="method_summary"><!-- --></A> 134 <TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY=""> 135 <TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor"> 136 <TH ALIGN="left" COLSPAN="2"><FONT SIZE="+2"> 137 <B>Method Summary</B></FONT></TH> 138 </TR> 139 <TR BGCOLOR="white" CLASS="TableRowColor"> 140 <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1"> 141 <CODE> 142 <TABLE BORDER="0" CELLPADDING="0" CELLSPACING="0" SUMMARY=""> 143 <TR ALIGN="right" VALIGN=""> 144 <TD NOWRAP><FONT SIZE="-1"> 145 <CODE><T> T</CODE></FONT></TD> 146 </TR> 147 </TABLE> 148 </CODE></FONT></TD> 149 <TD><CODE><B><A HREF="../../../../../com/google/common/util/concurrent/TimeLimiter.html#callWithTimeout(java.util.concurrent.Callable, long, java.util.concurrent.TimeUnit, boolean)">callWithTimeout</A></B>(<A HREF="http://java.sun.com/javase/6/docs/api/java/util/concurrent/Callable.html?is-external=true" title="class or interface in java.util.concurrent">Callable</A><T> callable, 150 long timeoutDuration, 151 <A HREF="http://java.sun.com/javase/6/docs/api/java/util/concurrent/TimeUnit.html?is-external=true" title="class or interface in java.util.concurrent">TimeUnit</A> timeoutUnit, 152 boolean interruptible)</CODE> 153 154 <BR> 155 Invokes a specified Callable, timing out after the specified time limit.</TD> 156 </TR> 157 <TR BGCOLOR="white" CLASS="TableRowColor"> 158 <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1"> 159 <CODE> 160 <TABLE BORDER="0" CELLPADDING="0" CELLSPACING="0" SUMMARY=""> 161 <TR ALIGN="right" VALIGN=""> 162 <TD NOWRAP><FONT SIZE="-1"> 163 <CODE><T> T</CODE></FONT></TD> 164 </TR> 165 </TABLE> 166 </CODE></FONT></TD> 167 <TD><CODE><B><A HREF="../../../../../com/google/common/util/concurrent/TimeLimiter.html#newProxy(T, java.lang.Class, long, java.util.concurrent.TimeUnit)">newProxy</A></B>(T target, 168 <A HREF="http://java.sun.com/javase/6/docs/api/java/lang/Class.html?is-external=true" title="class or interface in java.lang">Class</A><T> interfaceType, 169 long timeoutDuration, 170 <A HREF="http://java.sun.com/javase/6/docs/api/java/util/concurrent/TimeUnit.html?is-external=true" title="class or interface in java.util.concurrent">TimeUnit</A> timeoutUnit)</CODE> 171 172 <BR> 173 Returns an instance of <code>interfaceType</code> that delegates all method 174 calls to the <code>target</code> object, enforcing the specified time limit on 175 each call.</TD> 176 </TR> 177 </TABLE> 178 179 <P> 180 181 <!-- ============ METHOD DETAIL ========== --> 182 183 <A NAME="method_detail"><!-- --></A> 184 <TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY=""> 185 <TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor"> 186 <TH ALIGN="left" COLSPAN="1"><FONT SIZE="+2"> 187 <B>Method Detail</B></FONT></TH> 188 </TR> 189 </TABLE> 190 191 <A NAME="newProxy(java.lang.Object,java.lang.Class,long,java.util.concurrent.TimeUnit)"><!-- --></A><A NAME="newProxy(T, java.lang.Class, long, java.util.concurrent.TimeUnit)"><!-- --></A><H3> 192 newProxy</H3> 193 <PRE> 194 <T> T <B>newProxy</B>(T target, 195 <A HREF="http://java.sun.com/javase/6/docs/api/java/lang/Class.html?is-external=true" title="class or interface in java.lang">Class</A><T> interfaceType, 196 long timeoutDuration, 197 <A HREF="http://java.sun.com/javase/6/docs/api/java/util/concurrent/TimeUnit.html?is-external=true" title="class or interface in java.util.concurrent">TimeUnit</A> timeoutUnit)</PRE> 198 <DL> 199 <DD>Returns an instance of <code>interfaceType</code> that delegates all method 200 calls to the <code>target</code> object, enforcing the specified time limit on 201 each call. This time-limited delegation is also performed for calls to 202 <A HREF="http://java.sun.com/javase/6/docs/api/java/lang/Object.html?is-external=true#equals(java.lang.Object)" title="class or interface in java.lang"><CODE>Object.equals(java.lang.Object)</CODE></A>, <A HREF="http://java.sun.com/javase/6/docs/api/java/lang/Object.html?is-external=true#hashCode()" title="class or interface in java.lang"><CODE>Object.hashCode()</CODE></A>, and 203 <A HREF="http://java.sun.com/javase/6/docs/api/java/lang/Object.html?is-external=true#toString()" title="class or interface in java.lang"><CODE>Object.toString()</CODE></A>. 204 <p> 205 If the target method call finishes before the limit is reached, the return 206 value or exception is propagated to the caller exactly as-is. If, on the 207 other hand, the time limit is reached, the proxy will attempt to abort the 208 call to the target, and will throw an <A HREF="../../../../../com/google/common/util/concurrent/UncheckedTimeoutException.html" title="class in com.google.common.util.concurrent"><CODE>UncheckedTimeoutException</CODE></A> to 209 the caller. 210 <p> 211 It is important to note that the primary purpose of the proxy object is to 212 return control to the caller when the timeout elapses; aborting the target 213 method call is of secondary concern. The particular nature and strength 214 of the guarantees made by the proxy is implementation-dependent. However, 215 it is important that each of the methods on the target object behaves 216 appropriately when its thread is interrupted. 217 <P> 218 <DD><DL> 219 <DT><B>Parameters:</B><DD><CODE>target</CODE> - the object to proxy<DD><CODE>interfaceType</CODE> - the interface you wish the returned proxy to 220 implement<DD><CODE>timeoutDuration</CODE> - with timeoutUnit, the maximum length of time that 221 callers are willing to wait on each method call to the proxy<DD><CODE>timeoutUnit</CODE> - with timeoutDuration, the maximum length of time that 222 callers are willing to wait on each method call to the proxy 223 <DT><B>Returns:</B><DD>a time-limiting proxy 224 <DT><B>Throws:</B> 225 <DD><CODE><A HREF="http://java.sun.com/javase/6/docs/api/java/lang/IllegalArgumentException.html?is-external=true" title="class or interface in java.lang">IllegalArgumentException</A></CODE> - if <code>interfaceType</code> is a regular 226 class, enum, or annotation type, rather than an interface</DL> 227 </DD> 228 </DL> 229 <HR> 230 231 <A NAME="callWithTimeout(java.util.concurrent.Callable, long, java.util.concurrent.TimeUnit, boolean)"><!-- --></A><H3> 232 callWithTimeout</H3> 233 <PRE> 234 <T> T <B>callWithTimeout</B>(<A HREF="http://java.sun.com/javase/6/docs/api/java/util/concurrent/Callable.html?is-external=true" title="class or interface in java.util.concurrent">Callable</A><T> callable, 235 long timeoutDuration, 236 <A HREF="http://java.sun.com/javase/6/docs/api/java/util/concurrent/TimeUnit.html?is-external=true" title="class or interface in java.util.concurrent">TimeUnit</A> timeoutUnit, 237 boolean interruptible) 238 throws <A HREF="http://java.sun.com/javase/6/docs/api/java/lang/Exception.html?is-external=true" title="class or interface in java.lang">Exception</A></PRE> 239 <DL> 240 <DD>Invokes a specified Callable, timing out after the specified time limit. 241 If the target method call finished before the limit is reached, the return 242 value or exception is propagated to the caller exactly as-is. If, on the 243 other hand, the time limit is reached, we attempt to abort the call to the 244 target, and throw an <A HREF="../../../../../com/google/common/util/concurrent/UncheckedTimeoutException.html" title="class in com.google.common.util.concurrent"><CODE>UncheckedTimeoutException</CODE></A> to the caller. 245 <p> 246 <b>Warning:</b> The future of this method is in doubt. It may be nuked, or 247 changed significantly. 248 <P> 249 <DD><DL> 250 <DT><B>Parameters:</B><DD><CODE>callable</CODE> - the Callable to execute<DD><CODE>timeoutDuration</CODE> - with timeoutUnit, the maximum length of time to wait<DD><CODE>timeoutUnit</CODE> - with timeoutDuration, the maximum length of time to wait<DD><CODE>interruptible</CODE> - whether to respond to thread interruption by aborting 251 the operation and throwing InterruptedException; if false, the 252 operation is allowed to complete or time out, and the current thread's 253 interrupt status is re-asserted. 254 <DT><B>Returns:</B><DD>the result returned by the Callable 255 <DT><B>Throws:</B> 256 <DD><CODE><A HREF="http://java.sun.com/javase/6/docs/api/java/lang/InterruptedException.html?is-external=true" title="class or interface in java.lang">InterruptedException</A></CODE> - if <code>interruptible</code> is true and our 257 thread is interrupted during execution 258 <DD><CODE><A HREF="../../../../../com/google/common/util/concurrent/UncheckedTimeoutException.html" title="class in com.google.common.util.concurrent">UncheckedTimeoutException</A></CODE> - if the time limit is reached 259 <DD><CODE><A HREF="http://java.sun.com/javase/6/docs/api/java/lang/Exception.html?is-external=true" title="class or interface in java.lang">Exception</A></CODE></DL> 260 </DD> 261 </DL> 262 <!-- ========= END OF CLASS DATA ========= --> 263 <HR> 264 265 266 <!-- ======= START OF BOTTOM NAVBAR ====== --> 267 <A NAME="navbar_bottom"><!-- --></A> 268 <A HREF="#skip-navbar_bottom" title="Skip navigation links"></A> 269 <TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0" SUMMARY=""> 270 <TR> 271 <TD COLSPAN=2 BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> 272 <A NAME="navbar_bottom_firstrow"><!-- --></A> 273 <TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3" SUMMARY=""> 274 <TR ALIGN="center" VALIGN="top"> 275 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A> </TD> 276 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-summary.html"><FONT CLASS="NavBarFont1"><B>Package</B></FONT></A> </TD> 277 <TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> <FONT CLASS="NavBarFont1Rev"><B>Class</B></FONT> </TD> 278 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="class-use/TimeLimiter.html"><FONT CLASS="NavBarFont1"><B>Use</B></FONT></A> </TD> 279 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A> </TD> 280 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A> </TD> 281 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A> </TD> 282 <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A> </TD> 283 </TR> 284 </TABLE> 285 </TD> 286 <TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM> 287 </EM> 288 </TD> 289 </TR> 290 291 <TR> 292 <TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2"> 293 <A HREF="../../../../../com/google/common/util/concurrent/SimpleTimeLimiter.html" title="class in com.google.common.util.concurrent"><B>PREV CLASS</B></A> 294 <A HREF="../../../../../com/google/common/util/concurrent/UncheckedTimeoutException.html" title="class in com.google.common.util.concurrent"><B>NEXT CLASS</B></A></FONT></TD> 295 <TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2"> 296 <A HREF="../../../../../index.html?com/google/common/util/concurrent/TimeLimiter.html" target="_top"><B>FRAMES</B></A> 297 <A HREF="TimeLimiter.html" target="_top"><B>NO FRAMES</B></A> 298 <SCRIPT type="text/javascript"> 299 <!-- 300 if(window==top) { 301 document.writeln('<A HREF="../../../../../allclasses-noframe.html"><B>All Classes</B></A>'); 302 } 303 //--> 304 </SCRIPT> 305 <NOSCRIPT> 306 <A HREF="../../../../../allclasses-noframe.html"><B>All Classes</B></A> 307 </NOSCRIPT> 308 309 310 </FONT></TD> 311 </TR> 312 <TR> 313 <TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2"> 314 SUMMARY: NESTED | FIELD | CONSTR | <A HREF="#method_summary">METHOD</A></FONT></TD> 315 <TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2"> 316 DETAIL: FIELD | CONSTR | <A HREF="#method_detail">METHOD</A></FONT></TD> 317 </TR> 318 </TABLE> 319 <A NAME="skip-navbar_bottom"></A> 320 <!-- ======== END OF BOTTOM NAVBAR ======= --> 321 322 <HR> 323 324 </BODY> 325 </HTML> 326
