View Javadoc
1   /*
2     File: Puttable.java
3   
4     Originally written by Doug Lea and released into the public domain.
5     This may be used for any purposes whatsoever without acknowledgment.
6     Thanks for the assistance and support of Sun Microsystems Labs,
7     and everyone contributing, testing, and using this code.
8   
9     History:
10    Date       Who                What
11    11Jun1998  dl               Create public version
12  */
13  
14  package org.dbunit.util.concurrent;
15  
16  /** 
17   * This interface exists to enable stricter type checking
18   * for channels. A method argument or instance variable
19   * in a producer object can be declared as only a Puttable
20   * rather than a Channel, in which case a Java compiler
21   * will disallow take operations.
22   * <p>
23   * Full method descriptions appear in the Channel interface.
24   * <p>[<a href="http://gee.cs.oswego.edu/dl/classes/EDU/oswego/cs/dl/util/concurrent/intro.html"> Introduction to this package. </a>]
25   * 
26   * @author Doug Lea
27   * @author Last changed by: $Author$
28   * @version $Revision$ $Date$
29   * @since ? (pre 2.1)
30   * 
31   * @see Channel
32   * @see Takable
33   */
34  
35  public interface Puttable {
36  
37  
38    /** 
39     * Place item in the channel, possibly waiting indefinitely until
40     * it can be accepted. Channels implementing the BoundedChannel
41     * subinterface are generally guaranteed to block on puts upon
42     * reaching capacity, but other implementations may or may not block.
43     * @param item the element to be inserted. Should be non-null.
44     * @exception InterruptedException if the current thread has
45     * been interrupted at a point at which interruption
46     * is detected, in which case the element is guaranteed not
47     * to be inserted. Otherwise, on normal return, the element is guaranteed
48     * to have been inserted.
49    **/
50    public void put(Object item) throws InterruptedException;
51  
52  
53    /** 
54     * Place item in channel only if it can be accepted within
55     * msecs milliseconds. The time bound is interpreted in
56     * a coarse-grained, best-effort fashion. 
57     * @param item the element to be inserted. Should be non-null.
58     * @param msecs the number of milliseconds to wait. If less than
59     * or equal to zero, the method does not perform any timed waits,
60     * but might still require
61     * access to a synchronization lock, which can impose unbounded
62     * delay if there is a lot of contention for the channel.
63     * @return true if accepted, else false
64     * @exception InterruptedException if the current thread has
65     * been interrupted at a point at which interruption
66     * is detected, in which case the element is guaranteed not
67     * to be inserted (i.e., is equivalent to a false return).
68    **/
69    public boolean offer(Object item, long msecs) throws InterruptedException;
70  }