Package org.astrogrid.samp

# Class SampMap

java.lang.Object
java.util.AbstractMap
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:

- its entries are ordered in a convenient fashion
- it contains some general-purpose utility methods appropriate to SAMP maps
- particular subclasses contain specific constants and utility methods, e.g. well-known keys and accessor methods for them
- concrete subclasses provide a static `asClass` method to convert from a normal Map to the class in question

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 class java.util.AbstractMap

`AbstractMap.SimpleEntry<K,V>, AbstractMap.SimpleImmutableEntry<K,V>`

## Nested classes/interfaces inherited from interface java.util.Map

`Map.Entry<K,V>`

## Field Summary

Fields
Modifier and Type
Field
Description
`static final Map`
`EMPTY`

## Constructor Summary

Constructors
Modifier
Constructor
Description
`protected`
`SampMap(String[] knownKeys)`
Constructor.

## Method Summary

Modifier and Type
Method
Description
`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`

### Methods inherited from interface java.util.Map

`compute, computeIfAbsent, computeIfPresent, forEach, getOrDefault, merge, putIfAbsent, remove, replace, replace, replaceAll`

## Field Details

### EMPTY

public static final Map EMPTY

## Constructor Details

### 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 Details

### 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`