org.astrogrid.samp
Class SampMap

java.lang.Object
  extended by java.util.AbstractMap
      extended by org.astrogrid.samp.SampMap
All Implemented Interfaces:
Map
Direct Known Subclasses:
ErrInfo, LockInfo, Message, Metadata, RegInfo, Response, Subscriptions

public abstract class SampMap
extends AbstractMap

Abstract superclass for objects represented within the SAMP package as key-value maps. There are several of these, represented by subclasses of SampMap, for instance Message, Metadata etc. A SampMap is-a Map, but has some additional useful features:

In general any time a map-encoded object is required by a method in the toolkit, any Map can be used. When the toolkit provides a map-encoded object however (as return value or callback method parameter), an object of the more specific SampMap type is used. This allows maximum convenience for the application programmer, but means that you don't have to use these additional features if you don't want to, you can treat everything as a plain old Map.

Since:
14 Jul 2008
Author:
Mark Taylor

Nested Class Summary
 
Nested classes/interfaces inherited from interface java.util.Map
Map.Entry
 
Field Summary
static Map EMPTY
           
 
Constructor Summary
protected SampMap(String[] knownKeys)
          Constructor.
 
Method Summary
 void check()
          Checks that this object is ready for use with the SAMP toolkit.
 void checkHasKeys(String[] keys)
          Checks that this map contains at least the given set of keys.
 Set entrySet()
           
 List getList(String key)
          Returns the value for a given key in this map, cast to List.
 Map getMap(String key)
          returns the value for a given key in this map, cast to Map.
 String getString(String key)
          Returns the value for a given key in this map, cast to String.
 URL getUrl(String key)
          Returns the value for a given key in this map as a URL.
 Object put(Object key, Object value)
           
 
Methods inherited from class java.util.AbstractMap
clear, clone, containsKey, containsValue, equals, get, hashCode, isEmpty, keySet, putAll, remove, size, toString, values
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

EMPTY

public static final Map EMPTY
Constructor Detail

SampMap

protected SampMap(String[] knownKeys)
Constructor. The given array of well-known keys will appear first in the list of entries when this map is iterated over. Other entries will appear in alphabetical order.

Parameters:
knownKeys - array of well-known keys for this class
Method Detail

put

public Object put(Object key,
                  Object value)
Specified by:
put in interface Map
Overrides:
put in class AbstractMap

entrySet

public Set entrySet()
Specified by:
entrySet in interface Map
Specified by:
entrySet in class AbstractMap

check

public void check()
Checks that this object is ready for use with the SAMP toolkit. As well as calling SampUtils.checkMap(java.util.Map) (ensuring that all keys are Strings, and all values Strings, Lists or Maps), subclass-specific invariants may be checked. In the case that there's something wrong, an informative DataException will be thrown.

Throws:
DataException - if this object's current state is not suitable for SAMP use

checkHasKeys

public void checkHasKeys(String[] keys)
Checks that this map contains at least the given set of keys. If any is absent, an informative DataException will be thrown. Normally called by check().

Parameters:
keys - array of required keys for this map
Throws:
DataException - if this object does not contain entries for all elements of the array keys

getString

public String getString(String key)
Returns the value for a given key in this map, cast to String.

Returns:
string value for key

getMap

public Map getMap(String key)
returns the value for a given key in this map, cast to Map.

Returns:
map value for key

getList

public List getList(String key)
Returns the value for a given key in this map, cast to List.

Returns:
list value for key

getUrl

public URL getUrl(String key)
Returns the value for a given key in this map as a URL.

Returns:
URL value for key


Copyright © 2008-2011 AstroGrid. All Rights Reserved.