Debian Codegraph @

src/java/org/astrogrid/samp/Message.java

raw
1 package org.astrogrid.samp;
2
3 import java.util.HashMap;
4 import java.util.Map;
5
6 /**
7 * Represents an encoded SAMP Message.
8 *
9 * @author Mark Taylor
10 * @since 14 Jul 2008
11 */
12 public class Message extends SampMap {
13
14 /** Key for message MType. */
15 public static final String MTYPE_KEY = "samp.mtype";
16
17 /** Key for map of parameters used by this message. */
18 public static final String PARAMS_KEY = "samp.params";
19
20 private static final String[] KNOWN_KEYS = new String[] {
21 MTYPE_KEY,
22 PARAMS_KEY,
23 };
24
25 /**
26 * Constructs an empty message.
27 */
28 public Message() {
29 super( KNOWN_KEYS );
30 }
31
32 /**
33 * Constructs a message based on an existing map.
34 *
35 * @param map map containing initial data for this object
36 */
37 public Message( Map map ) {
38 this();
39 putAll( map );
40 }
41
42 /**
43 * Constructs a message with a given MType and params map.
44 *
45 * @param mtype value for {@link #MTYPE_KEY} key
46 * @param params value for {@link #PARAMS_KEY} key
47 */
48 public Message( String mtype, Map params ) {
49 this();
50 put( MTYPE_KEY, mtype );
51 put( PARAMS_KEY, params == null ? new HashMap() : params );
52 }
53
54 /**
55 * Constructs a message with a given MType.
56 * The parameters map will be mutable.
57 *
58 * @param mtype value for {@link #MTYPE_KEY} key
59 */
60 public Message( String mtype ) {
61 this( mtype, null );
62 }
63
64 /**
65 * Returns this message's MType.
66 *
67 * @return value for {@link #MTYPE_KEY}
68 */
69 public String getMType() {
70 return getString( MTYPE_KEY );
71 }
72
73 /**
74 * Sets this message's params map.
75 *
76 * @param params value for {@link #PARAMS_KEY}
77 */
78 public void setParams( Map params ) {
79 put( PARAMS_KEY, params );
80 }
81
82 /**
83 * Returns this message's params map.
84 *
85 * @return value for {@link #PARAMS_KEY}
86 */
87 public Map getParams() {
88 return getMap( PARAMS_KEY );
89 }
90
91 /**
92 * Sets the value for a single entry in this message's
93 * <code>samp.params</code> map.
94 *
95 * @param name param name
96 * @param value param value
97 */
98 public Message addParam( String name, Object value ) {
99 if ( ! containsKey( PARAMS_KEY ) ) {
100 put( PARAMS_KEY, new HashMap() );
101 }
102 getParams().put( name, value );
103 return this;
104 }
105
106 /**
107 * Returns the value of a single entry in this message's
108 * <code>samp.params</code> map. Null is returned if the parameter
109 * does not appear.
110 *
111 * @param name param name
112 * @return param value, or null
113 */
114 public Object getParam( String name ) {
115 Map params = getParams();
116 return params == null ? null
117 : params.get( name );
118 }
119
120 /**
121 * Returns the value of a single entry in this message's
122 * <code>samp.params</code> map, throwing an exception
123 * if it is not present.
124 *
125 * @param name param name
126 * @return param value
127 * @throws DataException if no parameter <code>name</code> is present
128 */
129 public Object getRequiredParam( String name ) {
130 Object param = getParam( name );
131 if ( param != null ) {
132 return param;
133 }
134 else {
135 throw new DataException( "Required parameter \"" + name
136 + "\" is missing" );
137 }
138 }
139
140 public void check() {
141 super.check();
142 checkHasKeys( new String[] { MTYPE_KEY } );
143 }
144
145 /**
146 * Returns a given map as a Message object.
147 *
148 * @param map map
149 * @return message
150 */
151 public static Message asMessage( Map map ) {
152 return ( map instanceof Message || map == null )
153 ? (Message) map
154 : new Message( map );
155 }
156 }