[[space_interface]]
== Space interface

In addition to those three basic operations, +org.jpos.space.Space+ adds a few 
handy methods: 

* +void out (K key, V value, long timeout)+
  Place an object into the space using an expiration timeout.  
  The entry is automatically removed upon expiration.

* +V rd (K key, long timeout)+
   Wait a maximum of +timeout+ milliseconds for a given entry; otherwise, return null.

* +V in (K key, long timeout)+
   Wait a maximum of +timeout+ milliseconds for a given entry, and takes it; otherwise, return null.

* +V rdp (K key)+
  Read an entry if it exists ('p' for 'probe').

* +V inp (K key)+
  Take an entry if it exists (again, 'p' for 'probe').

* +void nrd (K key)+
  Block while key is present in the space. The operation name comes after 'not read'.

* +V nrd (K key, long timeout)+
  Block up to timeout milliseconds while key is present in the space.
  If timeout is reached and key is still present, returns its value (as in 'rdp').

* +void push (K key, V value)+
  Same as +out+ but the entry is placed at the head of the queue (like a Stack's push operation). 

* +void push (K key, V value, long timeout)+
  Same as the previous +push+ operation with a timeout in millis.

* +public void put (K key, V value)+
  Like a +Map.put+ operation, a +Space.put+ wipes all entries that may exist under a given
  key and puts just this one.

* +public void put (K key, V value, long timeout)+
  Same as previous one, but with a timeout.

See http://jpos.org/doc/javadoc/org/jpos/space/Space.html[Javadoc] for full details and 
additional helper methods (such as the handy +existAny(K[] keys+).

[NOTE]
======
While +org.jpos.space.Space+ supports `generics', current implementations
does not guarantee object type. 
Use with care as an unexpected +ClassCastException+ can occurr.
======

The Space interface is small enough to show here:

[source,java]
-------------
package org.jpos.space;

public interface Space<K,V> {
    public void out (K key, V value);
    public void out (K key, V value, long timeout);
    public V in  (Object key);
    public V rd  (Object key);
    public V in  (Object key, long timeout);
    public V rd  (Object key, long timeout);
    public V inp (Object key);
    public V rdp (Object key);
    public void push (K key, V value);
    public void push (K key, V value, long timeout);
    public boolean existAny (K[] keys);
    public boolean existAny (K[] keys, long timeout);
    public void put (K key, V value);
    public void put (K key, V value, long timeout);
}
-------------

