Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.thetransactioncompany.jsonrpc2.util
Class PositionalParamsRetriever

java.lang.Object
  extended by com.thetransactioncompany.jsonrpc2.util.ParamsRetriever
      extended by com.thetransactioncompany.jsonrpc2.util.PositionalParamsRetriever

public class PositionalParamsRetriever
extends ParamsRetriever

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

Example: suppose you have a method with 3 positional parameters where the first two are mandatory and the last is optional and has a default value of true. 

 // Parse received request string
 JSONRPC2Request request = null;

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

 // Create a new retriever for positional parameters
 List params = (List)request.getParams();
 PositionalParamsRetriever r = new PositionalParamsRetriever(params);

 try {
         // Extract first mandatory string parameter
         String param1 = r.getString(0);

         // Extract second integer parameter
         int param2 = r.getInt(1);

         // Extract third optional boolean parameter which defaults to true
         boolean param3 = r.getOptBoolean(2, true);

 } 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
PositionalParamsRetriever(java.util.List params)
          Creates a new positional parameters instance from the specified value list.
 
Method Summary
 void ensureParameter(int position)
          Throws a JSONRPC2Error.INVALID_PARAMS exception if there is no parameter at the specified position.
 void ensureParameter(int position, java.lang.Object typeRef)
          Throws a JSONRPC2Error.INVALID_PARAMS exception if there is no parameter at the specified position, or its type doesn't match the specified.
 java.lang.Object get(int position)
          Retrieves the specified parameter which can be of any type.
 java.lang.Object get(int position, java.lang.Object refType)
          Retrieves the specified parameter which must match the provided reference type.
 boolean getBoolean(int position)
          Retrieves the specified boolean (maps from JSON true/false) parameter.
 boolean[] getBooleanArray(int position)
          Retrieves the specified boolean array (maps from JSON array of true/false values) parameter.
 double getDouble(int position)
          Retrieves the specified double parameter.
 double[] getDoubleArray(int position)
          Retrieves the specified double array (maps from JSON array of fraction numbers) parameter.
 java.lang.String getEnumString(int position, java.lang.String[] enumStrings)
          Retrieves the specified enumerated string parameter.
 java.lang.String getEnumString(int position, java.lang.String[] enumStrings, boolean ignoreCase)
          Retrieves the specified enumerated string parameter, allowing for a case insenstive match.
 float getFloat(int position)
          Retrieves the specified float parameter.
 float[] getFloatArray(int position)
          Retrieves the specified float array (maps from JSON array of fraction numbers) parameter.
 int getInt(int position)
          Retrieves the specified integer parameter.
 int[] getIntArray(int position)
          Retrieves the specified integer array (maps from JSON array of integer numbers) parameter.
 java.util.List getList(int position)
          Retrieves the specified list (maps from JSON array) parameter.
 long getLong(int position)
          Retrieves the specified long parameter.
 long[] getLongArray(int position)
          Retrieves the specified long array (maps from JSON array of integer numbers) parameter.
 java.util.Map getMap(int position)
          Retrieves the specified map (maps from JSON object) parameter.
 java.lang.Object getOpt(int position, java.lang.Object defaultValue)
          Retrieves the specified optional parameter which must have the same type as the default value.
 boolean getOptBoolean(int position, boolean defaultValue)
          Retrieves the specified optional boolean (maps from JSON true/false) parameter.
 boolean[] getOptBooleanArray(int position, boolean[] defaultValue)
          Retrieves the specified optional boolean array (maps from JSON array of true/false values) parameter.
 double getOptDouble(int position, double defaultValue)
          Retrieves the specified optional double parameter.
 double[] getOptDoubleArray(int position, double[] defaultValue)
          Retrieves the specified optional double array (maps from JSON array of fraction numbers) parameter.
 java.lang.String getOptEnumString(int position, java.lang.String[] enumStrings, java.lang.String defaultValue)
          Retrieves the specified optional enumerated string parameter.
 java.lang.String getOptEnumString(int position, 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(int position, float defaultValue)
          Retrieves the specified optional float parameter.
 float[] getOptFloatArray(int position, float[] defaultValue)
          Retrieves the specified optional float array (maps from JSON array of fraction numbers) parameter.
 int getOptInt(int position, int defaultValue)
          Retrieves the specified optional integer parameter.
 int[] getOptIntArray(int position, int[] defaultValue)
          Retrieves the specified optional integer array (maps from JSON array of integer numbers) parameter.
 java.util.List getOptList(int position, java.util.List defaultValue)
          Retrieves the specified optional list (maps from JSON array) parameter.
 long getOptLong(int position, long defaultValue)
          Retrieves the specified optional long parameter.
 long[] getOptLongArray(int position, long[] defaultValue)
          Retrieves the specified optional long array (maps from JSON array of integer numbers) parameter.
 java.util.Map getOptMap(int position, java.util.Map defaultValue)
          Retrieves the specified optional map (maps from JSON object) paramter.
 java.lang.String getOptString(int position, java.lang.String defaultValue)
          Retrieves the specified optional string parameter.
 java.lang.String[] getOptStringArray(int position, java.lang.String[] defaultValue)
          Retrieves the specified optional string array (maps from JSON array of strings) parameter.
 java.lang.String getString(int position)
          Retrieves the specified string parameter.
 java.lang.String[] getStringArray(int position)
          Retrieves the specified string array (maps from JSON array of strings) parameter.
 boolean hasParameter(int position)
          Returns true a parameter at the specified position exists, otherwise false.
 int size()
          Returns the number of positional 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

PositionalParamsRetriever

public PositionalParamsRetriever(java.util.List params)
Creates a new positional parameters instance from the specified value list.

Parameters:
params - The positional parameters list.
Method Detail

size

public int size()
Returns the number of positional parameters.

Specified by:
size in class ParamsRetriever
Returns:
The number of positional parameters.

ensureParameter

public void ensureParameter(int position)
                     throws JSONRPC2Error
Throws a JSONRPC2Error.INVALID_PARAMS exception if there is no parameter at the specified position.

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

Parameters:
position - The parameter position, starting with zero for the first.
Throws:
JSONRPC2Error - With proper code and message if the parameter is missing.

ensureParameter

public void ensureParameter(int position,
                            java.lang.Object typeRef)
                     throws JSONRPC2Error
Throws a JSONRPC2Error.INVALID_PARAMS exception if there is no parameter at the specified position, 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:
position - The parameter position.
typeRef - The parameter's expected 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 expected.

hasParameter

public boolean hasParameter(int position)
Returns true a parameter at the specified position exists, otherwise false.

Parameters:
position - The parameter position.
Returns:
true if the parameter exists, otherwise false.

getString

public java.lang.String getString(int position)
                           throws JSONRPC2Error
Retrieves the specified string parameter.

Parameters:
position - The parameter position.
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(int position,
                                     java.lang.String defaultValue)
                              throws JSONRPC2Error
Retrieves the specified optional string parameter. If not defined the method will return the specified default value.

Parameters:
position - The parameter position.
defaultValue - The default return value if the parameter doesn't exist.
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(int position,
                                      java.lang.String[] enumStrings)
                               throws JSONRPC2Error
Retrieves the specified enumerated string parameter.

Parameters:
position - The parameter position.
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(int position,
                                      java.lang.String[] enumStrings,
                                      boolean ignoreCase)
                               throws JSONRPC2Error
Retrieves the specified enumerated string parameter, allowing for a case insenstive match.

Parameters:
position - The parameter position.
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(int position,
                                         java.lang.String[] enumStrings,
                                         java.lang.String defaultValue)
                                  throws JSONRPC2Error
Retrieves the specified optional enumerated string parameter.

Parameters:
position - The parameter position.
enumStrings - The possible string values.
defaultValue - The default return value if the parameter doesn't exist.
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(int position,
                                         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 not defined the method will return the specified default value.

Parameters:
position - The parameter position.
enumStrings - The possible string values.
defaultValue - The default return value if the parameter doesn't exist.
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(int position)
                   throws JSONRPC2Error
Retrieves the specified boolean (maps from JSON true/false) parameter.

Parameters:
position - The parameter position.
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(int position,
                             boolean defaultValue)
                      throws JSONRPC2Error
Retrieves the specified optional boolean (maps from JSON true/false) parameter. If not defined the method will return the specified default value.

Parameters:
position - The parameter position.
defaultValue - The default return value if the parameter doesn't exist.
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(int position)
           throws JSONRPC2Error
Retrieves the specified integer parameter.

Parameters:
position - The parameter position.
Returns:
The parameter value as an integer.
Throws:
JSONRPC2Error - With proper code and message if the specified parameterdoesn't exist or is of a different type.

getOptInt

public int getOptInt(int position,
                     int defaultValue)
              throws JSONRPC2Error
Retrieves the specified optional integer parameter. If not defined the method will return the specified default value.

Parameters:
position - The parameter position.
defaultValue - The default return value if the parameter doesn't exist.
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(int position)
             throws JSONRPC2Error
Retrieves the specified long parameter.

Parameters:
position - The parameter position.
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(int position,
                       long defaultValue)
                throws JSONRPC2Error
Retrieves the specified optional long parameter. If not defined the method will return the specified default value.

Parameters:
position - The parameter position.
defaultValue - The default return value if the parameter doesn't exist.
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(int position)
               throws JSONRPC2Error
Retrieves the specified float parameter.

Parameters:
position - The parameter position.
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(int position,
                         float defaultValue)
                  throws JSONRPC2Error
Retrieves the specified optional float parameter. If not defined the method will return the specified default value.

Parameters:
position - The parameter position.
defaultValue - The default return value if the parameter doesn't exist.
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(int position)
                 throws JSONRPC2Error
Retrieves the specified double parameter.

Parameters:
position - The parameter position.
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(int position,
                           double defaultValue)
                    throws JSONRPC2Error
Retrieves the specified optional double parameter. If not defined the method will return the specified default value.

Parameters:
position - The parameter position.
defaultValue - The default return value if the parameter doesn't exist.
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(int position)
                       throws JSONRPC2Error
Retrieves the specified list (maps from JSON array) parameter.

Parameters:
position - The parameter position.
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(int position,
                                 java.util.List defaultValue)
                          throws JSONRPC2Error
Retrieves the specified optional list (maps from JSON array) parameter. If not defined the method will return the specified default value.

Parameters:
position - The parameter position.
defaultValue - The default return value if the parameter doesn't exist.
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(int position)
                                  throws JSONRPC2Error
Retrieves the specified string array (maps from JSON array of strings) parameter.

Parameters:
position - The parameter position.
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(int position,
                                            java.lang.String[] defaultValue)
                                     throws JSONRPC2Error
Retrieves the specified optional string array (maps from JSON array of strings) parameter. If not defined the method will return the specified default value.

Parameters:
position - The parameter position.
defaultValue - The default return value if the parameter doesn't exist.
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(int position)
                          throws JSONRPC2Error
Retrieves the specified boolean array (maps from JSON array of true/false values) parameter.

Parameters:
position - The parameter position.
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(int position,
                                    boolean[] defaultValue)
                             throws JSONRPC2Error
Retrieves the specified optional boolean array (maps from JSON array of true/false values) parameter. If not defined the method will return the specified default value.

Parameters:
position - The parameter position.
defaultValue - The default return value if the parameter doesn't exist.
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(int position)
                  throws JSONRPC2Error
Retrieves the specified integer array (maps from JSON array of integer numbers) parameter.

Parameters:
position - The parameter position.
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(int position,
                            int[] defaultValue)
                     throws JSONRPC2Error
Retrieves the specified optional integer array (maps from JSON array of integer numbers) parameter. If not defined the method will return the specified default value.

Parameters:
position - The parameter position.
defaultValue - The default return value if the parameter doesn't exist.
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(int position)
                    throws JSONRPC2Error
Retrieves the specified long array (maps from JSON array of integer numbers) parameter.

Parameters:
position - The parameter position.
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(int position,
                              long[] defaultValue)
                       throws JSONRPC2Error
Retrieves the specified optional long array (maps from JSON array of integer numbers) parameter. If not defined the method will return the specified default value.

Parameters:
position - The parameter position.
defaultValue - The default return value if the parameter doesn't exist.
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(int position)
                      throws JSONRPC2Error
Retrieves the specified float array (maps from JSON array of fraction numbers) parameter.

Parameters:
position - The parameter position.
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(int position,
                                float[] defaultValue)
                         throws JSONRPC2Error
Retrieves the specified optional float array (maps from JSON array of fraction numbers) parameter. If not defined the method will return the specified default value.

Parameters:
position - The parameter position.
defaultValue - The default return value if the parameter doesn't exist.
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(int position)
                        throws JSONRPC2Error
Retrieves the specified double array (maps from JSON array of fraction numbers) parameter.

Parameters:
position - The parameter position.
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(int position,
                                  double[] defaultValue)
                           throws JSONRPC2Error
Retrieves the specified optional double array (maps from JSON array of fraction numbers) parameter. If not defined the method will return the specified default value.

Parameters:
position - The parameter position.
defaultValue - The default return value if the parameter doesn't exist.
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(int position)
                     throws JSONRPC2Error
Retrieves the specified map (maps from JSON object) parameter.

Parameters:
position - The parameter position.
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(int position,
                               java.util.Map defaultValue)
                        throws JSONRPC2Error
Retrieves the specified optional map (maps from JSON object) paramter. If not defined the method will return the specified default value.

Parameters:
position - The parameter position.
defaultValue - The default return value if the parameter doesn't exist.
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(int position)
                     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:
position - The parameter position.
Returns:
The parameter value.
Throws:
JSONRPC2Error - With proper code and message if the specified parameter doesn't exist.

get

public java.lang.Object get(int position,
                            java.lang.Object refType)
                     throws JSONRPC2Error
Retrieves the specified parameter which must match the provided reference type.

Parameters:
position - The parameter position.
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(int position,
                               java.lang.Object defaultValue)
                        throws JSONRPC2Error
Retrieves the specified optional parameter which must have the same type as the default value. If the parameter doesn't exist the method returns the specified default value.

Parameters:
position - The parameter position.
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.
Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Copyright © 2009-2010 Vladimir Dzhuvinov. All Rights Reserved.