org.j4me.collections
Class CubbyHole

java.lang.Object
  extended by org.j4me.collections.CubbyHole

public class CubbyHole
extends java.lang.Object

Stores a single object for the producer/consumer pattern and takes care of thread synchronization. A first thread, the producer, can put an object into the cubby hole using set. If there already is an object in the cubby hole then it is discarded. Meanwhile a second thread, the consumer, can get the object using get. If no object is in the cubby hole the consumer will block until one is available.

CubbyHole is valuable for several situations including where a lot of information is produced and consumption is time consuming. For example an application that does expensive rendering based on location events could only render based on the very latest location.


Constructor Summary
CubbyHole()
           
 
Method Summary
 boolean empty()
          Test is the cubby hole is empty.
 java.lang.Object get()
          Called by the consumer to get an object stored in the cubby hole.
 java.lang.Object peek()
          Looks at the cubby hole without removing the object from it.
 java.lang.Object set(java.lang.Object data)
          Called by the producer to put data into the cubby hole.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

CubbyHole

public CubbyHole()
Method Detail

set

public java.lang.Object set(java.lang.Object data)
Called by the producer to put data into the cubby hole. If there was another object stored in the cubby hole it will be removed and returned.

This is a thread-safe method that returns immediately. If another thread, acting as the consumer, is blocking on get it will start running so long as data is not null.

Parameters:
data - is the information to store in the cubby hole. If null then there is no job and any calls to get will block until set is called again with a non- null object.
Returns:
The object in the cubby hole replaced by data or null if nothing was stored.

get

public java.lang.Object get()
                     throws java.lang.InterruptedException
Called by the consumer to get an object stored in the cubby hole. If nothing is stored this thread will block until set is called by a different thread.

Returns:
The object stored in the cubby hole by a call to set. This will never return null.
Throws:
java.lang.InterruptedException - if the program is exiting.

peek

public java.lang.Object peek()
Looks at the cubby hole without removing the object from it. This is a non-blocking method.

Returns:
The object in the cubby hole which will be null if nothing is being stored.

empty

public boolean empty()
Test is the cubby hole is empty. This is a non-blocking method.

Returns:
true if nothing is in the cubby hole or false if it has an object.