com.artima.place
Interface Place

All Known Subinterfaces:

DynamicPlace, ModifiablePlace

public interface Place

A map of Links to services on the network. If a Place object also implements DynamicPlace, LinkItems may be added to or removed from the Place, and existing LinkItems may be altered, by third parties. If a Place object also implements ModifiablePlace, the client may add, remove, and alter the LinkItems contained in the Place.

Method Summary

boolean	containsAllKeys(java.util.Collection keys) Returns true if this Place contains a mapping for each key in the passed collection.
boolean	containsAllLinkItems(java.util.Collection values) Returns true if this Place maps one or more keys to each LinkItem value in the passed collection.
boolean	containsKey(int key) Returns true if this Place contains a mapping for the key created by wrapping the specified int in an Integer object.
boolean	containsKey(java.lang.Object key) Returns true if this Place contains a mapping for the specified key.
boolean	containsLinkItem(LinkItem value) Returns true if this Place maps one or more keys to the specified value.
LinkItem	get(int key) Convenience method that returns the LinkItem value to which this Place maps the Integer key with the int value passed in the key parameter.
LinkItem	get(java.lang.Object key) Returns the LinkItem value to which this Place maps the specified Object key.
boolean	isEmpty() Returns true if this map contains no key-value mappings.
DistributedIterator	keyIterator() Returns a DistributedIterator over the Object keys contained in this Place.
int	keySetSize() Returns the number of unique keys in this map.
DistributedIterator	linkItemIterator() Returns a DistributedIterator over the LinkItem values contained contained in this Place.
int	size() Returns the number of key-value mappings in this map.

Method Detail

get

public LinkItem get(java.lang.Object key)
             throws java.rmi.RemoteException

Returns the LinkItem value to which this Place maps the specified Object key. Returns null if the map contains no mapping for this key. A return value of null does definitely indicate that the map contains no mapping for the key, because Places never map a key to the value null. In other words, all keys contained in the Place are associated with a non-null LinkItem value.

Parameters:

key - key whose associated value is to be returned.

Returns:

the LinkItem value mapped to the specified key, or null if no LinkItem is mapped to that key

Throws:

NullPointerException - if passed key is null

java.rmi.RemoteException - if a network problem prevents this method from fulfilling its contractual obligations

get

public LinkItem get(int key)
             throws java.rmi.RemoteException

Convenience method that returns the LinkItem value to which this Place maps the Integer key with the int value passed in the key parameter. Returns null if the map contains no mapping for this key. A return value of null does definitely indicate that the map contains no mapping for the key, because Places never map a key to the value null. In other words, all keys contained in the Place are associated with a non-null LinkItem value.

Parameters:

the - int value of an Integer key whose LinkItem mapping is requested

Returns:

the LinkItem value mapped to the specified int wrapped in an Integer object, or null if no LinkItem is mapped to that Integer value

Throws:

java.rmi.RemoteException - if a network problem prevents this method from fulfilling its contractual obligations

containsKey

public boolean containsKey(java.lang.Object key)
                    throws java.rmi.RemoteException

Returns true if this Place contains a mapping for the specified key.

Parameters:

key - key whose presence in this Place is to be tested.

Returns:

true if this Place contains a mapping for the specified key

Throws:

NullPointerException - if passed key is null

java.rmi.RemoteException - if a network problem prevents this method from fulfilling its contractual obligations

containsKey

public boolean containsKey(int key)
                    throws java.rmi.RemoteException

Returns true if this Place contains a mapping for the key created by wrapping the specified int in an Integer object.

Parameters:

key - int key whose presence in in this Place in Integer form is to be tested.

Returns:

true if this Place contains a mapping for the specified int key wrapped in an Integer.

Throws:

NullPointerException - if passed key is null

java.rmi.RemoteException - if a network problem prevents this method from fulfilling its contractual obligations

containsAllKeys

public boolean containsAllKeys(java.util.Collection keys)
                        throws java.rmi.RemoteException

Returns true if this Place contains a mapping for each key in the passed collection.

Parameters:

keys - collection of keys to check for in this Place's set of keys.

Returns:

true if this Place contains a mapping for all of the keys in the specified collection

Throws:

NullPointerException - if passed keys is null

java.rmi.RemoteException - if a network problem prevents this method from fulfilling its contractual obligations

containsLinkItem

public boolean containsLinkItem(LinkItem value)
                         throws java.rmi.RemoteException

Returns true if this Place maps one or more keys to the specified value.

Parameters:

value - LinkItem check for in this Place.

Returns:

true if this Place maps one or more keys to the specified Place.

Throws:

NullPointerException - if passed value is null.

java.rmi.RemoteException - if a network problem prevents this method from fulfilling its contractual obligations

containsAllLinkItems

public boolean containsAllLinkItems(java.util.Collection values)
                             throws java.rmi.RemoteException

Returns true if this Place maps one or more keys to each LinkItem value in the passed collection.

Parameters:

values - collection of LinkItems to check for in this Place collection of values.

Returns:

true if this Place contains at least one key mapped to each of the LinkItem values in the specified collection

Throws:

NullPointerException - if passed values is null

java.rmi.RemoteException - if a network problem prevents this method from fulfilling its contractual obligations

isEmpty

public boolean isEmpty()
                throws java.rmi.RemoteException

Returns true if this map contains no key-value mappings.

Returns:

true if this set contains no elements.

Throws:

java.rmi.RemoteException - if a network problem prevents this method from fulfilling its contractual obligations

keyIterator

public DistributedIterator keyIterator()
                                throws java.rmi.RemoteException

Returns a DistributedIterator over the Object keys contained in this Place.

If changes occur to this Place after this method returns, which is possible if this object is a DynamicPlace or a ModifiablePlace, those changes will be reflected in the returned DistributedIterator. In other words, the returned DistributedIterator is backed by this Place.

If an iteration (via a DistributedIterator) is in progress when this Place is changed, the iteration will be able to continue to completion, but may give stale results or result in an NoSuchElementException being thrown as a result of the change to the underlying Place. Any keys removed from this Place may or may not be returned by subsequent invocations of next on the KeyIteration. (Of course, the removed keys may have already been returned by prior invocations of the next method). Any keys added to this Place may or may not be returned by subsequent invocations of next on the KeyIteration.

Therefore, the client of a DistributedIterator returned by a DynamicPlace or a ModifiablePlace should be careful to catch NoSuchElementException. For example, imagine a DistributedIterator has one more key to return before the iteration completes. When the client invokes hasNext, the result will be true. If the key is then removed, then a subsequent invocation of hasNext could legally return false. I.e., the key removed from the Place is also removed from the iteration. Since the client has already invoked hasNext and gotten a true back, however, the client may go ahead and simply invoke next. Even if the client has registered a PlaceChangeListener, that listener may not be notified of removal of the key before the client invokes next on the DistributedIterator. The result of invoking next would then be a thrown NoSuchElementException.

Returns:

a DistributedIterator over the keys in this Place

Throws:

java.rmi.RemoteException - if a network problem prevents this method from fulfilling its contractual obligations

keySetSize

public int keySetSize()
               throws java.rmi.RemoteException

Returns the number of unique keys in this map. Baring any changes to the underlying Place, the value returned by this method will be the number of keys returned by iterating with the DistributedIterator returned by the keyIterator method.

Returns:

the number of keys in this map.

Throws:

java.rmi.RemoteException - if a network problem prevents this method from fulfilling its contractual obligations

size

public int size()
         throws java.rmi.RemoteException

Returns the number of key-value mappings in this map.

Returns:

the number of LinkItem values in this map.

Throws:

java.rmi.RemoteException - if a network problem prevents this method from fulfilling its contractual obligations

linkItemIterator

public DistributedIterator linkItemIterator()
                                     throws java.rmi.RemoteException

Returns a DistributedIterator over the LinkItem values contained contained in this Place.

If changes occur to this Place after this method returns, which is possible if this object is a DynamicPlace or a ModifiablePlace, those changes will be reflected in the returned DistributedIterator. In other words, the returned DistributedIterator is backed by this Place.

If an iteration (via a DistributedIterator) over the returned LinkCollection is in progress when this Place is changed, the iteration will be able to continue to completion, but may give stale results or result in an NoSuchElementException being thrown as a result of the change to the underlying Place. Any values removed from this Place may or may not be returned by subsequent invocations of next on the DistributedIterator. (Of course, the removed values may have already been returned by prior invocations of the next method). Any values added to this Place may or may not be returned by subsequent invocations of next on the DistributedIterator.

Therefore, the client of a DistributedIterator returned by a DynamicPlace or a ModifiablePlace should be careful to catch NoSuchElementException. For example, imagine a DistributedIterator has one more value to return before the iteration completes. When the client invokes hasNext, the result will be true. If the value is then removed, then a subsequent invocation of hasNext could legally return false. I.e., the value removed from the Place is also removed from the iteration. Since the client has already invoked hasNext and gotten a true back, however, the client may go ahead and simply invoke next. Even if the client has registered a PlaceChangeListener, that listener may not be notified of removal of the value before the client invokes next on the DistributedIterator. The result of invoking next would then be a thrown NoSuchElementException.

Returns:

a DistributedIterator over the LinkItem values in this Place

Throws:

java.rmi.RemoteException - if a network problem prevents this method from fulfilling its contractual obligations