package org.astrogrid.samp; import java.util.HashMap; import java.util.Map; /** * Represents an encoded SAMP Message. * * @author Mark Taylor * @since 14 Jul 2008 */ public class Message extends SampMap { /** Key for message MType. */ public static final String MTYPE_KEY = "samp.mtype"; /** Key for map of parameters used by this message. */ public static final String PARAMS_KEY = "samp.params"; private static final String[] KNOWN_KEYS = new String[] { MTYPE_KEY, PARAMS_KEY, }; /** * Constructs an empty message. */ public Message() { super( KNOWN_KEYS ); } /** * Constructs a message based on an existing map. * * @param map map containing initial data for this object */ public Message( Map map ) { this(); putAll( map ); } /** * Constructs a message with a given MType and params map. * * @param mtype value for {@link #MTYPE_KEY} key * @param params value for {@link #PARAMS_KEY} key */ public Message( String mtype, Map params ) { this(); put( MTYPE_KEY, mtype ); put( PARAMS_KEY, params == null ? new HashMap() : params ); } /** * Constructs a message with a given MType. * The parameters map will be mutable. * * @param mtype value for {@link #MTYPE_KEY} key */ public Message( String mtype ) { this( mtype, null ); } /** * Returns this message's MType. * * @return value for {@link #MTYPE_KEY} */ public String getMType() { return getString( MTYPE_KEY ); } /** * Sets this message's params map. * * @param params value for {@link #PARAMS_KEY} */ public void setParams( Map params ) { put( PARAMS_KEY, params ); } /** * Returns this message's params map. * * @return value for {@link #PARAMS_KEY} */ public Map getParams() { return getMap( PARAMS_KEY ); } /** * Sets the value for a single entry in this message's * samp.params map. * * @param name param name * @param value param value */ public Message addParam( String name, Object value ) { if ( ! containsKey( PARAMS_KEY ) ) { put( PARAMS_KEY, new HashMap() ); } getParams().put( name, value ); return this; } /** * Returns the value of a single entry in this message's * samp.params map. Null is returned if the parameter * does not appear. * * @param name param name * @return param value, or null */ public Object getParam( String name ) { Map params = getParams(); return params == null ? null : params.get( name ); } /** * Returns the value of a single entry in this message's * samp.params map, throwing an exception * if it is not present. * * @param name param name * @return param value * @throws DataException if no parameter name is present */ public Object getRequiredParam( String name ) { Object param = getParam( name ); if ( param != null ) { return param; } else { throw new DataException( "Required parameter \"" + name + "\" is missing" ); } } public void check() { super.check(); checkHasKeys( new String[] { MTYPE_KEY } ); } /** * Returns a given map as a Message object. * * @param map map * @return message */ public static Message asMessage( Map map ) { return ( map instanceof Message || map == null ) ? (Message) map : new Message( map ); } }