| 1 |
package org.astrogrid.samp; |
| 2 |
|
| 3 |
import java.net.MalformedURLException; |
| 4 |
import java.net.URL; |
| 5 |
import java.util.AbstractMap; |
| 6 |
import java.util.Arrays; |
| 7 |
import java.util.Collections; |
| 8 |
import java.util.Comparator; |
| 9 |
import java.util.HashMap; |
| 10 |
import java.util.List; |
| 11 |
import java.util.Map; |
| 12 |
import java.util.Set; |
| 13 |
import java.util.TreeMap; |
| 14 |
|
| 15 |
/** |
| 16 |
* Abstract superclass for objects represented within the SAMP package as |
| 17 |
* key-value maps. There are several of these, represented by subclasses |
| 18 |
* of <code>SampMap</code>, for instance {@link Message}, {@link Metadata} etc. |
| 19 |
* A <code>SampMap</code> is-a {@link java.util.Map}, but has some |
| 20 |
* additional useful features: |
| 21 |
* <ul> |
| 22 |
* <li>its entries are ordered in a convenient fashion |
| 23 |
* <li>it contains some general-purpose utility methods appropriate to SAMP maps |
| 24 |
* <li>particular subclasses contain specific constants and utility methods, |
| 25 |
* e.g. well-known keys and accessor methods for them |
| 26 |
* <li>concrete subclasses provide a static <code>as<em>Class</em></code> |
| 27 |
* method to convert from a normal Map to the class in question |
| 28 |
* </ul> |
| 29 |
* |
| 30 |
* <p>In general |
| 31 |
* any time a map-encoded object is required by a method in the toolkit, |
| 32 |
* any <code>Map</code> can be used. When the toolkit provides a map-encoded |
| 33 |
* object however (as return value or callback method parameter), an object |
| 34 |
* of the more specific <code>SampMap</code> type is used. |
| 35 |
* This allows maximum convenience for the application programmer, but |
| 36 |
* means that you don't have to use these additional features if you |
| 37 |
* don't want to, you can treat everything as a plain old <code>Map</code>. |
| 38 |
* |
| 39 |
* @author Mark Taylor |
| 40 |
* @since 14 Jul 2008 |
| 41 |
*/ |
| 42 |
public abstract class SampMap extends AbstractMap { |
| 43 |
|
| 44 |
private final Map baseMap_; |
| 45 |
public static final Map EMPTY = |
| 46 |
Collections.unmodifiableMap( new HashMap() ); |
| 47 |
|
| 48 |
/** |
| 49 |
* Constructor. |
| 50 |
* The given array of well-known keys will appear first in the list of |
| 51 |
* entries when this map is iterated over. Other entries will appear in |
| 52 |
* alphabetical order. |
| 53 |
* |
| 54 |
* @param knownKeys array of well-known keys for this class |
| 55 |
*/ |
| 56 |
protected SampMap( String[] knownKeys ) { |
| 57 |
super(); |
| 58 |
final List knownKeyList = Arrays.asList( (String[]) knownKeys.clone() ); |
| 59 |
baseMap_ = new TreeMap( new Comparator() { |
| 60 |
public int compare( Object o1, Object o2 ) { |
| 61 |
String s1 = o1.toString(); |
| 62 |
String s2 = o2.toString(); |
| 63 |
int k1 = knownKeyList.indexOf( s1 ); |
| 64 |
int k2 = knownKeyList.indexOf( s2 ); |
| 65 |
if ( k1 >= 0 ) { |
| 66 |
if ( k2 >= 0 ) { |
| 67 |
return k1 - k2; |
| 68 |
} |
| 69 |
else { |
| 70 |
return -1; |
| 71 |
} |
| 72 |
} |
| 73 |
else if ( k2 >= 0 ) { |
| 74 |
assert k1 < 0; |
| 75 |
return +1; |
| 76 |
} |
| 77 |
boolean f1 = s1.startsWith( "samp." ); |
| 78 |
boolean f2 = s2.startsWith( "samp." ); |
| 79 |
if ( f1 && ! f2 ) { |
| 80 |
return -1; |
| 81 |
} |
| 82 |
else if ( ! f1 && f2 ) { |
| 83 |
return +1; |
| 84 |
} |
| 85 |
boolean g1 = s1.startsWith( "x-samp." ); |
| 86 |
boolean g2 = s2.startsWith( "x-samp." ); |
| 87 |
if ( g1 && ! g2 ) { |
| 88 |
return -1; |
| 89 |
} |
| 90 |
else if ( ! g1 && g2 ) { |
| 91 |
return +1; |
| 92 |
} |
| 93 |
return s1.compareTo( s2 ); |
| 94 |
} |
| 95 |
} ); |
| 96 |
} |
| 97 |
|
| 98 |
public Object put( Object key, Object value ) { |
| 99 |
return baseMap_.put( key, value ); |
| 100 |
} |
| 101 |
|
| 102 |
public Set entrySet() { |
| 103 |
return baseMap_.entrySet(); |
| 104 |
} |
| 105 |
|
| 106 |
/** |
| 107 |
* Checks that this object is ready for use with the SAMP toolkit. |
| 108 |
* As well as calling {@link SampUtils#checkMap} (ensuring that all keys |
| 109 |
* are Strings, and all values Strings, Lists or Maps), subclass-specific |
| 110 |
* invariants may be checked. In the case that there's something wrong, |
| 111 |
* an informative <code>DataException</code> will be thrown. |
| 112 |
* |
| 113 |
* @throws DataException if this object's current state |
| 114 |
* is not suitable for SAMP use |
| 115 |
*/ |
| 116 |
public void check() { |
| 117 |
SampUtils.checkMap( this ); |
| 118 |
} |
| 119 |
|
| 120 |
/** |
| 121 |
* Checks that this map contains at least the given set of keys. |
| 122 |
* If any is absent, an informative <code>DataException</code> will be |
| 123 |
* thrown. Normally called by {@link #check}. |
| 124 |
* |
| 125 |
* @param keys array of required keys for this map |
| 126 |
* @throws DataException if this object does not contain entries |
| 127 |
* for all elements of the array <code>keys</code> |
| 128 |
*/ |
| 129 |
public void checkHasKeys( String[] keys ) { |
| 130 |
for ( int i = 0; i < keys.length; i++ ) { |
| 131 |
String key = keys[ i ]; |
| 132 |
if ( ! containsKey( key ) ) { |
| 133 |
throw new DataException( "Required key " + key |
| 134 |
+ " not present" ); |
| 135 |
} |
| 136 |
} |
| 137 |
} |
| 138 |
|
| 139 |
/** |
| 140 |
* Returns the value for a given key in this map, cast to String. |
| 141 |
* |
| 142 |
* @return string value for <code>key</code> |
| 143 |
*/ |
| 144 |
public String getString( String key ) { |
| 145 |
return (String) get( key ); |
| 146 |
} |
| 147 |
|
| 148 |
/** |
| 149 |
* returns the value for a given key in this map, cast to Map. |
| 150 |
* |
| 151 |
* @return map value for <code>key</code> |
| 152 |
*/ |
| 153 |
public Map getMap( String key ) { |
| 154 |
return (Map) get( key ); |
| 155 |
} |
| 156 |
|
| 157 |
/** |
| 158 |
* Returns the value for a given key in this map, cast to List. |
| 159 |
* |
| 160 |
* @return list value for <code>key</code> |
| 161 |
*/ |
| 162 |
public List getList( String key ) { |
| 163 |
return (List) get( key ); |
| 164 |
} |
| 165 |
|
| 166 |
/** |
| 167 |
* Returns the value for a given key in this map as a URL. |
| 168 |
* |
| 169 |
* @return URL value for <code>key</code> |
| 170 |
*/ |
| 171 |
public URL getUrl( String key ) { |
| 172 |
String loc = getString( key ); |
| 173 |
if ( loc == null ) { |
| 174 |
return null; |
| 175 |
} |
| 176 |
else { |
| 177 |
try { |
| 178 |
return new URL( loc ); |
| 179 |
} |
| 180 |
catch ( MalformedURLException e ) { |
| 181 |
return null; |
| 182 |
} |
| 183 |
} |
| 184 |
} |
| 185 |
} |