Package org.astrogrid.samp

Class SampMap

  • All Implemented Interfaces:
    java.util.Map
    Direct Known Subclasses:
    ErrInfo, LockInfo, Message, Metadata, RegInfo, Response, Subscriptions
    public abstract class SampMap
extends java.util.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

        java.util.AbstractMap.SimpleEntry<K extends java.lang.Object,​V extends java.lang.Object>, java.util.AbstractMap.SimpleImmutableEntry<K extends java.lang.Object,​V extends java.lang.Object>

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

        java.util.Map.Entry<K extends java.lang.Object,​V extends java.lang.Object>

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.util.Map EMPTY  

    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      protected SampMap​(java.lang.String[] knownKeys)
      Constructor.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void check()
      Checks that this object is ready for use with the SAMP toolkit.
      void checkHasKeys​(java.lang.String[] keys)
      Checks that this map contains at least the given set of keys.
      java.util.Set entrySet()  
      java.util.List getList​(java.lang.String key)
      Returns the value for a given key in this map, cast to List.
      java.util.Map getMap​(java.lang.String key)
      returns the value for a given key in this map, cast to Map.
      java.lang.String getString​(java.lang.String key)
      Returns the value for a given key in this map, cast to String.
      java.net.URL getUrl​(java.lang.String key)
      Returns the value for a given key in this map as a URL.
      java.lang.Object put​(java.lang.Object key, java.lang.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 Detail

      • EMPTY

        public static final java.util.Map EMPTY

    • Constructor Detail

      • SampMap

        protected SampMap​(java.lang.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 java.lang.Object put​(java.lang.Object key,
                            java.lang.Object value)
        Specified by:
        put in interface java.util.Map
        Overrides:
        put in class java.util.AbstractMap

      • entrySet

        public java.util.Set entrySet()
        Specified by:
        entrySet in interface java.util.Map
        Specified by:
        entrySet in class java.util.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​(java.lang.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 java.lang.String getString​(java.lang.String key)
        Returns the value for a given key in this map, cast to String.
        Returns:
        string value for key

      • getMap

        public java.util.Map getMap​(java.lang.String key)
        returns the value for a given key in this map, cast to Map.
        Returns:
        map value for key

      • getList

        public java.util.List getList​(java.lang.String key)
        Returns the value for a given key in this map, cast to List.
        Returns:
        list value for key

      • getUrl

        public java.net.URL getUrl​(java.lang.String key)
        Returns the value for a given key in this map as a URL.
        Returns:
        URL value for key