com.thetransactioncompany.jsonrpc2.util
Class NamedParamsRetriever

java.lang.Object
  com.thetransactioncompany.jsonrpc2.util.ParamsRetriever
      com.thetransactioncompany.jsonrpc2.util.NamedParamsRetriever

public class NamedParamsRetriever
extends ParamsRetriever

Utility class for retrieving JSON-RPC 2.0 named parameters (key-value pairs packed into a JSON Object). Provides proper handling of expected JSON types, mandatory or optional parameters, and default values.

Example: suppose you have a method with 3 named parameters "name", "age" and "sex", where the last is optional and defaults to "female":

 // Parse received request string
 JSONRPC2Request request = null;

 try {
         request = JSONRPC2Request.parse(jsonString);
 } catch (JSONRPC2ParseException e) {
         // handle exception...
 }

 // Create a new retriever for named parameters
 Map params = (Map)request.getParams();
 NamedParamsRetriever r = new NamedParamsRetriever(params);

 try {
         // Extract "name" string parameter
         String name = r.getString("name");

         // Extract "age" integer parameter
         int age = r.getInt("age");

         // Extract optional "sex" string parameter which defaults to "female"
         String sex = r.getOptString("sex", "female");

 } catch (JSONRPC2Error e) {
         // A JSONRPC2Error.INVALID_PARAMS will be thrown to indicate
         // an unexptected parameter type or a missing mandatory parameter.
         // You can use it straight away to create the appropriate
         // JSON-RPC 2.0 error response.
         JSONRPC2Response response = new JSONRPC2Response(e, null);
 }
 
 

The mapping between JSON and Java entities (as defined by the underlying JSON.simple library):

    true|false  <--->  java.lang.Boolean
    number      <--->  java.lang.Number
    string      <--->  java.lang.String
    array       <--->  java.util.List
    object      <--->  java.util.Map
    null        <--->  null
 

Version:

1.9.1 (2009-03-15)

Author:

Vladimir Dzhuvinov

Constructor Summary

NamedParamsRetriever(java.util.Map params)
Creates a new named parameters retriever from the specified key-value map.

Method Summary

void	ensureParameter(java.lang.String name) Throws a JSONRPC2Error.INVALID_PARAMS exception if there is no parameter by the specified name.
void	ensureParameter(java.lang.String name, java.lang.Object typeRef) Throws a JSONRPC2Error.INVALID_PARAMS exception if there is no parameter by the specified name, or its type doesn't match the specified.
void	ensureParameters(java.lang.String[] mandatoryNames) Throws a JSONRPC2Error.INVALID_PARAMS if the specified names aren't contained in the parameters, or names outside the specified are contained.
void	ensureParameters(java.lang.String[] mandatoryNames, java.lang.String[] optionalNames) Throws a JSONRPC2Error.INVALID_PARAMS if the specified mandatory names aren't contained in the parameters, or names outside the specified mandatory and optional are contained.
java.lang.Object	get(java.lang.String name) Retrieves the specified parameter which can be of any type.
java.lang.Object	get(java.lang.String name, java.lang.Object refType) Retrieves the specified parameter which must match the provided reference type.
boolean	getBoolean(java.lang.String name) Retrieves the specified boolean (maps from JSON true/false) parameter.
boolean[]	getBooleanArray(java.lang.String name) Retrieves the specified boolean array (maps from JSON array of true/false values) parameter.
double	getDouble(java.lang.String name) Retrieves the specified double parameter.
double[]	getDoubleArray(java.lang.String name) Retrieves the specified double array (maps from JSON array of fraction numbers) parameter.
java.lang.String	getEnumString(java.lang.String name, java.lang.String[] enumStrings) Retrieves the specified enumerated string parameter.
java.lang.String	getEnumString(java.lang.String name, java.lang.String[] enumStrings, boolean ignoreCase) Retrieves the specified enumerated string parameter, allowing for a case insenstive match.
float	getFloat(java.lang.String name) Retrieves the specified float parameter.
float[]	getFloatArray(java.lang.String name) Retrieves the specified float array (maps from JSON array of fraction numbers) parameter.
int	getInt(java.lang.String name) Retrieves the specified integer parameter.
int[]	getIntArray(java.lang.String name) Retrieves the specified integer array (maps from JSON array of integer numbers) parameter.
java.util.List	getList(java.lang.String name) Retrieves the specified list (maps from JSON array) parameter.
long	getLong(java.lang.String name) Retrieves the specified long parameter.
long[]	getLongArray(java.lang.String name) Retrieves the specified long array (maps from JSON array of integer numbers) parameter.
java.util.Map	getMap(java.lang.String name) Retrieves the specified map (maps from JSON object) parameter.
java.lang.String[]	getNames() Returns the names of all parameters.
java.lang.Object	getOpt(java.lang.String name, java.lang.Object defaultValue) Retrieves the specified optional parameter which must have the same type as the default value.
boolean	getOptBoolean(java.lang.String name, boolean defaultValue) Retrieves the specified optional boolean (maps from JSON true/false) parameter.
boolean[]	getOptBooleanArray(java.lang.String name, boolean[] defaultValue) Retrieves the specified optional boolean array (maps from JSON array of true/false values) parameter.
double	getOptDouble(java.lang.String name, double defaultValue) Retrieves the specified optional double parameter.
double[]	getOptDoubleArray(java.lang.String name, double[] defaultValue) Retrieves the specified optional double array (maps from JSON array of fraction numbers) parameter.
java.lang.String	getOptEnumString(java.lang.String name, java.lang.String[] enumStrings, java.lang.String defaultValue) Retrieves the specified optional enumerated string parameter.
java.lang.String	getOptEnumString(java.lang.String name, java.lang.String[] enumStrings, java.lang.String defaultValue, boolean ignoreCase) Retrieves the specified optional enumerated string parameter, allowing for a case insenstive match.
float	getOptFloat(java.lang.String name, float defaultValue) Retrieves the specified optional float parameter.
float[]	getOptFloatArray(java.lang.String name, float[] defaultValue) Retrieves the specified optional float array (maps from JSON array of fraction numbers) parameter.
int	getOptInt(java.lang.String name, int defaultValue) Retrieves the specified optional integer parameter.
int[]	getOptIntArray(java.lang.String name, int[] defaultValue) Retrieves the specified optional integer array (maps from JSON array of integer numbers) parameter.
java.util.List	getOptList(java.lang.String name, java.util.List defaultValue) Retrieves the specified optional list (maps from JSON array) parameter.
long	getOptLong(java.lang.String name, long defaultValue) Retrieves the specified optional long parameter.
long[]	getOptLongArray(java.lang.String name, long[] defaultValue) Retrieves the specified optional long array (maps from JSON array of integer numbers) parameter.
java.util.Map	getOptMap(java.lang.String name, java.util.Map defaultValue) Retrieves the specified optional map (maps from JSON object) parameter.
java.lang.String	getOptString(java.lang.String name, java.lang.String defaultValue) Retrieves the specified optional string parameter.
java.lang.String[]	getOptStringArray(java.lang.String name, java.lang.String[] defaultValue) Retrieves the specified optional string array (maps from JSON array of strings) parameter.
java.lang.String	getString(java.lang.String name) Retrieves the specified string parameter.
java.lang.String[]	getStringArray(java.lang.String name) Retrieves the specified string array (maps from JSON array of strings) parameter.
boolean	hasParameter(java.lang.String name) Returns true if a parameter by the specified name exists, otherwise false.
int	size() Returns the number of named parameters.

Methods inherited from class com.thetransactioncompany.jsonrpc2.util.ParamsRetriever

ensureEnumString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

NamedParamsRetriever

public NamedParamsRetriever(java.util.Map params)

Creates a new named parameters retriever from the specified key-value map.

Parameters:

params - The named parameters map.

Method Detail

size

public int size()

Returns the number of named parameters.

Specified by:

size in class ParamsRetriever

Returns:

The number of named parameters.

getNames

public java.lang.String[] getNames()

Returns the names of all parameters.

Returns:

The parameter names.

ensureParameters

public void ensureParameters(java.lang.String[] mandatoryNames)
                      throws JSONRPC2Error

Throws a JSONRPC2Error.INVALID_PARAMS if the specified names aren't contained in the parameters, or names outside the specified are contained.

You may use this method to a fire a proper JSON-RPC 2.0 error on a missing or unexpected mandatory parameter name.

Parameters:

mandatoryNames - The expected parameter names.

Throws:

JSONRPC2Error - With proper code and message if the specified names aren't contained or names outside the specified are contained.

ensureParameters

public void ensureParameters(java.lang.String[] mandatoryNames,
                             java.lang.String[] optionalNames)
                      throws JSONRPC2Error

Throws a JSONRPC2Error.INVALID_PARAMS if the specified mandatory names aren't contained in the parameters, or names outside the specified mandatory and optional are contained.

You may use this method to a fire a proper JSON-RPC 2.0 error on a missing or unexpected mandatory parameter name.

Parameters:

mandatoryNames - The expected mandatory parameter names.

optionalNames - The expected optional parameter names, null if none.

Throws:

JSONRPC2Error - With proper code and message if the specified mandatory names aren't contained or names outside the specified mandatory and optional are contained.

ensureParameter

public void ensureParameter(java.lang.String name)
                     throws JSONRPC2Error

Throws a JSONRPC2Error.INVALID_PARAMS exception if there is no parameter by the specified name.

You may use this method to fire the proper JSON-RPC 2.0 error on a missing mandatory parameter.

Parameters:

name - The parameter name.

Throws:

JSONRPC2Error - With proper code and message if the parameter is missing.

ensureParameter

public void ensureParameter(java.lang.String name,
                            java.lang.Object typeRef)
                     throws JSONRPC2Error

Throws a JSONRPC2Error.INVALID_PARAMS exception if there is no parameter by the specified name, or its type doesn't match the specified. A null type reference matches any object type.

You may use this method to fire the proper JSON-RPC 2.0 error on a missing mandatory parameter.

Parameters:

name - The parameter name.

typeRef - The expected parameter type, specified as an instance of the same class. Set to null to match any type.

Throws:

JSONRPC2Error - With proper code and message if the parameter is missing or its type doesn't match the specified.

hasParameter

public boolean hasParameter(java.lang.String name)

Returns true if a parameter by the specified name exists, otherwise false.

Parameters:

name - The parameter name.

Returns:

true if the parameter exists, otherwise false.

getString

public java.lang.String getString(java.lang.String name)
                           throws JSONRPC2Error

Retrieves the specified string parameter.

Parameters:

name - The parameter name.

Returns:

The parameter value as a string.

Throws:

JSONRPC2Error - With proper code and message if the specified parameter doesn't exist or is of a different type.

getOptString

public java.lang.String getOptString(java.lang.String name,
                                     java.lang.String defaultValue)
                              throws JSONRPC2Error

Retrieves the specified optional string parameter. If it doesn't exist the method will return the specified default value.

Parameters:

name - The parameter name.

defaultValue - The default return value if the parameter is not defined.

Returns:

The parameter value as a string.

Throws:

JSONRPC2Error - With proper code and message if the specified parameter is of a different type.

getEnumString

public java.lang.String getEnumString(java.lang.String name,
                                      java.lang.String[] enumStrings)
                               throws JSONRPC2Error

Retrieves the specified enumerated string parameter.

Parameters:

name - The parameter name.

enumStrings - The possible string values.

Returns:

The parameter value as a string.

Throws:

JSONRPC2Error - With proper code and message if the specified parameter doesn't exist, is of a different type or doesn't match the expected values.

getEnumString

public java.lang.String getEnumString(java.lang.String name,
                                      java.lang.String[] enumStrings,
                                      boolean ignoreCase)
                               throws JSONRPC2Error

Retrieves the specified enumerated string parameter, allowing for a case insenstive match.

Parameters:

name - The parameter name.

enumStrings - The possible string values.

ignoreCase - Specifies if the case of the value must match the case of the expected strings.

Returns:

The parameter value as a string.

Throws:

JSONRPC2Error - With proper code and message if the specified parameter doesn't exist, is of a different type or doesn't match the expected values.

getOptEnumString

public java.lang.String getOptEnumString(java.lang.String name,
                                         java.lang.String[] enumStrings,
                                         java.lang.String defaultValue)
                                  throws JSONRPC2Error

Retrieves the specified optional enumerated string parameter.

Parameters:

name - The parameter name.

enumStrings - The possible string values.

defaultValue - The default return value if the parameter is not defined.

Returns:

The parameter value as a string.

Throws:

JSONRPC2Error - With proper code and message if the specified parameter is of a different type or doesn't match the expected values.

getOptEnumString

public java.lang.String getOptEnumString(java.lang.String name,
                                         java.lang.String[] enumStrings,
                                         java.lang.String defaultValue,
                                         boolean ignoreCase)
                                  throws JSONRPC2Error

Retrieves the specified optional enumerated string parameter, allowing for a case insenstive match. If it doesn't exist the method will return the specified default value.

Parameters:

name - The parameter name.

enumStrings - The possible string values.

defaultValue - The default return value if the parameter is not defined.

ignoreCase - Specifies if the case of the value must match the case of the expected strings.

Returns:

The parameter value as a string.

Throws:

JSONRPC2Error - With proper code and message if the specified parameter is of a different type or doesn't match the expected values.

getBoolean

public boolean getBoolean(java.lang.String name)
                   throws JSONRPC2Error

Retrieves the specified boolean (maps from JSON true/false) parameter.

Parameters:

name - The parameter name.

Returns:

The parameter value as a boolean.

Throws:

JSONRPC2Error - With proper code and message if the specified parameter doesn't exist or is of a different type.

getOptBoolean

public boolean getOptBoolean(java.lang.String name,
                             boolean defaultValue)
                      throws JSONRPC2Error

Retrieves the specified optional boolean (maps from JSON true/false) parameter. If it doesn't exist the method will return the specified default value.

Parameters:

name - The parameter name.

defaultValue - The default return value if the parameter is not defined.

Returns:

The parameter value as a boolean.

Throws:

JSONRPC2Error - With proper code and message if the specified parameter is of a different type.

getInt

public int getInt(java.lang.String name)
           throws JSONRPC2Error

Retrieves the specified integer parameter.

Parameters:

name - The parameter name.

Returns:

The parameter value as an integer.

Throws:

JSONRPC2Error - With proper code and message if the specified parameter doesn't exist or is of a different type.

getOptInt

public int getOptInt(java.lang.String name,
                     int defaultValue)
              throws JSONRPC2Error

Retrieves the specified optional integer parameter. If it doesn't exist the method will return the specified default value.

Parameters:

name - The parameter name.

defaultValue - The default return value if the parameter is not defined.

Returns:

The parameter value as a boolean.

Throws:

JSONRPC2Error - With proper code and message if the specified parameter is of a different type.

getLong

public long getLong(java.lang.String name)
             throws JSONRPC2Error

Retrieves the specified long parameter.

Parameters:

name - The parameter name.

Returns:

The parameter value as a long.

Throws:

JSONRPC2Error - With proper code and message if the specified parameter doesn't exist or is of a different type.

getOptLong

public long getOptLong(java.lang.String name,
                       long defaultValue)
                throws JSONRPC2Error

Retrieves the specified optional long parameter. If it doesn't exist the method will return the specified default value.

Parameters:

name - The parameter name.

defaultValue - The default return value if the parameter is not defined.

Returns:

The parameter value as a long.

Throws:

JSONRPC2Error - With proper code and message if the specified parameter is of a different type.

getFloat

public float getFloat(java.lang.String name)
               throws JSONRPC2Error

Retrieves the specified float parameter.

Parameters:

name - The parameter name.

Returns:

The parameter value as a float.

Throws:

JSONRPC2Error - With proper code and message if the specified parameter doesn't exist or is of a different type.

getOptFloat

public float getOptFloat(java.lang.String name,
                         float defaultValue)
                  throws JSONRPC2Error

Retrieves the specified optional float parameter. If it doesn't exist the method will return the specified default value.

Parameters:

name - The parameter name.

defaultValue - The default return value if the parameter is not defined.

Returns:

The parameter value as a float.

Throws:

JSONRPC2Error - With proper code and message if the specified parameter is of a different type.

getDouble

public double getDouble(java.lang.String name)
                 throws JSONRPC2Error

Retrieves the specified double parameter.

Parameters:

name - The parameter name.

Returns:

The parameter value as a double.

Throws:

JSONRPC2Error - With proper code and message if the specified parameter doesn't exist or is of a different type.

getOptDouble

public double getOptDouble(java.lang.String name,
                           double defaultValue)
                    throws JSONRPC2Error

Retrieves the specified optional double parameter. If it doesn't exist the method will return the specified default value.

Parameters:

name - The parameter name.

defaultValue - The default return value if the parameter is not defined.

Returns:

The parameter value as a double.

Throws:

JSONRPC2Error - With proper code and message if the specified parameter is of a different type.

getList

public java.util.List getList(java.lang.String name)
                       throws JSONRPC2Error

Retrieves the specified list (maps from JSON array) parameter.

Parameters:

name - The parameter name.

Returns:

The parameter value as a list.

Throws:

JSONRPC2Error - With proper code and message if the specified parameter doesn't exist or is of a different type.

getOptList

public java.util.List getOptList(java.lang.String name,
                                 java.util.List defaultValue)
                          throws JSONRPC2Error

Retrieves the specified optional list (maps from JSON array) parameter. If it doesn't exist the method will return the specified default value.

Parameters:

name - The parameter name.

defaultValue - The default return value if the parameter is not defined.

Returns:

The parameter value as a list.

Throws:

JSONRPC2Error - With proper code and message if the specified parameter is of a different type.

getStringArray

public java.lang.String[] getStringArray(java.lang.String name)
                                  throws JSONRPC2Error

Retrieves the specified string array (maps from JSON array of strings) parameter.

Parameters:

name - The parameter name.

Returns:

The parameter value as a string array.

Throws:

JSONRPC2Error - With proper code and message if the specified parameter doesn't exist or is of a different type.

getOptStringArray

public java.lang.String[] getOptStringArray(java.lang.String name,
                                            java.lang.String[] defaultValue)
                                     throws JSONRPC2Error

Retrieves the specified optional string array (maps from JSON array of strings) parameter. If it doesn't exist the method will return the specified default value.

Parameters:

name - The parameter name.

defaultValue - The default return value if the parameter is not defined.

Returns:

The parameter value as a string array.

Throws:

JSONRPC2Error - With proper code and message if the specified parameter is of a different type.

getBooleanArray

public boolean[] getBooleanArray(java.lang.String name)
                          throws JSONRPC2Error

Retrieves the specified boolean array (maps from JSON array of true/false values) parameter.

Parameters:

name - The parameter name.

Returns:

The parameter value as a boolean array.

Throws:

JSONRPC2Error - With proper code and message if the specified parameter doesn't exist or is of a different type.

getOptBooleanArray

public boolean[] getOptBooleanArray(java.lang.String name,
                                    boolean[] defaultValue)
                             throws JSONRPC2Error

Retrieves the specified optional boolean array (maps from JSON array of true/false values) parameter. If it doesn't exist the method will return the specified default value.

Parameters:

name - The parameter name.

defaultValue - The default return value if the parameter is not defined.

Returns:

The parameter value as a boolean array.

Throws:

JSONRPC2Error - With proper code and message if the specified parameter is of a different type.

getIntArray

public int[] getIntArray(java.lang.String name)
                  throws JSONRPC2Error

Retrieves the specified integer array (maps from JSON array of integer numbers) parameter.

Parameters:

name - The parameter name.

Returns:

The parameter value as an int array.

Throws:

JSONRPC2Error - With proper code and message if the specified parameter doesn't exist or is of a different type.

getOptIntArray

public int[] getOptIntArray(java.lang.String name,
                            int[] defaultValue)
                     throws JSONRPC2Error

Retrieves the specified optional integer array (maps from JSON array of integer numbers) parameter. If it doesn't exist the method will return the specified default value.

Parameters:

name - The parameter name.

defaultValue - The default return value if the parameter is not defined.

Returns:

The parameter value as an int array.

Throws:

JSONRPC2Error - With proper code and message if the specified parameter is of a different type.

getLongArray

public long[] getLongArray(java.lang.String name)
                    throws JSONRPC2Error

Retrieves the specified long array (maps from JSON array of integer numbers) parameter.

Parameters:

name - The parameter name.

Returns:

The parameter value as a long array.

Throws:

JSONRPC2Error - With proper code and message if the specified parameter doesn't exist or is of a different type.

getOptLongArray

public long[] getOptLongArray(java.lang.String name,
                              long[] defaultValue)
                       throws JSONRPC2Error

Retrieves the specified optional long array (maps from JSON array of integer numbers) parameter. If it doesn't exist the method will return the specified default value.

Parameters:

name - The parameter name.

defaultValue - The default return value if the parameter is not defined.

Returns:

The parameter value as a long array.

Throws:

JSONRPC2Error - With proper code and message if the specified parameter is of a different type.

getFloatArray

public float[] getFloatArray(java.lang.String name)
                      throws JSONRPC2Error

Retrieves the specified float array (maps from JSON array of fraction numbers) parameter.

Parameters:

name - The parameter name.

Returns:

The parameter value as a float array.

Throws:

JSONRPC2Error - With proper code and message if the specified parameter doesn't exist or is of a different type.

getOptFloatArray

public float[] getOptFloatArray(java.lang.String name,
                                float[] defaultValue)
                         throws JSONRPC2Error

Retrieves the specified optional float array (maps from JSON array of fraction numbers) parameter. If it doesn't exist the method will return the specified default value.

Parameters:

name - The parameter name.

defaultValue - The default return value if the parameter is not defined.

Returns:

The parameter value as a float array.

Throws:

JSONRPC2Error - With proper code and message if the specified parameter is of a different type.

getDoubleArray

public double[] getDoubleArray(java.lang.String name)
                        throws JSONRPC2Error

Retrieves the specified double array (maps from JSON array of fraction numbers) parameter.

Parameters:

name - The parameter name.

Returns:

The parameter value as a double array.

Throws:

JSONRPC2Error - With proper code and message if the specified parameter doesn't exist or is of a different type.

getOptDoubleArray

public double[] getOptDoubleArray(java.lang.String name,
                                  double[] defaultValue)
                           throws JSONRPC2Error

Retrieves the specified optional double array (maps from JSON array of fraction numbers) parameter. If it doesn't exist the method will return the specified default value.

Parameters:

name - The parameter name.

defaultValue - The default return value if the parameter is not defined.

Returns:

The parameter value as a double array.

Throws:

JSONRPC2Error - With proper code and message if the specified parameter is of a different type.

getMap

public java.util.Map getMap(java.lang.String name)
                     throws JSONRPC2Error

Retrieves the specified map (maps from JSON object) parameter.

Parameters:

name - The parameter name.

Returns:

The parameter value as a map.

Throws:

JSONRPC2Error - With proper code and message if the specified parameter doesn't exist or is of a different type.

getOptMap

public java.util.Map getOptMap(java.lang.String name,
                               java.util.Map defaultValue)
                        throws JSONRPC2Error

Retrieves the specified optional map (maps from JSON object) parameter. If it doesn't exist the method will return the specified default value.

Parameters:

name - The parameter name.

defaultValue - The default return value if the parameter is not defined.

Returns:

The parameter value as a map.

Throws:

JSONRPC2Error - With proper code and message if the specified parameter is of a different type.

get

public java.lang.Object get(java.lang.String name)
                     throws JSONRPC2Error

Retrieves the specified parameter which can be of any type. Use this generic getter if you want to cast the value yourself. Otherwise look at the typed get* methods.

Parameters:

name - The parameter name.

Returns:

The parameter value.

Throws:

JSONRPC2Error - With proper code and message if the specified parameter doesn't exist.

get

public java.lang.Object get(java.lang.String name,
                            java.lang.Object refType)
                     throws JSONRPC2Error

Retrieves the specified parameter which must match the provided reference type.

Parameters:

name - The parameter name.

refType - The type the parameter value must match, specified as an instance of the same class. Set to null to match any type.

Returns:

The parameter value.

Throws:

JSONRPC2Error - With proper code and message if the specified parameter doesn't exist or its type doesn't match.

getOpt

public java.lang.Object getOpt(java.lang.String name,
                               java.lang.Object defaultValue)
                        throws JSONRPC2Error

Retrieves the specified optional parameter which must have the same type as the default value. If the paramter doesn't exist the method returns the specified default value.

Parameters:

name - The parameter name.

defaultValue - The default return value if the parameter doesn't exist.

Returns:

The parameter value.

Throws:

JSONRPC2Error - With proper code and message if the specified parameter doesn't exist or its type doesn't match.