com.thetransactioncompany.jsonrpc2.util.ParamsRetriever
com.thetransactioncompany.jsonrpc2.util.PositionalParamsRetriever
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
java.lang.Object
public class PositionalParamsRetriever
Utility class for retrieving JSON-RPC 2.0 positional parameters (packed into a JSON Array).
Provides a set of getter methods according to the expected parameter type (number, string, etc.) and whether the parameter is mandatory or optional:
getXXX(param_pos) for mandatory parameters, where XXX
is the expected parameter type.getOptXXX(param_pos, default_value) for optional parameters,
specifying a default value.There are also generic getter methods that let you do the type conversion yourself.
If a parameter cannot be retrieved, e.g. due to a missing mandatory
parameter or bad type, a
JSONRPC2Error.INVALID_PARAMS
exception is thrown.
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 unexpected 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);
}
| Constructor Summary | |
|---|---|
PositionalParamsRetriever(java.util.List<java.lang.Object> params)
Creates a new positional parameters retriever 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. |
|
|
ensureParameter(int position,
java.lang.Class<T> clazz)
Throws a JSONRPC2Error.INVALID_PARAMS exception if there is
no parameter at the specified position, its value is null,
or its type doesn't map to the specified. |
|
|
ensureParameter(int position,
java.lang.Class<T> clazz,
boolean allowNull)
Throws a JSONRPC2Error.INVALID_PARAMS exception if there is
no parameter at the specified position or its type doesn't map to the
specified. |
|
java.lang.Object |
get(int position)
Retrieves the specified parameter which can be of any type. |
|
|
get(int position,
java.lang.Class<T> clazz)
Retrieves the specified parameter which must map to the provided class (use the appropriate wrapper class for primitive types). |
|
|
get(int position,
java.lang.Class<T> clazz,
boolean allowNull)
Retrieves the specified parameter which must map to the provided class (use the appropriate wrapper class for primitive types). |
|
boolean |
getBoolean(int position)
Retrieves the specified boolean (maps from JSON true/false) parameter. |
|
double |
getDouble(int position)
Retrieves the specified numeric parameter as a double. |
|
|
getEnum(int position,
java.lang.Class<T> enumClass)
Retrieves the specified enumerated parameter (from a JSON string that has a predefined set of possible values). |
|
|
getEnum(int position,
java.lang.Class<T> enumClass,
boolean ignoreCase)
Retrieves the specified enumerated parameter (from a JSON string that has a predefined set of possible values), allowing for a case insensitive match. |
|
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 numeric parameter as a float. |
|
int |
getInt(int position)
Retrieves the specified numeric parameter as an int. |
|
java.util.List<java.lang.Object> |
getList(int position)
Retrieves the specified list (maps from JSON array) parameter. |
|
java.util.List<java.lang.Object> |
getList(int position,
boolean allowNull)
Retrieves the specified list (maps from JSON array) parameter. |
|
long |
getLong(int position)
Retrieves the specified numeric parameter as a long. |
|
java.util.Map<java.lang.String,java.lang.Object> |
getMap(int position)
Retrieves the specified map (maps from JSON object) parameter. |
|
java.util.Map<java.lang.String,java.lang.Object> |
getMap(int position,
boolean allowNull)
Retrieves the specified map (maps from JSON object) parameter. |
|
|
getOpt(int position,
java.lang.Class<T> clazz,
boolean allowNull,
T defaultValue)
Retrieves the specified optional parameter which must map to the provided class (use the appropriate wrapper class for primitive types). |
|
|
getOpt(int position,
java.lang.Class<T> clazz,
T defaultValue)
Retrieves the specified optional parameter which must map to the provided class (use the appropriate wrapper class for primitive types). |
|
boolean |
getOptBoolean(int position,
boolean defaultValue)
Retrieves the specified optional boolean (maps from JSON true/false) parameter. |
|
double |
getOptDouble(int position,
double defaultValue)
Retrieves the specified optional numeric parameter as a double. |
|
|
getOptEnum(int position,
java.lang.Class<T> enumClass,
java.lang.String defaultValue)
Retrieves the specified optional enumerated parameter (from a JSON string that has a predefined set of possible values). |
|
|
getOptEnum(int position,
java.lang.Class<T> enumClass,
java.lang.String defaultValue,
boolean ignoreCase)
Retrieves the specified optional enumerated parameter (from a JSON string that has a predefined set of possible values), allowing for a case insenstive match. |
|
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 numeric parameter as a float. |
|
int |
getOptInt(int position,
int defaultValue)
Retrieves the specified optional numeric parameter as an int. |
|
java.util.List<java.lang.Object> |
getOptList(int position,
boolean allowNull,
java.util.List<java.lang.Object> defaultValue)
Retrieves the specified optional list (maps from JSON array) parameter. |
|
java.util.List<java.lang.Object> |
getOptList(int position,
java.util.List<java.lang.Object> defaultValue)
Retrieves the specified optional list (maps from JSON array) parameter. |
|
long |
getOptLong(int position,
long defaultValue)
Retrieves the specified optional numeric parameter as a long. |
|
java.util.Map<java.lang.String,java.lang.Object> |
getOptMap(int position,
boolean allowNull,
java.util.Map<java.lang.String,java.lang.Object> defaultValue)
Retrieves the specified optional map (maps from JSON object) parameter. |
|
java.util.Map<java.lang.String,java.lang.Object> |
getOptMap(int position,
java.util.Map<java.lang.String,java.lang.Object> defaultValue)
Retrieves the specified optional map (maps from JSON object) parameter. |
|
java.lang.String |
getOptString(int position,
boolean allowNull,
java.lang.String defaultValue)
Retrieves the specified optional string parameter. |
|
java.lang.String |
getOptString(int position,
java.lang.String defaultValue)
Retrieves the specified optional string parameter. |
|
java.lang.String[] |
getOptStringArray(int position,
boolean allowNull,
java.lang.String[] defaultValue)
Retrieves the specified optional string array (maps from JSON array of strings) 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 |
getString(int position,
boolean allowNull)
Retrieves the specified string parameter. |
|
java.lang.String[] |
getStringArray(int position)
Retrieves the specified string array (maps from JSON array of strings) parameter. |
|
java.lang.String[] |
getStringArray(int position,
boolean allowNull)
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,
else false. |
|
int |
size()
Returns the number of available positional parameters. |
|
| Methods inherited from class com.thetransactioncompany.jsonrpc2.util.ParamsRetriever |
|---|
ensureEnumString, ensureEnumString |
| Methods inherited from class java.lang.Object |
|---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
| Constructor Detail |
|---|
public PositionalParamsRetriever(java.util.List<java.lang.Object> params)
params - The positional parameters list.| Method Detail |
|---|
public int size()
size in class ParamsRetrieverpublic boolean hasParameter(int position)
true a parameter at the specified position exists,
else false.
position - The parameter position.
true if the parameter exists, else false.
public void ensureParameter(int position)
throws JSONRPC2Error
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.
position - The parameter position, starting with zero for the
first.
JSONRPC2Error - On a missing parameter
(JSONRPC2Error.INVALID_PARAMS).
public <T> void ensureParameter(int position,
java.lang.Class<T> clazz)
throws JSONRPC2Error
JSONRPC2Error.INVALID_PARAMS exception if there is
no parameter at the specified position, its value is null,
or its type doesn't map to the specified.
You may use this method to fire the proper JSON-RPC 2.0 error on a missing or badly-typed mandatory parameter.
position - The parameter position.clazz - The corresponding Java class that the parameter
should map to (any one of the return types of the
getXXX() getter methods. Set to
Object.class to allow any type.
JSONRPC2Error - On a missing parameter, null value or
bad type (JSONRPC2Error.INVALID_PARAMS).
public <T> void ensureParameter(int position,
java.lang.Class<T> clazz,
boolean allowNull)
throws JSONRPC2Error
JSONRPC2Error.INVALID_PARAMS exception if there is
no parameter at the specified position or its type doesn't map to the
specified.
You may use this method to fire the proper JSON-RPC 2.0 error on a missing or badly-typed mandatory parameter.
position - The parameter position.clazz - The corresponding Java class that the parameter
should map to (any one of the return types of the
getXXX() getter methods. Set to
Object.class to allow any type.allowNull - If true allows a null parameter
value.
JSONRPC2Error - On a missing parameter or bad type
(JSONRPC2Error.INVALID_PARAMS).
public java.lang.Object get(int position)
throws JSONRPC2Error
get* methods.
position - The parameter position.
JSONRPC2Error - On a missing parameter
(JSONRPC2Error.INVALID_PARAMS).
public <T> T get(int position,
java.lang.Class<T> clazz)
throws JSONRPC2Error
position - The parameter position.clazz - The corresponding Java class that the parameter
should map to (any one of the return types of the
getXXX() getter methods. Set to
Object.class to allow any type.
JSONRPC2Error - On a missing parameter, null value or
bad type (JSONRPC2Error.INVALID_PARAMS).
public <T> T get(int position,
java.lang.Class<T> clazz,
boolean allowNull)
throws JSONRPC2Error
position - The parameter position.clazz - The corresponding Java class that the parameter
should map to (any one of the return types of the
getXXX() getter methods. Set to
Object.class to allow any type.allowNull - If true allows a null parameter
value.
JSONRPC2Error - On a missing parameter or bad type
(JSONRPC2Error.INVALID_PARAMS).
public <T> T getOpt(int position,
java.lang.Class<T> clazz,
T defaultValue)
throws JSONRPC2Error
position - The parameter position.clazz - The corresponding Java class that the parameter
should map to (any one of the return types of the
getXXX() getter methods. Set to
Object.class to allow any type.defaultValue - The default return value if the parameter
doesn't exist. May be null.
JSONRPC2Error - On a bad parameter type or null value
(JSONRPC2Error.INVALID_PARAMS).
public <T> T getOpt(int position,
java.lang.Class<T> clazz,
boolean allowNull,
T defaultValue)
throws JSONRPC2Error
position - The parameter position.clazz - The corresponding Java class that the parameter
should map to (any one of the return types of the
getXXX() getter methods. Set to
Object.class to allow any type.allowNull - If true allows a null parameter
value.defaultValue - The default return value if the parameter
doesn't exist. May be null.
JSONRPC2Error - On a bad parameter type
(JSONRPC2Error.INVALID_PARAMS).
public java.lang.String getString(int position)
throws JSONRPC2Error
position - The parameter position.
JSONRPC2Error - On a missing parameter, bad type or null
value (JSONRPC2Error.INVALID_PARAMS).
public java.lang.String getString(int position,
boolean allowNull)
throws JSONRPC2Error
position - The parameter position.allowNull - If true allows a null value.
JSONRPC2Error - On a missing parameter or bad type
(JSONRPC2Error.INVALID_PARAMS).
public java.lang.String getOptString(int position,
java.lang.String defaultValue)
throws JSONRPC2Error
position - The parameter position.defaultValue - The default return value if the parameter
doesn't exist. May be null.
JSONRPC2Error - On a bad type or null value
(JSONRPC2Error.INVALID_PARAMS).
public java.lang.String getOptString(int position,
boolean allowNull,
java.lang.String defaultValue)
throws JSONRPC2Error
position - The parameter position.allowNull - If true allows a null value.defaultValue - The default return value if the parameter
doesn't exist. May be null.
JSONRPC2Error - On a bad type (JSONRPC2Error.INVALID_PARAMS).
public java.lang.String getEnumString(int position,
java.lang.String[] enumStrings)
throws JSONRPC2Error
position - The parameter position.enumStrings - The acceptable string values.
JSONRPC2Error - On a missing parameter, bad type or
bad enumeration value
(JSONRPC2Error.INVALID_PARAMS).
public java.lang.String getEnumString(int position,
java.lang.String[] enumStrings,
boolean ignoreCase)
throws JSONRPC2Error
position - The parameter position.enumStrings - The acceptable string values.ignoreCase - true for a case insensitive match.
JSONRPC2Error - On a missing parameter, bad type or
bad enumeration value
(JSONRPC2Error.INVALID_PARAMS).
public java.lang.String getOptEnumString(int position,
java.lang.String[] enumStrings,
java.lang.String defaultValue)
throws JSONRPC2Error
position - The parameter position.enumStrings - The acceptable string values.defaultValue - The default return value if the parameter
doesn't exist. May be null.
JSONRPC2Error - On a bad type or bad enumeration value
(JSONRPC2Error.INVALID_PARAMS).
public java.lang.String getOptEnumString(int position,
java.lang.String[] enumStrings,
java.lang.String defaultValue,
boolean ignoreCase)
throws JSONRPC2Error
position - The parameter position.enumStrings - The acceptable string values.defaultValue - The default return value if the parameter
doesn't exist. May be null.ignoreCase - true for a case insensitive match.
JSONRPC2Error - On a bad type or bad enumeration value
(JSONRPC2Error.INVALID_PARAMS).
public <T extends java.lang.Enum<T>> T getEnum(int position,
java.lang.Class<T> enumClass)
throws JSONRPC2Error
position - The parameter position.enumClass - An enumeration type with constant names representing
the acceptable string values.
JSONRPC2Error - On a missing parameter, bad type or
bad enumeration value
(JSONRPC2Error.INVALID_PARAMS).
public <T extends java.lang.Enum<T>> T getEnum(int position,
java.lang.Class<T> enumClass,
boolean ignoreCase)
throws JSONRPC2Error
position - The parameter position.enumClass - An enumeration type with constant names representing
the acceptable string values.ignoreCase - If true a case insensitive match against
the acceptable constant names is performed.
JSONRPC2Error - On a missing parameter, bad type or
bad enumeration value
(JSONRPC2Error.INVALID_PARAMS).
public <T extends java.lang.Enum<T>> T getOptEnum(int position,
java.lang.Class<T> enumClass,
java.lang.String defaultValue)
throws JSONRPC2Error
position - The parameter position.enumClass - An enumeration type with constant names representing
the acceptable string values.defaultValue - The default return value if the parameter
doesn't exist. May be null.
JSONRPC2Error - On a bad type or bad enumeration value
(JSONRPC2Error.INVALID_PARAMS).
public <T extends java.lang.Enum<T>> T getOptEnum(int position,
java.lang.Class<T> enumClass,
java.lang.String defaultValue,
boolean ignoreCase)
throws JSONRPC2Error
position - The parameter position.enumClass - An enumeration type with constant names representing
the acceptable string values.defaultValue - The default return value if the parameter
doesn't exist. May be null.ignoreCase - If true a case insensitive match against
the acceptable constant names is performed.
JSONRPC2Error - On a bad type or bad enumeration value
(JSONRPC2Error.INVALID_PARAMS).
public boolean getBoolean(int position)
throws JSONRPC2Error
position - The parameter position.
boolean.
JSONRPC2Error - On a missing parameter, bad type or
null value
(JSONRPC2Error.INVALID_PARAMS).
public boolean getOptBoolean(int position,
boolean defaultValue)
throws JSONRPC2Error
position - The parameter position.defaultValue - The default return value if the parameter
doesn't exist.
boolean.
JSONRPC2Error - On a bad parameter type or null value
(JSONRPC2Error.INVALID_PARAMS).
public int getInt(int position)
throws JSONRPC2Error
int.
position - The parameter position.
int.
JSONRPC2Error - On a missing parameter, bad type or
null value
(JSONRPC2Error.INVALID_PARAMS).
public int getOptInt(int position,
int defaultValue)
throws JSONRPC2Error
int.
If it doesn't exist the method will return the specified default
value.
position - The parameter position.defaultValue - The default return value if the parameter
doesn't exist.
int.
JSONRPC2Error - On a bad parameter type or null value
(JSONRPC2Error.INVALID_PARAMS).
public long getLong(int position)
throws JSONRPC2Error
long.
position - The parameter position.
long.
JSONRPC2Error - On a missing parameter, bad type or
null value
(JSONRPC2Error.INVALID_PARAMS).
public long getOptLong(int position,
long defaultValue)
throws JSONRPC2Error
long.
If it doesn't exist the method will return the specified default
value.
position - The parameter position.defaultValue - The default return value if the parameter
doesn't exist.
long.
JSONRPC2Error - On a bad parameter type or null value
(JSONRPC2Error.INVALID_PARAMS).
public float getFloat(int position)
throws JSONRPC2Error
float.
position - The parameter position.
float.
JSONRPC2Error - On a missing parameter, bad type or
null value
(JSONRPC2Error.INVALID_PARAMS).
public float getOptFloat(int position,
float defaultValue)
throws JSONRPC2Error
float. If it doesn't exist the method will return the
specified default value.
position - The parameter position.defaultValue - The default return value if the parameter
doesn't exist.
float.
JSONRPC2Error - On a bad parameter type or null value
(JSONRPC2Error.INVALID_PARAMS).
public double getDouble(int position)
throws JSONRPC2Error
double.
position - The parameter position.
double.
JSONRPC2Error - On a missing parameter, bad type or
null value
(JSONRPC2Error.INVALID_PARAMS).
public double getOptDouble(int position,
double defaultValue)
throws JSONRPC2Error
double. If it doesn't exist the method will return the
specified default value.
position - The parameter position.defaultValue - The default return value if the parameter
doesn't exist.
double.
JSONRPC2Error - On a bad parameter type or null value
(JSONRPC2Error.INVALID_PARAMS).
public java.util.List<java.lang.Object> getList(int position)
throws JSONRPC2Error
position - The parameter position.
JSONRPC2Error - On a missing parameter, bad type or
null value
(JSONRPC2Error.INVALID_PARAMS).
public java.util.List<java.lang.Object> getList(int position,
boolean allowNull)
throws JSONRPC2Error
position - The parameter position.allowNull - If true allows a null value.
JSONRPC2Error - On a missing parameter or bad type
(JSONRPC2Error.INVALID_PARAMS).
public java.util.List<java.lang.Object> getOptList(int position,
java.util.List<java.lang.Object> defaultValue)
throws JSONRPC2Error
position - The parameter position.defaultValue - The default return value if the parameter
doesn't exist. May be null.
JSONRPC2Error - On a bad parameter type or null value
(JSONRPC2Error.INVALID_PARAMS).
public java.util.List<java.lang.Object> getOptList(int position,
boolean allowNull,
java.util.List<java.lang.Object> defaultValue)
throws JSONRPC2Error
position - The parameter position.allowNull - If true allows a null value.defaultValue - The default return value if the parameter
doesn't exist. May be null.
JSONRPC2Error - On a bad parameter type
(JSONRPC2Error.INVALID_PARAMS).
public java.lang.String[] getStringArray(int position)
throws JSONRPC2Error
position - The parameter position.
JSONRPC2Error - On a missing parameter, bad type or
null value
(JSONRPC2Error.INVALID_PARAMS).
public java.lang.String[] getStringArray(int position,
boolean allowNull)
throws JSONRPC2Error
position - The parameter position.allowNull - If true allows a null value.
JSONRPC2Error - On a missing parameter or bad type
(JSONRPC2Error.INVALID_PARAMS).
public java.lang.String[] getOptStringArray(int position,
java.lang.String[] defaultValue)
throws JSONRPC2Error
position - The parameter position.defaultValue - The default return value if the parameter
doesn't exist. May be null.
JSONRPC2Error - On a bad parameter type or null value
(JSONRPC2Error.INVALID_PARAMS).
public java.lang.String[] getOptStringArray(int position,
boolean allowNull,
java.lang.String[] defaultValue)
throws JSONRPC2Error
position - The parameter position.allowNull - If true allows a null value.defaultValue - The default return value if the parameter
doesn't exist. May be null.
JSONRPC2Error - On a bad parameter type
(JSONRPC2Error.INVALID_PARAMS).
public java.util.Map<java.lang.String,java.lang.Object> getMap(int position)
throws JSONRPC2Error
position - The parameter position.
JSONRPC2Error - On a missing parameter, bad type or
null value
(JSONRPC2Error.INVALID_PARAMS).
public java.util.Map<java.lang.String,java.lang.Object> getMap(int position,
boolean allowNull)
throws JSONRPC2Error
position - The parameter position.allowNull - If true allows a null value.
JSONRPC2Error - On a missing parameter or bad type
(JSONRPC2Error.INVALID_PARAMS).
public java.util.Map<java.lang.String,java.lang.Object> getOptMap(int position,
java.util.Map<java.lang.String,java.lang.Object> defaultValue)
throws JSONRPC2Error
position - The parameter position.defaultValue - The default return value if the parameter
doesn't exist. May be null.
JSONRPC2Error - On a bad parameter type or null value
(JSONRPC2Error.INVALID_PARAMS).
public java.util.Map<java.lang.String,java.lang.Object> getOptMap(int position,
boolean allowNull,
java.util.Map<java.lang.String,java.lang.Object> defaultValue)
throws JSONRPC2Error
position - The parameter position.allowNull - If true allows a null value.defaultValue - The default return value if the parameter
doesn't exist. May be null.
JSONRPC2Error - On a bad parameter type
(JSONRPC2Error.INVALID_PARAMS).
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||