Package org.eclipse.ditto.json
Interface JsonFieldDefinition<T>
public interface JsonFieldDefinition<T>
A
JsonFieldDefinition
is a formal description of a single JsonField
. A JSON field consists of a key
(or name) and a value. A JsonFieldDefinition differs in the way that it consists not only of a simple JSON key but
its super type JsonPointer
. With the help of this interface one can explicitly define a schema of a JSON
document including all sub documents.
The following example shows how a JSON document would be described with the help of JsonFieldDefinition.
{ "thingId": "myThing", "attributes": { "someAttr": { "subsel": 42 }, "anotherAttr": "baz" } }
Within an according class the structure of this JSON document could be described as follows:
import static JsonFactory.newIntFieldDefinition; import static JsonFactory.newStringFieldDefinition; ... public final class Thing { private static final JsonFieldDefinition THING_ID = newStringFieldDefinition("thingId"); private static final JsonFieldDefinition SUBSEL = newIntFieldDefinition("attributes/someAttr/subsel"); private static final JsonFieldDefinition ANOTHER_ATTR = newStringFieldDefinition("attributes/anotherAttr"); ... }
In this case attributes
and someAttr
are implicitly defined with the value type JsonObject
.
Additionally, a JSON field definition can be marked with zero to n JsonFieldMarker
s. The semantics of a
marker is defined by you rather than Ditto JSON. One possible usage scenario would be to define the fields which
belong to a particular schema version with a maker according to that version.
Implementations of this interface are required to be immutable!
-
Method Summary
Modifier and TypeMethodDescriptionReturns an unordered and unmodifiable set of markers which provide this field with semantics, e.g.Returns the JSON pointer which refers to this field.Returns the type of the value of this field.boolean
isMarkedAs
(JsonFieldMarker fieldMarker, JsonFieldMarker... furtherFieldMarkers) Indicates whether this definition is marked with at least all specified markers.Maps the specified JsonValue to the value type of this field definition.static JsonFieldDefinition<Boolean>
ofBoolean
(CharSequence pointer, JsonFieldMarker... markers) Returns a new JSON field definition for aboolean
value.static JsonFieldDefinition<Double>
ofDouble
(CharSequence pointer, JsonFieldMarker... markers) Returns a new JSON field definition for adouble
value.static JsonFieldDefinition<Integer>
ofInt
(CharSequence pointer, JsonFieldMarker... markers) Returns a new JSON field definition for anint
value.static JsonFieldDefinition<JsonArray>
ofJsonArray
(CharSequence pointer, JsonFieldMarker... markers) Returns a new JSON field definition for aJsonArray
value.static JsonFieldDefinition<JsonObject>
ofJsonObject
(CharSequence pointer, JsonFieldMarker... markers) Returns a new JSON field definition for aJsonObject
value.static JsonFieldDefinition<JsonValue>
ofJsonValue
(CharSequence pointer, JsonFieldMarker... markers) Returns a new JSON field definition for aJsonValue
value.static JsonFieldDefinition<Long>
ofLong
(CharSequence pointer, JsonFieldMarker... markers) Returns a new JSON field definition for along
value.static JsonFieldDefinition<String>
ofString
(CharSequence pointer, JsonFieldMarker... markers) Returns a new JSON field definition for a String value.
-
Method Details
-
ofString
Returns a new JSON field definition for a String value.- Parameters:
pointer
- a character sequence consisting of either a single JSON key or a slash delimited hierarchy of JSON keys aka JSON pointer.markers
- an optional array of markers which add user defined semantics to the defined JSON field.- Returns:
- the new JSON field definition.
- Throws:
NullPointerException
- ifpointer
isnull
.IllegalArgumentException
- ifpointer
is empty.- See Also:
-
ofInt
Returns a new JSON field definition for anint
value.- Parameters:
pointer
- a character sequence consisting of either a single JSON key or a slash delimited hierarchy of JSON keys aka JSON pointer.markers
- an optional array of markers which add user defined semantics to the defined JSON field.- Returns:
- the new JSON field definition.
- Throws:
NullPointerException
- ifpointer
isnull
.IllegalArgumentException
- ifpointer
is empty.- See Also:
-
ofLong
Returns a new JSON field definition for along
value.- Parameters:
pointer
- a character sequence consisting of either a single JSON key or a slash delimited hierarchy of JSON keys aka JSON pointer.markers
- an optional array of markers which add user defined semantics to the defined JSON field.- Returns:
- the new JSON field definition.
- Throws:
NullPointerException
- ifpointer
isnull
.IllegalArgumentException
- ifpointer
is empty.- See Also:
-
ofDouble
Returns a new JSON field definition for adouble
value.- Parameters:
pointer
- a character sequence consisting of either a single JSON key or a slash delimited hierarchy of JSON keys aka JSON pointer.markers
- an optional array of markers which add user defined semantics to the defined JSON field.- Returns:
- the new JSON field definition.
- Throws:
NullPointerException
- ifpointer
isnull
.IllegalArgumentException
- ifpointer
is empty.- See Also:
-
ofBoolean
Returns a new JSON field definition for aboolean
value.- Parameters:
pointer
- a character sequence consisting of either a single JSON key or a slash delimited hierarchy of JSON keys aka JSON pointer.markers
- an optional array of markers which add user defined semantics to the defined JSON field.- Returns:
- the new JSON field definition.
- Throws:
NullPointerException
- ifpointer
isnull
.IllegalArgumentException
- ifpointer
is empty.- See Also:
-
ofJsonObject
static JsonFieldDefinition<JsonObject> ofJsonObject(CharSequence pointer, JsonFieldMarker... markers) Returns a new JSON field definition for aJsonObject
value.- Parameters:
pointer
- a character sequence consisting of either a single JSON key or a slash delimited hierarchy of JSON keys aka JSON pointer.markers
- an optional array of markers which add user defined semantics to the defined JSON field.- Returns:
- the new JSON field definition.
- Throws:
NullPointerException
- ifpointer
isnull
.IllegalArgumentException
- ifpointer
is empty.- See Also:
-
ofJsonArray
Returns a new JSON field definition for aJsonArray
value.- Parameters:
pointer
- a character sequence consisting of either a single JSON key or a slash delimited hierarchy of JSON keys aka JSON pointer.markers
- an optional array of markers which add user defined semantics to the defined JSON field.- Returns:
- the new JSON field definition.
- Throws:
NullPointerException
- ifpointer
isnull
.IllegalArgumentException
- ifpointer
is empty.- See Also:
-
ofJsonValue
Returns a new JSON field definition for aJsonValue
value.- Parameters:
pointer
- a character sequence consisting of either a single JSON key or a slash delimited hierarchy of JSON keys aka JSON pointer.markers
- an optional array of markers which add user defined semantics to the defined JSON field.- Returns:
- the new JSON field definition.
- Throws:
NullPointerException
- ifpointer
isnull
.IllegalArgumentException
- ifpointer
is empty.- See Also:
-
getPointer
JsonPointer getPointer()Returns the JSON pointer which refers to this field.- Returns:
- the JSON pointer to this field.
-
getValueType
Returns the type of the value of this field.- Returns:
- the value type of this field.
-
getMarkers
Set<JsonFieldMarker> getMarkers()Returns an unordered and unmodifiable set of markers which provide this field with semantics, e.g. schema version number.- Returns:
- the markers of this field or an empty set.
-
isMarkedAs
Indicates whether this definition is marked with at least all specified markers.- Parameters:
fieldMarker
- the mandatory fieldMarker to check this definition for.furtherFieldMarkers
- additional markers to check this definition for.- Returns:
- true if this definition is marked with at least all specified markers,
false
else. - Throws:
NullPointerException
- if any argument isnull
.
-
mapValue
Maps the specified JsonValue to the value type of this field definition. If the JsonValue cannot be mapped aJsonParseException
is thrown.- Parameters:
jsonValue
- the JsonValue to be mapped.- Returns:
- the JsonValue as the Java type of this field definition.
- Throws:
NullPointerException
- ifjsonValue
isnull
.JsonParseException
- ifjsonValue
does not represent this definition's expected Java type.- See Also:
-