com.artima.place
Interface LinkMap

All Known Subinterfaces:

DynamicLinkMap, ModifiableLinkMap

public interface LinkMap

Represents a map of links to resources on the network. If a LinkMap object also implements ModifiableLinkMap, the client may add, remove, and alter the LinkItems contained in the LinkMap. If a LinkMap object also implements DynamicLinkMap, LinkItems may be added to or removed from the LinkMap, and existing LinkItems may be altered, by parties other than the client.

Method Summary

boolean	containsAllKeys(java.util.Collection keys) Returns true if this LinkMap contains a mapping for each key in the passed collection.
boolean	containsAllLinkItems(java.util.Collection values) Returns true if this LinkMap maps one or more keys to each LinkItem value in the passed collection.
boolean	containsKey(int key) Returns true if this LinkMap 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 LinkMap contains a mapping for the specified key.
boolean	containsLinkItem(LinkItem value) Returns true if this LinkMap maps one or more keys to the specified value.
LinkItem	get(int key) Convenience method that returns the LinkItem value to which this LinkMap 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 LinkMap maps the specified Object key.
boolean	isEmpty() Returns true if this map contains no key-value mappings.
KeyIterator	keyIterator() Returns a KeyIterator over the Object keys contained in this LinkMap.
int	keySetSize() Returns the number of unique keys in this map.
LinkItemIterator	linkItemIterator() Returns a LinkItemIterator over the LinkItem values contained contained in this LinkMap.
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 LinkMap 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 LinkMaps never map a key to the value null. In other words, all keys contained in the LinkMap 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 LinkMap 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 LinkMaps never map a key to the value null. In other words, all keys contained in the LinkMap 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 LinkMap contains a mapping for the specified key.

Parameters:

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

Returns:

true if this LinkMap 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 LinkMap 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 LinkMap in Integer form is to be tested.

Returns:

true if this LinkMap 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 LinkMap contains a mapping for each key in the passed collection.

Parameters:

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

Returns:

true if this LinkMap 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 LinkMap maps one or more keys to the specified value.

Parameters:

value - LinkItem check for in this LinkMap.

Returns:

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

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 LinkMap maps one or more keys to each LinkItem value in the passed collection.

Parameters:

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

Returns:

true if this LinkMap 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 KeyIterator keyIterator()
                        throws java.rmi.RemoteException

Returns a KeyIterator over the Object keys contained in this LinkMap.

If changes occur to this LinkMap after this method returns, which is possible if this object is a DynamicLinkMap or a ModifiableLinkMap, those changes will be reflected in the returned KeyIterator. In other words, the returned KeyIterator is backed by this LinkMap.

If an iteration (via a KeyIterator) is in progress when this LinkMap 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 LinkMap. Any keys removed from this LinkMap 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 LinkMap may or may not be returned by subsequent invocations of next on the KeyIteration.

Therefore, the client of a KeyIterator returned by a DynamicLinkMap or a ModifiableLinkMap should be careful to catch NoSuchElementException. For example, imagine a KeyIterator 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 LinkMap 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 LinkMapListener, that listener may not be notified of removal of the key before the client invokes next on the KeyIterator. The result of invoking next would then be a thrown NoSuchElementException.

Returns:

a KeyIterator over the keys in this LinkMap

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 LinkMap, the value returned by this method will be the number of keys returned by iterating with the KeyIterator 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 LinkItemIterator linkItemIterator()
                                  throws java.rmi.RemoteException

Returns a LinkItemIterator over the LinkItem values contained contained in this LinkMap.

If changes occur to this LinkMap after this method returns, which is possible if this object is a DynamicLinkMap or a ModifiableLinkMap, those changes will be reflected in the returned LinkItemIterator. In other words, the returned LinkItemIterator is backed by this LinkMap.

If an iteration (via a LinkItemIterator) over the returned LinkCollection is in progress when this LinkMap 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 LinkMap. Any values removed from this LinkMap may or may not be returned by subsequent invocations of next on the LinkItemIterator. (Of course, the removed values may have already been returned by prior invocations of the next method). Any values added to this LinkMap may or may not be returned by subsequent invocations of next on the LinkItemIterator.

Therefore, the client of a LinkItemIterator returned by a DynamicLinkMap or a ModifiableLinkMap should be careful to catch NoSuchElementException. For example, imagine a LinkItemIterator 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 LinkMap 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 LinkMapListener, that listener may not be notified of removal of the value before the client invokes next on the LinkItemIterator. The result of invoking next would then be a thrown NoSuchElementException.

Returns:

a LinkItemIterator over the LinkItem values in this LinkMap

Throws:

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