Core: the REST API of documents
This document describes the code in linked-data-store-core that answers REST requests for documents: how a
request path becomes a resource, the three handlers, schema validation and the
reading of a request body. It is for developers and maintainers who change that code. What a user of the API needs
is in the REST API.
What this part is for
A REST request names a document, a part of a document, or a link from a document. This part finds out which of the three it is, reads what is stored, and for a write builds the whole new document, validates it and hands it to a saga. It does not store anything itself. Storing is done by the saga (the write path).
The packages are io.descoped.lds.core.domain and io.descoped.lds.core.validation. The module does not export
them (module-info.java exports io.descoped.lds.core and io.descoped.lds.test.server only).
Layout
| Class | Responsibility |
|---|---|
DataController (core.controller) |
The way in. Moves the request to a worker thread, reads the time of the request, builds the ResourceContext and picks the handler. |
ResourceContext (domain.resource) |
The request path, checked against the model: the namespace, a chain of ResourceElement and the time. Says which kind of resource the path is. Also walks a document along the chain (subTree, referenceToExists, navigateAndCreateJson). |
ResourceElement (domain.resource) |
One step of the path: the name, the element of the specification it is, an id (of the document for the first step, the link /Entity/id for the last step of a reference) and the next step. |
ResourceException (domain.resource) |
A path that the model does not have. Its message is the body of the 400 answer. |
ManagedResourceHandler (domain.managed) |
The whole document: read one, read all of an entity type, read the versions, write, delete, and give out the JSON Schema of the entity type. |
EmbeddedResourceHandler (domain.embedded) |
A part of a document: read it, replace it, remove it. |
ReferenceResourceHandler (domain.reference) |
One link of a document: ask whether it is there, add it, remove it. |
ReferenceJsonHelper (domain.reference) |
Puts a link into a document and takes it out, for a single link and for an array of links. |
BodyParser (domain) |
Reads the body of a request into a Jackson tree, by the content type. |
ResourceJsonTraversalTuple (domain.resource) |
The last step of a path and the object of the document that holds it, as navigateAndCreateJson gives them to its caller. |
LinkedDocumentValidator (validation) |
Says whether a document may be written: the JSON Schema of the entity type, then the links. It throws LinkedDocumentValidationException. |
A new handler and a new ResourceContext are made for every request. They hold no state between requests.
From a request to a resource
The way in
UndertowApplication puts NamespaceController on the path /, behind the exact paths /ping,
/health/alive and /health/ready, and behind /graphql and /graphiql when graphql.enabled is true and
graphql.schema is not empty. Without a GraphQL schema those two paths reach NamespaceController and are
answered as a namespace that is not served. NamespaceController looks at the path, in this order:
- A path of one character or less is answered 404 with no body.
- The path is exactly the namespace and the first value of
schemais blank (/<namespace>?schema): the list of the addresses of the schemas is answered there. - The path is exactly the namespace and one value of
schemaisembed: the schemas themselves are answered there. Both are answered for every method, and not for/<namespace>/?schema. - A path that is the namespace, or starts with it and a
/, goes to a newDataController. - A path that starts with
/source/goes toSourceHandler(the transaction log, not this part). - Anything else is answered 400 with
Unsupported namespace: "<first segment>".
CORSHandler is in front of all of this (the application). An OPTIONS request with
the headers Origin and Access-Control-Request-Method is answered 204 by it and does not reach this part.
The namespace is the value of namespace.default. REST serves this one namespace. ResourceContext takes the
namespace from the path and gives it to the store with every read and write.
DataController.handleRequest first calls exchange.dispatch(this) when it is on an I/O thread. Everything after
that runs on a worker thread of Undertow, and the handlers block on it: blockingGet and blockingIterable on
the reads, join on the saga.
NamespaceController and DataController read the path with exchange.getRelativePath(), so a value of
http.prefix is not part of the path that is checked.
The time of the request
DataController reads the time before anything else:
- The parameter
timestamp. When the request has notimestamp, the parametert. The names are in lower case. When the parameter is given more than once, the last value is used. - No parameter: the time is now,
ZonedDateTime.now(ZoneId.of("Etc/UTC")). - The value is read with
ZonedDateTime.parse, which needs a date, the hour and the minute, and an offset orZ(2018-12-06T11:05:31.000+01:00). Seconds may be left out. A zone in brackets after the offset is accepted. When that fails, the value is decoded as a URL once and read again. - When both fail the answer is 400 with a fixed text (see Where an error answer comes
from). A parameter with no value (
?timestamp=,?timestamp) fails too. - The time is moved to UTC with
withZoneSameInstant(ZoneId.of("Etc/UTC")).
This one time is used for the whole request. A read is an as-of read: it gives the
document as it is at that time. A write makes the version whose
valid time is that time. So a write without timestamp makes a version valid from
the moment the request arrived, and a write with a timestamp in the past or the future makes a version there.
The path
ResourceContext.createResourceContext(specification, path, timestamp) splits the path at / with
String.split, which drops empty segments at the end, so a / at the end of a path is ignored. Every segment
is decoded as a URL (urlDecode). The path is /{namespace}/{Entity}/{id}/{field}/.../{Entity}/{id}:
- Fewer than two segments:
ResourceException. - The second segment must be an entity type of the model (a property of the root
element of the specification,
Specification). - The third segment, when there is one, is the id. An id that is empty or only spaces is refused.
- Every segment after the id must be a property of the element before it in the specification
(
navigateSpecAndCreateResourceContext). - When a segment is a link field (
SpecificationElementType.REF):- nothing after it: the path ends at the field, which is an embedded resource whose value is the link or links;
- one segment after it: refused, an id is missing;
- two segments after it: the entity type and the id of the target. The entity type must be one the field may
link to (
getRefTypes). The lastResourceElementgets the id/Entity/id; - more than two: refused, a path does not go through a link.
The result is a chain of ResourceElement. getResourceType reads the kind from it:
| Kind | The chain | Example |
|---|---|---|
MANAGED |
Only the first element. The id may be missing (all documents of the entity type). | /ns/Person/ola, /ns/Person |
EMBEDDED |
More elements, and the last has no id. | /ns/Person/ola/address |
REFERENCE |
More elements, and the last has an id. | /ns/Person/ola/employer/Company/acme |
DataController asks isReference() first, then isManaged(), then isEmbedded(), and makes the handler.
DataController ends with a 404 and the text Unsupported resource path: <path>. No request gets there:
every ResourceContext is one of the three kinds.
The names in the path are checked against the model, and only names of the model pass. The id is not checked
beyond being non-empty. It is given to the store as a value. The id of the target of a reference is not checked
at all: /ns/Person/ola/employer/Company/%20 is the link /Company/ followed by a space.
DataController catches ResourceException and nothing else. URLDecoder.decode throws
IllegalArgumentException for a % that two hexadecimal digits do not follow, so such a segment is answered 500
(see Not finished).
The handlers
Each handler looks at the method. GET, PUT, POST and DELETE are answered. PUT and POST run the same code. Any
other method, HEAD and OPTIONS included, is answered 400 with Unsupported managed resource method: <METHOD>
(or embedded, or reference). An OPTIONS request that is a CORS preflight does not get this far (see above).
The examples below were run against LDS in memory with the example model
(linked-data-store-server/schemas/schema.graphql), started on port 19108. Headers are left out except where
they matter.
Managed: the whole document
| Request | What happens | Answer |
|---|---|---|
GET, no id, ?schema |
SchemaRepository.getJsonSchema().getSchemaJson(entity) |
200, the JSON Schema of the entity |
| GET, no id | readDocuments at the time, unbounded. Deleted documents are left out. |
200, an array of documents, [] when there are none |
GET, id, ?timeline |
readDocumentVersions, unbounded. The time of the request is not used. |
200, an array of {"version": ..., "document": ...}, oldest first; 404 when there is no version |
| GET, id | readDocument at the time |
200, the document; 404 when there is none at that time or it is deleted |
| PUT or POST | See A write becomes a saga. The body is the whole document. | 201 {"saga-execution-id":"..."} |
| DELETE | The saga Delete managed resource. The store marks the document deleted from the time. |
204 when the saga was awaited, else 202 {"saga-execution-id":"..."} |
version in the timeline is ZonedDateTime.toString() of the UTC time:
2020-01-01T00:00Z[Etc/UTC]. timeline and schema are looked for as names only (containsKey);
?timeline=false gives the timeline too. schema is looked at only when the path has no id.
putManaged checks in this order: an empty body (400 Payload was empty!), a missing id (400 Id was empty!),
then BodyParser, then the validator. Only a body of no characters is empty. For a body of spaces Jackson gives a
missing node, and the validator answers [$: unknown found, object expected].
curl -i -X PUT 'http://localhost:19108/ns/Person/ola?sync=true×tamp=2020-01-01T00:00:00Z' \
-H 'Content-Type: application/json' \
-d '{
"name": "Ola",
"employer": "/Company/acme"
}'HTTP/1.1 201 Created
Content-Type: application/json
{"saga-execution-id": "01a1f996-a2fa-70bc-9813-014051609244"}curl -i 'http://localhost:19108/ns/Person/ola?timestamp=2021-06-01T00:00:00Z'HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"employer": "/Company/acme",
"name": "Ola"
}A DELETE does not look for the document first. A DELETE of a document that does not exist is answered 204 as
well, and the store gets a deleted version, a tombstone, at that time. With the memory
provider the timeline shows a tombstone as {"version":"2020-01-01T00:00Z[Etc/UTC]","document":{}}.
Embedded: a part of a document
All three methods first read the document at the time of the request. When there is none, or it is deleted, the answer is 404 with no body. For a PUT that is before the body is parsed, so a body that cannot be read is answered 404 when there is no document.
| Method | What happens | Answer |
|---|---|---|
| GET | ResourceContext.subTree walks the document along the chain. |
200. An object or an array as it is. A simple value inside an array: ["Ola"]. A part the document does not have: [null]. |
| PUT or POST | The body is the new value of the part. mergeJson sets it in the document; navigateAndCreateJson makes the objects on the way that the document does not have. The whole document is validated, then written with the saga Create or update managed resource. |
200 {"saga-execution-id":"..."}; 400 when the document is not valid; 404 |
| DELETE | The field is removed from the document and the document is written. It is not validated. | 200 {"saga-execution-id":"..."}; 404 |
The body null is a value: where the schema allows it, the field is set to null
(PUT /ns/Person/ola/address with null gave "address":null with the example model).
curl -i 'http://localhost:19108/ns/Person/ola/name'HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
["Ola"]curl -i -X PUT 'http://localhost:19108/ns/Person/ola/born?sync=true×tamp=2022-01-01T00:00:00Z' \
-H 'Content-Type: application/json' -d '"1990-05-17T00:00:00Z"'HTTP/1.1 200 OK
Content-Type: application/json
{"saga-execution-id": "01a1f996-a32c-7800-b3c6-e4fc44007c40"}A write to a part makes a new version of the whole document, valid from the time of the request. It is built from the document as it is at that time (an as-of read), not from the newest version.
Reference: one link
| Method | What happens | Answer |
|---|---|---|
| GET | ResourceContext.referenceToExists: the field holds the link, or the array of the field has it. |
200 when the link is there; 404 when it is not, or there is no document. No body. |
| PUT or POST | 404 when there is no document at the time. When the link is there, nothing is written. Else ReferenceJsonHelper.createReferenceJson: an array field gets the link added, a single field gets it as its value, in place of the link it had. Then the saga Create or update managed resource. The body of the request is read and not used. |
200 with no body when the link was there; 200 {"saga-execution-id":"..."} when it was written; 404 |
| DELETE | When there is no document, or the link is not there, nothing is written. Else ReferenceJsonHelper.deleteReferenceJson: the first equal element is taken out of the array, or the single field is removed. Then the same saga. |
200 always. No body when nothing was written or the saga was awaited, else {"saga-execution-id":"..."}. |
The document is not validated after a link is added or removed. The path was checked against the model, so the
link is to an entity type the field may link to. navigateAndCreateJson makes the objects on the way to the field
that the document does not have. An array that becomes empty stays in the document as [].
curl -i -X PUT 'http://localhost:19108/ns/Person/ola/friends/Person/kari?sync=true×tamp=2023-01-01T00:00:00Z'HTTP/1.1 200 OK
Content-Type: application/json
{"saga-execution-id": "01a1f996-a33a-72cc-8a99-78d0a8d4c231"}curl -i 'http://localhost:19108/ns/Person/ola?timeline'[
{
"version": "2020-01-01T00:00Z[Etc/UTC]",
"document": {"employer": "/Company/acme", "name": "Ola"}
},
{
"version": "2022-01-01T00:00Z[Etc/UTC]",
"document": {
"born": "1990-05-17T00:00:00Z",
"employer": "/Company/acme",
"name": "Ola"
}
},
{
"version": "2023-01-01T00:00Z[Etc/UTC]",
"document": {
"born": "1990-05-17T00:00:00Z",
"employer": "/Company/acme",
"name": "Ola",
"friends": ["/Person/kari"]
}
}
]The answer is one line; it is broken here to be read. There is no document Person/kari in this LDS. A link may
point at a document that does not exist (a dangling reference), and no handler looks for the target.
A write becomes a saga
Every write ends the same way, in all three handlers:
- The handler has the whole document as a Jackson tree. For a managed PUT it is the body. For the others it is the stored document with the change made in it.
syncis read from the query (see below).- The saga is taken from
SagaRepositoryby name:SAGA_CREATE_OR_UPDATE_MANAGED_RESOURCE, orSAGA_DELETE_MANAGED_RESOURCEfor the DELETE of a whole document. - A
SagaInputis made: a new transaction id (SagaExecutionCoordinator.generateTxId, a UUIDv7), the method (PUTorDELETE), the namespace, the entity type, the id, the time as the version (its valid time),sourceandsourceIdfrom the query when given, and the document. A DELETE has no document. SagaExecutionCoordinator.handoff(sync, ...)starts the saga and gives a future. The handler callsjoinon it and then answers.saga-execution-idin the answer is the transaction id.
When the handler passes true as sync, the future is the completion of the saga: the answer comes when the
transaction log, the store and, when there is one, the search index have been written. This is a
synchronous write: a read that follows it sees the write (read-your-writes).
With false the future is the hand-off: the answer comes when the saga is written to its
saga log, and the saga goes on after the answer, so a read that follows at once may not
see the write yet (eventual consistency). A saga that fails after that is not seen by the client; it is logged by
SagasObserver.
sync is not read the same way everywhere:
| Handler | The saga is awaited when |
|---|---|
ManagedResourceHandler (PUT, POST, DELETE) |
no value of sync is false (any case). So also when sync is not given. |
EmbeddedResourceHandler, ReferenceResourceHandler |
a value of sync is true (any case). So not when sync is not given, and not for ?sync with no value. |
The query parameter saga is given to SagaCommands.getSagaAdminParameterCommands. It makes a step of the saga
fail, and is used only when saga.commands.enabled is true (the write path).
When the saga fails while the handler waits, join throws. No handler catches it. Undertow logs
UT005071: Undertow request failed and answers 500 with no body. The 500 does not say how far the saga came:
with saga=failAfter persistence the answer was 500 and the document was in the store.
No handler holds a lock between its read and its write. A write to a part or to a link reads the document, changes it and writes the whole document as a new version, so two such writes to one document at the same time each start from the document without the change of the other (see Not finished).
A write with the same id and the same valid time as a version that exists replaces that version. That is what makes a
repeated PUT with a timestamp safe.
Validation
LinkedDocumentValidator.validate(entity, document) is called by the managed PUT and the embedded PUT, on the
whole document. It throws LinkedDocumentValidationException, and the handler answers 400 with
Schema validation error: and the message.
It checks two things, in this order:
- The JSON Schema of the entity type (
JsonSchema.validate, oncom.networknt:json-schema-validator).formatis checked, so a text in adate-timefield must be a date-time of RFC 3339. Everything that is wrong is collected. The message is the list as Java prints it:[$.name: integer found, string expected]. - The links. The specification of the entity type is walked (
SpecificationTraversal). For every link field the value is looked up in the document. A field that is missing or null is not checked, and neither is a null in an array of links, nor a field whose parent in the document is missing or is not an object. The schema is checked first, so a null gets this far only where the schema allows it. The schema LDS writes from a GraphQL schema says"type":"string"for a link, and a null there is answered[$.employer: null found, string expected]. A value that is not a text is checked as its JSON text. A value must be a/, an entity type, a/and an id, with no other/in it (linkPattern), or the message isNot a valid link. Navigation: <path>: "<value>". The entity type in it must be one the field may link to, or the message isIllegal linked-domain: "<entity>". Navigation: <path>: "<value>". The first link that is wrong ends the check.
The validator does not look for the document a link points at. That is on purpose: LDS keeps versions with a valid time in the past and the future, and a link may point at a document that is written later.
curl -i -X PUT 'http://localhost:19108/ns/Person/per?sync=true' \
-H 'Content-Type: application/json' \
-d '{
"name": "Per",
"employer": "/Person/ola"
}'HTTP/1.1 400 Bad Request
Content-Type: text/plain
Schema validation error: Illegal linked-domain: "Person". Navigation: employer: "/Person/ola"The schema the validator uses, and the specification it walks, are built at start from the model (the model).
The body of a request
The handlers read the body with receiveFullString(..., StandardCharsets.UTF_8), so the body is a text when it
reaches BodyParser.deserializeBody(contentType, body). The content type is the first Content-Type header, or
application/json when the request has none. Apache Tika parses it (MediaType.parse), so parameters such as
; charset=utf-8 and the case of the letters do not matter.
application/json: read with Jackson 3. A text with something after the document is refused. A text of no characters or of only spaces is not refused:readTreegives a missing node.application/msgpack,application/x-msgpack: handed to aMessagePackMapper.- Any other type:
IllegalArgumentException("Unsupported Content-Type: ..."). - A value that is no media type (
Content-Type: garbage):MediaType.parsegives null and the next line throwsNullPointerException.
The body is always read as UTF-8. A charset in the header changes nothing.
A JacksonException is wrapped in a RuntimeException. No handler catches what BodyParser throws, so the
answer is 500 with no body (see Not finished).
Answers are JSON. The handlers do not read the Accept header.
Where an error answer comes from
| Status | Body | From |
|---|---|---|
| 400 | Unsupported namespace: "<first segment>" |
NamespaceController |
| 400 | The 'timestamp' query-parameter must follow the ISO-8601 standard. Example of a valid formatted timestamp is '2018-12-06T11:05:31.000+01:00' |
DataController |
| 400 | Not a valid resource. The resource path must contain at least namespace, name, and id of managed resource |
ResourceContext, fewer than two segments |
| 400 | Not a managed resource name: "<name>" |
ResourceContext |
| 400 | Managed resource id cannot be empty. |
ResourceContext, an id that is empty or only spaces |
| 400 | Not a valid path element: "<name>" |
ResourceContext |
| 400 | Reference resource path-element: "<field>" must be part of pattern ending like: "/<field>/<managed-domain>/<id>" |
ResourceContext |
| 400 | Resource path cannot navigate through REF property: "<field>" |
ResourceContext |
| 400 | Reference resource does not support link to managed-domain "<entity>". Must be one of: [<entities>] |
ResourceContext |
| 400 | Payload was empty! |
ManagedResourceHandler, PUT with an empty body |
| 400 | Id was empty! |
ManagedResourceHandler, PUT or DELETE without an id |
| 400 | Schema validation error: <message> |
the managed and the embedded PUT |
| 400 | Unsupported <kind> resource method: <METHOD> |
each handler |
| 404 | none | no document, no version, no link; a path of one character or less (NamespaceController) |
| 500 | none | an exception that no handler catches: a body that cannot be read, a content type that is not known, a saga that fails while the handler waits, a path segment with a % that cannot be decoded |
The 400 answers are text/plain. The managed handler sets Content-Type: application/json; charset=utf-8
before it reads, so its 404 has that header and no body.
Rules to keep
- Time is UTC.
DataControllermoves the time of the request to UTC before anything uses it. Versions are stored and compared as UTC instants (see the invariants). - Names come from the model. The entity type, every field of the path and the entity type of a link are
looked up in the
Specification. Keep it so: no name from a request reaches a store without that check. - A handler does not write to the store. It reads with
persistence.createTransaction(true)in a try-with-resources block, and writes through a saga. A write that skips the saga skips the transaction log and the search index. - A handler blocks on a worker thread only. Keep the
dispatchinDataController. The handlers wait for the reactive persistence interface (reactive streams) where they use it; no blocking method and no method that returns a complete list is added to that interface to make a handler shorter. - No check that a link target exists. Do not add one to the validator or to a handler.
- Every call can be sent again. A PUT of a link that is there writes nothing. A DELETE of a link or of a
document that is not there is answered as a success. A PUT with a
timestampreplaces the version at that time. A write withouttimestampthat is sent again makes one more version, at the time of the second request. - A text is taken out of a node with
JsonTools.textunless the node is known to be a text. It gives null for a node of another kind, where Jackson 3 itself throws. - The error texts are part of the API. Tests compare them letter by letter:
DataControllerTest,NamespaceControllerTest,ManagedResourceHandlerTest,DocumentValidationTest. - The answer of the validator keeps its form: the place in the document as LDS writes a path, then the message
of the validator (
$.tags[1]: integer found, string expected). - Lint. Core overrides
-Xlint:alland doclint in itspom.xmlwith the categories its older code is not clean of. The override is removed, not widened (see the invariants).
Configuration
The handlers read no configuration themselves. These keys decide what they are given:
| Key | Default | Meaning for this part |
|---|---|---|
namespace.default |
ns |
The namespace REST serves. A leading / is added when it is missing (NamespaceController). |
graphql.schema, specification.schema |
see the model | The model. It decides which entity types, fields and links a path may name, and what a document is validated with. |
http.prefix |
/ |
A prefix in front of every path. The handlers do not see it. |
saga.commands.enabled |
false |
Whether the query parameter saga is used. |
ManagedResourceHandler and EmbeddedResourceHandler log the method, the path and the body of a PUT at
TRACE, and a validation error at DEBUG. ManagedResourceHandler logs an empty body at ERROR.
Tests
The tests are in linked-data-store-core/src/test/java/io/descoped/lds/core.
| Test | What it holds |
|---|---|
domain/resource/ResourceContextTest |
Which kind a path is, for single links and arrays of links, at three depths; navigateAndCreateJson on an empty, a filled and a partly filled document. Its specification is built in the test (SpecificationBuilder). |
domain/resource/ResourceGraphqlContextTest |
The paths that are refused. It checks that a ResourceException is thrown, not its text. |
domain/managed/ManagedResourceHandlerTest |
PUT and GET, DELETE (204, and 400 without an id), 404, ?schema, the answer to a document that is not valid, ?timeline. |
domain/managed/ManagedTimeBasedVersioningTest |
Three versions read at five times; a timestamp that cannot be read is 400. |
domain/embedded/EmbeddedResourceHandlerTest |
GET of an array and of a missing part ([null]), PUT and DELETE of an object and an array, also two levels down. |
domain/reference/ReferenceResourceHandlerTest |
GET, PUT and DELETE of single links and links in arrays, PUT on a missing and on a deleted document (404), DELETE sent twice, a link to an entity type the field may not link to (400). |
domain/reference/ReferenceJsonHelperTest |
Adding, changing and removing a link in a document, without a server. |
domain/BodyParserTest |
JSON, JSON that is refused, another content type, and that a MessagePack body is refused. |
validation/DocumentValidationTest |
The messages of the validator, date-times that are valid and not, links, nulls where a link could be. |
validation/LinkedDocumentValidatorTest |
Links to another entity type and links of another form are refused. |
controller/DataControllerTest, controller/NamespaceControllerTest, controller/NamespaceSchemaTest |
The way in: a path the model does not have, another namespace, ?schema on the namespace. |
BodyParserTest and DocumentValidationTest are JUnit 6 with AssertJ. The others are TestNG. Those that send
requests take a server from TestServerListener: LDS in the JVM on a free port, in memory, with the namespace
data (src/test/resources/application_test.properties). The model of that server is the GraphQL schema
src/test/resources/gqlschema/schema.graphql, which has the entity types contact and provisionagreement among
others. The file also sets specification.schema to the JSON Schema files spec/schemas/contact.json and
spec/schemas/provisionagreement.json, but UndertowApplication.initializeUndertowApplication does not read
that key while graphql.schema is set. ResourceGraphqlContextTest reads the two JSON Schema files itself.
TestClient.put sends the header Origin: localhost and no Content-Type header, so those tests use the
default of the handlers. A new test class that takes its server from TestServerListener is TestNG and asserts
with AssertJ; a test added to an existing class follows that class.
Core is built and tested with the modules it needs by ./mvnw verify -pl linked-data-store-core -am, and one
test class is run with ./mvnw test -pl linked-data-store-core -Dtest=<Class>. The build needs JDK 27 and
Docker.
Not finished
Not finished: a path does not go into the elements of an array. ResourceContext, ReferenceJsonHelper and
EmbeddedResourceHandler have TODO notes about array-navigation, and ResourceJsonTraversalTuple throws
UnsupportedOperationException("array-navigation not supported") when the parent of the last step is not an
object. A part of an object that is an element of an array has no address:
/ns/Company/big/about/languageText is answered Not a valid path element: "languageText".
Not finished: with a model from a GraphQL schema, a field whose type is another object type (not a list) has no
content in the JSON Schema LDS writes: "address":{"displayName":""}. Such a field has no properties in the
specification either. So /ns/Person/ola/address/city is answered Not a valid path element: "city", the
content of address is not validated, and a link inside it is not known. The cause is where the JSON Schema is
written from the GraphQL schema, not in this part. With JSON Schema files that describe the object in place, the
same path works.
Not finished: a body that cannot be read is answered 500 with no body, not 400. The same holds for a content
type that is not JSON or MessagePack. curl -d without a Content-Type header sends
application/x-www-form-urlencoded and gets this answer.
Not finished: only the managed PUT answers Payload was empty!. The embedded PUT has no such check. An empty
body becomes a missing node that is set in the document. Where the schema gives the field a type the validator
answers 400 ([$.name: unknown found, string expected]). Where it does not (address in the example model) the
document goes to the saga, and the memory provider fails with
Type tools.jackson.databind.node.MissingNode not supported for path [$, address]: with sync=true the answer
is 500, and without it the answer is 200 with a saga-execution-id. Neither writes anything then. The saga
stays in its saga log, and recovery runs it again: in a run with the memory provider both writes were recovered
two seconds later (Recovery of saga succeeded in the log), and each document then had a new version with
"address":null.
Not finished: two writes to parts or links of one document at the same time lose changes. 20 requests
PUT /ns/Person/par/friends/Person/p<n>?sync=true sent at once were all answered 200, and the document had 12
of the 20 links afterwards in one run and 8 in another. By the same code, a write that follows a write that was
not awaited starts from the store as it is then, with or without the first write. That was not seen in a run:
20 such writes sent one after the other all came through with the memory provider.
Not finished: an id or a field name with a % that two hexadecimal digits do not follow is answered 500.
GET /ns/Person/100%25 reaches ResourceContext.urlDecode as 100%, and the IllegalArgumentException of
URLDecoder is not caught.
Not finished: a MessagePack body is never read. The body reaches BodyParser as a text, and MessagePack is not
text. BodyParserTest.aMessagePackBodyIsRefusedBecauseItIsHandedOverAsText holds this as it is.
Not finished: sync has two meanings, as shown in A write becomes a saga. A managed write
waits for the saga unless told not to; an embedded or a reference write does not wait unless told to.
Not finished: the status of a managed PUT is 201 whether or not the document existed and whether or not the saga was awaited. A reference DELETE and PUT answer 200 with or without a body.
Not finished: the embedded DELETE and the reference PUT and DELETE write the document without validating it. An
embedded DELETE of a field the schema requires is written. An embedded DELETE also writes a version when the
field was not there, and makes the objects on the way that the document does not have. With the JSON Schema
files of the tests as the model, DELETE /ns/provisionagreement/d1/address/street on a document without
address wrote a version with "address":{}, which that schema does not allow.
Not finished: the validator checks links only in objects it reaches through fields. A link field inside an
object that is an element of an array is not checked (SpecificationTraversal walks properties, not items).
With a model where Company.offices is a list of a type that has the link manager, a document with
"offices":[{"city":"Oslo","manager":"not a link"}] was written.
Not finished: a path segment is decoded twice, by Undertow and by ResourceContext.urlDecode. An id with +
becomes an id with a space, and %2541 becomes A. %2F reached ResourceContext as it was sent:
/ns/Person/a%2Fb is the id a/b. ResourceContextIntegrationTest, the only test of encoded names, is
switched off with @Ignore.
Not finished: the read of all documents of an entity type and the read of the versions are not paged. The read
of the versions has TODO Support pagination or time-range based query parameters. Both ask the store for
everything (Range.unbounded()) and build the answer in memory before it is sent.
Not finished: the form of the answer of an embedded GET depends on the value: an object or an array as it is, a
simple value in an array, [null] for nothing. The code has a TODO about one form for all.
Not finished: SagaInput has a field schema, and every handler gives it the text "TODO".
Not finished: the error callback of receiveFullString in the embedded and the reference handler sends a text
and sets no status. ResourceContext.subTree throws RuntimeException("") when the parent of the last step is
a simple value. ReferenceJsonHelper.createReferenceJson calls equals on the result of JsonTools.text, which
is null when a single link field holds something that is not a text.
Not finished: a method that is not answered gets 400, not 405, and HEAD is one of them.
Not finished: seven tests of the REST API are switched off in the source: five in DataControllerTest, one in
NamespaceControllerTest and the one in ResourceContextIntegrationTest.
Not finished: REST reaches one namespace, the one in namespace.default. The stores keep the namespace with
every document, but no request can name another.