js.util

Class Params

java.lang.Object

js.util.Params

public class Params
extends Object

Invocation parameters (in)sanity tests. This utility class supplies convenient methods for invocation parameters validation, see sample usage. All throws IllegalArgumentException if validation fails. Also all have a name parameter used to format exception message; it is injected at message beginning exactly as supplied.

In sample code throws illegal argument exception if file argument is null. Exception message is 'File parameter is null.'

  void method(File file . . . {
      Params.notNull(file, "File");
      . . .
  }
 

This utility class allows for sub-classing. See js.util for utility sub-classing description.

Version:

final

Author:

Iulian Rotaru

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	Params() Prevent default constructor synthesis but allow sub-classing.

Method Summary

Modifier and Type	Method and Description
static void	belongsTo(File directory, File parameter, String name) Check if file parameter belongs to requested directory.
static void	empty(Collection<?> parameter, String name) Test if collection parameter is strictly empty, that is, not null but empty.
static void	empty(String parameter, String name) Test if string parameter is strictly empty, that is, not null but empty.
static void	EQ(char parameter, char expected, String name) Test if character parameter has expected value.
static void	EQ(double parameter, double expected, String name) Test if numeric parameter has expected value.
static void	EQ(long parameter, long expected, String name) Test if numeric parameter has expected value.
static void	EQ(String parameter, String expected, String name) Test if string parameter has expected value.
static void	GT(char parameter, char expected, String name) Test if character parameter is strictly greater than given character value.
static void	GT(double parameter, double value, String name) Test if numeric parameter is strictly greater than given threshold value.
static void	GT(long parameter, long value, String name) Test if numeric parameter is strictly greater than given threshold value.
static void	GTE(char parameter, char value, String name) Test if character parameter is greater than or equal to given character value.
static void	GTE(double parameter, double value, String name) Test if numeric parameter is greater than or equal to given threshold value.
static void	GTE(long parameter, long value, String name) Test if numeric parameter is greater than or equal to given threshold value.
static void	isDirectory(File parameter, String name) Check if file parameter is an existing directory.
static void	isFalse(boolean condition, String message, Object... args) Test if given boolean condition is false and throw exception if not.
static void	isFile(File parameter, String name) Check if file parameter is an existing ordinary file, not a directory.
static void	isKindOf(Type parameter, Type typeToMatch, String name) Test if parameter is of requested type and throw exception if not.
static void	isNumeric(String parameter, String name) Check if string parameter is numeric.
static void	isTrue(boolean condition, String message, Object... args) Test if given boolean condition is true and throw exception if not.
static void	LT(char parameter, char value, String name) Test if character parameter is strictly less than given character value.
static void	LT(double parameter, double value, String name) Test if numeric parameter is strictly less than given threshold value.
static void	LT(long parameter, long value, String name) Test if numeric parameter is strictly less than given threshold value.
static void	LTE(char parameter, char value, String name) Test if character parameter is less than or equal to given threshold value.
static void	LTE(double parameter, double value, String name) Test if numeric parameter is less than or equal to given threshold value.
static void	LTE(long parameter, long value, String name) Test if numeric parameter is less than or equal to given threshold value.
static void	notEmpty(String parameter, String name) Test if string parameter is strict not empty.
static void	notNull(Character parameter, String name, Object... args) Throw exception if parameter is null character ('\0').
static void	notNull(Object parameter, String name, Object... args) Throw exception if parameter is null.
static void	notNullOrEmpty(File parameter, String name) Test if file parameter is not null and has not empty path.
static void	notNullOrEmpty(Object[] parameter, String name) Test if array parameter is not null or empty.
static void	notNullOrEmpty(String parameter, String name) Test if string parameter is not null or empty.
static void	notZero(double parameter, String name) Test if numeric parameter is not zero.
static void	positive(double parameter, String name) Test if numeric parameter is positive or zero.
static void	range(double parameter, double lowEndpoint, double highEndpoint, String name) Test if numeric parameter is in a given range.
static void	size(Collection<?> parameter, int size, String name) Test if given collection size has a specified value.
static void	size(Map<?,?> parameter, int size, String name) Test if given map size has a specified value.
static void	strictPositive(double parameter, String name) Test if numeric parameter is strict positive.
static void	zero(double parameter, String name) Test if numeric parameter is zero.

Methods inherited from class java.lang.Object

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

Constructor Detail

Params

protected Params()

Prevent default constructor synthesis but allow sub-classing.

Method Detail

notNull

public static void notNull(Object parameter,
                           String name,
                           Object... args)
                    throws IllegalArgumentException

Throw exception if parameter is null. Name parameter can be formatted as accepted by String.format(String, Object...).

Parameters:

parameter - invocation parameter to test,

name - parameter name used on exception message,

args - optional arguments if name is formatted.

Throws:

IllegalArgumentException - if parameter is null.

notNull

public static void notNull(Character parameter,
                           String name,
                           Object... args)
                    throws IllegalArgumentException

Throw exception if parameter is null character ('\0'). Name parameter can be formatted as accepted by String.format(String, Object...).

Parameters:

parameter - invocation parameter to test,

name - parameter name used on exception message,

args - optional arguments if name is formatted.

Throws:

IllegalArgumentException - if parameter is null character ('\0').

empty

public static void empty(String parameter,
                         String name)

Test if string parameter is strictly empty, that is, not null but empty.

Parameters:

parameter - invocation string parameter,

name - the name of invocation parameter.

Throws:

IllegalArgumentException - if parameter is null or not empty.

empty

public static void empty(Collection<?> parameter,
                         String name)

Test if collection parameter is strictly empty, that is, not null but empty.

Parameters:

parameter - invocation collection parameter,

name - the name of invocation parameter.

Throws:

IllegalArgumentException - if parameter is null or not empty.

notEmpty

public static void notEmpty(String parameter,
                            String name)
                     throws IllegalArgumentException

Test if string parameter is strict not empty. If parameter to test is null this test method does not rise exception.

Parameters:

parameter - invocation string parameter,

name - the name of invocation parameter.

Throws:

IllegalArgumentException - if parameter is empty.

notNullOrEmpty

public static void notNullOrEmpty(String parameter,
                                  String name)
                           throws IllegalArgumentException

Test if string parameter is not null or empty.

Parameters:

parameter - invocation string parameter,

name - the name of invocation parameter.

Throws:

IllegalArgumentException - if parameter is null or empty.

notNullOrEmpty

public static void notNullOrEmpty(File parameter,
                                  String name)
                           throws IllegalArgumentException

Test if file parameter is not null and has not empty path.

Parameters:

parameter - invocation file parameter,

name - the name of invocation parameter.

Throws:

IllegalArgumentException - if parameter is null or its path is empty.

notNullOrEmpty

public static void notNullOrEmpty(Object[] parameter,
                                  String name)
                           throws IllegalArgumentException

Test if array parameter is not null or empty.

Parameters:

parameter - invocation array parameter,

name - the name of invocation parameter.

Throws:

IllegalArgumentException - if parameter array is null or empty.

size

public static void size(Collection<?> parameter,
                        int size,
                        String name)
                 throws IllegalArgumentException

Test if given collection size has a specified value.

Parameters:

parameter - invocation collection parameters,

size - requested size,

name - the name of invocation parameter.

Throws:

IllegalArgumentException - if collection has not requested size.

size

public static void size(Map<?,?> parameter,
                        int size,
                        String name)
                 throws IllegalArgumentException

Test if given map size has a specified value.

Parameters:

parameter - invocation map parameters,

size - requested size,

name - the name of invocation parameter.

Throws:

IllegalArgumentException - if map has not requested size.

isNumeric

public static void isNumeric(String parameter,
                             String name)

Check if string parameter is numeric. This validator throws illegal argument if parameter value is not numeric. See Strings.isNumeric(String) for numeric definition.

Parameters:

parameter - invocation parameter value,

name - parameter name.

Throws:

IllegalArgumentException - if parameter is not numeric.

isFile

public static void isFile(File parameter,
                          String name)
                   throws IllegalArgumentException

Check if file parameter is an existing ordinary file, not a directory. This validator throws illegal argument if given file does not exist or is not an ordinary file.

Parameters:

parameter - invocation file parameter,

name - parameter name.

Throws:

IllegalArgumentException - if parameter file is null or does not exist or is a directory.

isDirectory

public static void isDirectory(File parameter,
                               String name)
                        throws IllegalArgumentException

Check if file parameter is an existing directory. This validator throws illegal argument if given file does not exist or is not a directory.

Parameters:

parameter - invocation file parameter,

name - parameter name.

Throws:

IllegalArgumentException - if parameter file is null or does not designate an existing directory.

belongsTo

public static void belongsTo(File directory,
                             File parameter,
                             String name)
                      throws IllegalArgumentException

Check if file parameter belongs to requested directory. This predicate test if given directory is ancestor of parameter file.

Parameters:

directory - directory supposed to be ancestor of file parameter,

parameter - invocation file parameter,

name - parameter name.

Throws:

IllegalArgumentException - if parameter file is outside directory.

range

public static void range(double parameter,
                         double lowEndpoint,
                         double highEndpoint,
                         String name)
                  throws IllegalArgumentException

Test if numeric parameter is in a given range. Parameter is considered in range if is greater or equal with lower endpoint and smaller or equal higher endpoint.

Parameters:

parameter - invocation numeric parameter,

lowEndpoint - range lower endpoint,

highEndpoint - range higher endpoint,

name - the name of invocation parameter.

Throws:

IllegalArgumentException - if parameter is not in range.

zero

public static void zero(double parameter,
                        String name)
                 throws IllegalArgumentException

Test if numeric parameter is zero.

Parameters:

parameter - invocation numeric parameter,

name - the name of invocation parameter.

Throws:

IllegalArgumentException - if parameter is not zero.

notZero

public static void notZero(double parameter,
                           String name)
                    throws IllegalArgumentException

Test if numeric parameter is not zero.

Parameters:

parameter - invocation numeric parameter,

name - the name of invocation parameter.

Throws:

IllegalArgumentException - if parameter is zero.

positive

public static void positive(double parameter,
                            String name)
                     throws IllegalArgumentException

Test if numeric parameter is positive or zero.

Parameters:

parameter - invocation numeric parameter,

name - the name of invocation parameter.

Throws:

IllegalArgumentException - if parameter is not positive or zero.

strictPositive

public static void strictPositive(double parameter,
                                  String name)
                           throws IllegalArgumentException

Test if numeric parameter is strict positive.

Parameters:

parameter - invocation numeric parameter,

name - the name of invocation parameter.

Throws:

IllegalArgumentException - if parameter is not strict positive.

EQ

public static void EQ(long parameter,
                      long expected,
                      String name)
               throws IllegalArgumentException

Test if numeric parameter has expected value.

Parameters:

parameter - invocation numeric parameter,

expected - expected value,

name - the name of invocation parameter.

Throws:

IllegalArgumentException - if parameter has not expected value.

EQ

public static void EQ(double parameter,
                      double expected,
                      String name)
               throws IllegalArgumentException

Test if numeric parameter has expected value.

Parameters:

parameter - invocation numeric parameter,

expected - expected value,

name - the name of invocation parameter.

Throws:

IllegalArgumentException - if parameter has not expected value.

EQ

public static void EQ(String parameter,
                      String expected,
                      String name)
               throws IllegalArgumentException

Test if string parameter has expected value.

Parameters:

parameter - invocation string parameter,

expected - expected value,

name - the name of invocation parameter.

Throws:

IllegalArgumentException - if parameter has not expected value.

EQ

public static void EQ(char parameter,
                      char expected,
                      String name)
               throws IllegalArgumentException

Test if character parameter has expected value.

Parameters:

parameter - invocation character parameter,

expected - expected value,

name - the name of invocation parameter.

Throws:

IllegalArgumentException - if parameter has not expected value.

GT

public static void GT(long parameter,
                      long value,
                      String name)
               throws IllegalArgumentException

Test if numeric parameter is strictly greater than given threshold value.

Parameters:

parameter - invocation numeric parameter,

value - threshold value,

name - the name of invocation parameter.

Throws:

IllegalArgumentException - if parameter is not greater than threshold value.

GT

public static void GT(double parameter,
                      double value,
                      String name)
               throws IllegalArgumentException

Test if numeric parameter is strictly greater than given threshold value.

Parameters:

parameter - invocation numeric parameter,

value - threshold value,

name - the name of invocation parameter.

Throws:

IllegalArgumentException - if parameter is not greater than threshold value.

GT

public static void GT(char parameter,
                      char expected,
                      String name)
               throws IllegalArgumentException

Test if character parameter is strictly greater than given character value.

Parameters:

parameter - invocation character parameter,

expected - expected character value,

name - the name of invocation parameter.

Throws:

IllegalArgumentException - if parameter is not greater than threshold character.

GTE

public static void GTE(long parameter,
                       long value,
                       String name)
                throws IllegalArgumentException

Test if numeric parameter is greater than or equal to given threshold value.

Parameters:

parameter - invocation numeric parameter,

value - threshold value,

name - the name of invocation parameter.

Throws:

IllegalArgumentException - if parameter is not greater than or equal to threshold value.

GTE

public static void GTE(double parameter,
                       double value,
                       String name)
                throws IllegalArgumentException

Test if numeric parameter is greater than or equal to given threshold value.

Parameters:

parameter - invocation numeric parameter,

value - threshold value,

name - the name of invocation parameter.

Throws:

IllegalArgumentException - if parameter is not greater than or equal to threshold value.

GTE

public static void GTE(char parameter,
                       char value,
                       String name)
                throws IllegalArgumentException

Test if character parameter is greater than or equal to given character value.

Parameters:

parameter - invocation numeric parameter,

value - character value,

name - the name of invocation parameter.

Throws:

IllegalArgumentException - if parameter is not greater than or equal to character value.

LT

public static void LT(long parameter,
                      long value,
                      String name)
               throws IllegalArgumentException

Test if numeric parameter is strictly less than given threshold value.

Parameters:

parameter - invocation numeric parameter,

value - threshold value,

name - the name of invocation parameter.

Throws:

IllegalArgumentException - if parameter is not less than threshold value.

LT

public static void LT(double parameter,
                      double value,
                      String name)
               throws IllegalArgumentException

Test if numeric parameter is strictly less than given threshold value.

Parameters:

parameter - invocation numeric parameter,

value - threshold value,

name - the name of invocation parameter.

Throws:

IllegalArgumentException - if parameter is not less than threshold value.

LT

public static void LT(char parameter,
                      char value,
                      String name)
               throws IllegalArgumentException

Test if character parameter is strictly less than given character value.

Parameters:

parameter - invocation character parameter,

value - threshold value,

name - the name of invocation parameter.

Throws:

IllegalArgumentException - if parameter is not less than character value.

LTE

public static void LTE(long parameter,
                       long value,
                       String name)
                throws IllegalArgumentException

Test if numeric parameter is less than or equal to given threshold value.

Parameters:

parameter - invocation numeric parameter,

value - threshold value,

name - the name of invocation parameter.

Throws:

IllegalArgumentException - if parameter is not less than or equal to threshold value.

LTE

public static void LTE(double parameter,
                       double value,
                       String name)
                throws IllegalArgumentException

Test if numeric parameter is less than or equal to given threshold value.

Parameters:

parameter - invocation numeric parameter,

value - threshold value,

name - the name of invocation parameter.

Throws:

IllegalArgumentException - if parameter is not less than or equal to threshold value.

LTE

public static void LTE(char parameter,
                       char value,
                       String name)
                throws IllegalArgumentException

Test if character parameter is less than or equal to given threshold value.

Parameters:

parameter - invocation numeric parameter,

value - character value,

name - the name of invocation parameter.

Throws:

IllegalArgumentException - if parameter is not less than or equal to character value.

isTrue

public static void isTrue(boolean condition,
                          String message,
                          Object... args)
                   throws IllegalArgumentException

Test if given boolean condition is true and throw exception if not. Exception message is that supplied by message parameter. Message can be formatted as supported by String.format(String, Object...).

Parameters:

condition - boolean condition to test,

message - exception message,

args - optional arguments if message is formatted.

Throws:

IllegalArgumentException - if given condition is false.

isFalse

public static void isFalse(boolean condition,
                           String message,
                           Object... args)
                    throws IllegalArgumentException

Test if given boolean condition is false and throw exception if not. Exception message is that supplied by message parameter. Message can be formatted as supported by String.format(String, Object...).

Parameters:

condition - boolean condition to test,

message - exception message,

args - optional arguments if message is formatted.

Throws:

IllegalArgumentException - if given condition is true.

isKindOf

public static void isKindOf(Type parameter,
                            Type typeToMatch,
                            String name)

Test if parameter is of requested type and throw exception if not.

Parameters:

parameter - invocation parameter,

typeToMatch - type to match,

name - the name of invocation parameter.

Throws:

IllegalArgumentException - if parameter is not of requested type.