Debian Codegraph @

src/java/org/astrogrid/samp/SampMap.java

raw
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 }