API

API

Result

class val::Result

Feedback for an individual validation rule.

An immutable value object representing one unit of feedback resulting from the evaluation of a Check against provided input. Will be aggregated into a ResultMap.

The feedback provided by this class is focused on a discrete input value and the constraints affecting that value, while the containing ResultMap contextualizes this information. In other words this class doesn’t indicate for which field the error occurred or any similar path within the input graph, that information is provided by the ResultMap.

The two fields (code and message) provided by this class are intended to provide complementary feedback:

  • code represents feedback which is more readily acted upon by any consuming code. The standard use is to indicate the type of error out of a defined set of possibilities; this would allow client code error handling to branch based on the item without requiring additional parsing.
  • message provides any information needed to resolve the specific issues encountered; this could include information based on any actual parameters affecting evaluation.

With the above conventional uses, code could inform initial dispatching of error handling code and message could be used for more refined logic or to provide feedback to the user.

The descriptions above and CODE constants provided below are conventional only and do not have any logical significance: replace or abandon at will. Additionally “field” is used in the general sense throughout rather than with the programming/Java connotations.

Public Functions

String val.Result.getMessage()

Return
Human readable information about this result.

String val.Result.getCode()

Return
Terse, machine-friendly information about this result

Public Static Functions

static Result val.Result.from(String message, String code)

Return a Result instance with the provided message and code.

Return
Result instance with provided values.
Parameters
  • message: Human readable information about this result.
  • code: Terse, machine-friendly information about this result.
Exceptions
  • NullPointerException: if either property is null.

Public Static Attributes

final String val.Result.CODE_ILLEGAL_VALUE = “ILLEGAL_VALUE”

The value provided violates a defined constraint.

final String val.Result.CODE_ILLEGAL_FIELD = “ILLEGAL_FIELD”

The value provided is targetting a field which is not supported.

final String val.Result.CODE_REQUIRED_FIELD = “REQUIRED_FIELD”

A value has not been provided for a field which requires a value.

final String val.Result.CODE_TOO_SHORT = “TOO_SHORT”

The value provided is shorter than the minimum allowed length.

final String val.Result.CODE_TOO_LONG = “TOO_LONG”

The value provided is longer than the maximum allowed length.

ResultMap

class val::ResultMap

An immutable value object which conveys the result of an evaluation of a Check against a provided input.

This is represented as a Map where the key defines the context for specific feedback and the value is a Result object providing that feedback. In conventional use the key will be the field or complete path to a field for which the Result applies.

If the map is empty then the checks have nothing to say (everything passed) and the ResultMap is considered clean.

Public Functions

abstract boolean val.ResultMap.isClean()

Whether the evaluation which created this ResultMap warranted no feedback.

Return
true if the ResultMap contains no feedback, false otherwise.

Map<String, List<Result> > val.ResultMap.asMap()

Return a read-only representation of this ResultMap as a Map.

Note read-only above. Modifying the data within the returned map is not supported (and will result in an exception). A (deep) copy should be made if any modifications are desired.

Return
A Map containing the entries within this ResultMap.

Public Static Functions

static ResultMap val.ResultMap.from(Map< String, List< Result >> map)

Return a ResultMap containing the entries in the provided Map.

This is the standard way of creating a ResultMap.

Return
A ResultMap with the entries provided.
Parameters
  • map: A Map with entries where the keys are context and the values are the list of Results.
Exceptions
  • NullPointerException: if map is null.

static ResultMap val.ResultMap.from(String key, List< Result > results)

Return a ResultMap containing one entry with the provided key and results.

Return
A single key ResultMap containing the provided entry.
Parameters
  • key: The String key for the entry in the ResultMap.
  • results: The list of Results to associate with the provided key.
Exceptions
  • NullPointerException: if either argument is null.

Indices and tables