On 04/19/2024 01:48 PM, Ross Finlayson wrote:
On 04/19/2024 11:49 AM, Ross Finlayson wrote:
On 04/19/2024 10:22 AM, Ross Finlayson wrote:
On 04/19/2024 09:30 AM, Ross Finlayson wrote:
Signature API
>
ccc.api
ccc.api.exception
ccc.api.fault
>
ccc.api.client
>
ccc.springsup.web
>
ccc.serdes
>
>
Api ApiMapping
>
ApiFlt ApiHardFlt
OtherCauseFault CovariantFault
>
Pth Hdr Qpa Req Rsp Flt Err
>
>
The other day I was writing a Spring Boot server,
and the implementation of the Api looks like this
>
For a service Srv, group of APIs Grp, and API Api
>
public interface Srv {
interface Grp {
interface Api extends ccc.api.Api {
>
static class Pth{}
static class Qpa{}
static class Hdr{}
static class Req{}
static class Rsp{}
static class Flt{}
static class Err{}
>
>
Rsp api(
@Valid @NotNull Pth pth,
@Valid @NotNull Qpa qpa,
@Valid @NotNull Hdr hdr,
@Valid @NotNull Req req
) throws ApiFlt;
>
}
}
>
}
>
The validation annotations have to be on the root type,
so, they go on the Api.
>
public interface SrvMapping {
interface Grp {
@RequestMapping
interface Api extends Srv.Grp.Api, ApiMapping {
>
@Override
@GetMapping("/api/{pth}")
@ResponseBody
Rsp api(
@PathVariable Pth pth,
@QueryParam Qpa qpa,
@RequestHeader Hdr hdr,
@RequestBody Req req
) throws ApiFlt;
>
}
}
}
>
The request mapping and also the openapi or documentation
interfaces have to be on the interface the controller implements,
and they don't mean anything to the Api, so they go on the ApiMapping.
>
@Controller
public class SrvController implements SrvMapping.Grp.Api
{
@Override
Srv.Grp.Rsp api(
Srv.Grp.Pth pth,
Srv.Grp.Qpa qpa,
Srv.Grp.Hdr hdr,
Srv.Grp.Req req
) throws ApiFlt;
}
>
The controller just implements the Api, Spring Web wires
it up and Openapi documents it up.
>
And it results sort of thusly a very simple organization of APIs.
>
public interface Srv {
>
interface Grp1 {
interface Api1 { /* */ }
interface Api2 { /* */ }
interface Api3 { /* */ }
interface Api4 { /* */ }
}
interface Grp@ {
interface Api1 { /* */ }
interface Api2 { /* */ }
interface Api3 { /* */ }
interface Api4 { /* */ }
}
/* */
}
>
The key is that given those, the Api and ApiMapping an entire
Signature, of the mapping, sort of results, with adding this
sort of ApiStatusMapping, to relate the HTTP status codes,
with, the covariant return bodies, then it's sort of all one thing.
>
("a functional interface may still have multiple default methods ...")
>
The idea is that the interfaces carry very well down from these.
>
For most often usual "APIs" these days it'd often look:
>
@Data
static class MyGrp {
>
}
>
public interface Srv {
interface Grp {
interface Get1 extends ccc.api.Api {
>
static class Pth{ String myGrpId;}
static class Req extends MyGrp{};
static class Rsp{}
static class Flt{}
static class Err{}
>
Rsp get1(
@Valid @NotNull Pth pth,
@Valid @NotNull Req req
) throws ApiFlt;
>
}
interface Put1 extends ccc.api.Api {
>
static class Pth{ String myGrpId;}
static class Req extends MyGrp{}
static class Rsp{}
static class Flt{}
static class Err{}
>
Rsp put1(
@Valid @NotNull Pth pth,
@Valid @NotNull Req req
) throws ApiFlt;
>
}
}
>
}
>
>
public interface SrvMapping {
interface Grp {
@RequestMapping
interface Api extends Srv.Grp.Get1, ApiMapping {
>
@Override
@GetMapping("/grp/{myGrpId}")
@ResponseBody
Rsp get1(
@PathVariable("myGrpId") Pth pth,
@RequestBody Req req
) throws ApiFlt;
>
}
@RequestMapping
interface Api extends Srv.Grp.Put1, ApiMapping {
>
@Override
@PutMapping("/grp/{myGrpId}")
@ResponseBody
Rsp put1(
@PathVariable("myGrpId") String myGrpId,
@RequestBody Req req
) throws ApiFlt;
>
}
}
}
>
>
Then, an issue involves that the Pth Hdr Qpa Req are distinct
types, among all the APIs, though they just extend the common
types. Then, those usually being the outside of the document,
so, not "in" the document as it were, all the members just get
copied among those, interchangeably, while the types in the
signatures, keep each API's types distinct. It results quite a few
types yet that also makes it great as each simply can be referred
to by its class constant, and it totally makes it so that common
behavior is a simple matter of extension.
>
Relating the HTTP status codes to the resulting response bodies,
is for the covariant return types, or fault, and how to make a
convention in the exceptions,
>
>
The Signature, Api + ApiMapping, then, basically encapsulates
everything
there is to make an HTTP request and interpret an HTTP response
according to the Api validation indicating values and ranges
and ApiMapping mapping indicating HTTP request and response
semantics.
>
Then, the covariant response semantics, is to get figured out,
to make it so that the exception types have a neat little convention
to extract according to response status and headers, the response
body, besides the usual case the success case.
>
For responses with no content, it's figured to have a distinguished
Rsp type or just to return void.
>
For common types then also is for common semantics, then as
with regards to those resulting the "schema" as what it is,
though that this is only about "interface first" as it were
with not much care except in the Java ecosystem, then as
with regards to Spring Web semantics and, JAX-RS semantics, say.
>
Api
ApiMapping <- Spring Web
ApiRsmapping <- JAX-RS Jersey
>
>
Hdr
Pth
Mtx // "MatrixVariable"
Qpa
Req
Rsp
Err
Cov1
Cov2
>
Then, how to associate status with the Covariant responses,
is sort of for annotations and repeated annotation, that relate
statuses, to, response bodies, then of the various kinds of response
bodies, then to sort of adopt the OneOf of the "Variant" return
types, among those.
>
class CovariantFault extends ApiFlt
>
@Success( status = 200)
@Success(status = 201, result = Accepted201.class)
@Success(status = 204, result = NoContent204.class)
>
@Covariant(status = 400, result = Error.class)
@Covariant(range = "4xx", result = Error.class)
class ErrorFault extends CovariantFault { static class covariantClass =
Error.class;}
>
@Covariant(status = 404, result = NotFound404.class)
class NotFoundException extends NovariantFault {}
>
@Covariant(range = "5xx", result = RetryOrCircuitBreak.class)
class BackendException extends CovariantFault {}
>
The idea is to sort of just inspect the interface for its members,
then find off of those the status. Then, inspect the interface
for its exceptions, and make what results for those the covariant
return values, and whatever other cases result from invocation.
>
@ResultSuccess(status = 200) @ResultCovariant(result = {Cov1.class,
Cov2.class})
>
@ResultCovariant(status = 400, range = "4xx", result = Error.class,
exception = ErrorFlt.class)
>
>
public interface Srv {
interface Grp {
interface Api extends ccc.api.Api {
>
static class Pth{}
static class Qpa{}
static class Hdr{}
static class Req{}
static class Rsp{}
static class Flt{}
static class Err extends Error {}
static class ErrFlt extends ErrorFault{}
static class Cov extends Error {}
static class CovFlt extends CovariantFault{ static class
covariantClass = Cov.class;}
>
>
Rsp api(
@Valid @NotNull Pth pth,
@Valid @NotNull Qpa qpa,
@Valid @NotNull Hdr hdr,
@Valid @NotNull Req req
) throws ApiFlt, ErrFlt, CovFlt;
>
}
}
>
}
>
>
For aligning with OpenApi, then there's a default range named
"default",
then whether the 2xx, 3xx, 4xx, 5xx ranges are named like 3XX or 3xx.
(Upper case, like '5XX'.) Then the idea would be that usual sorts of
unit tests check that the annotation match for the ApiMapping among the
Jersey or Spring RequestMappings, the OpenApi documentation and type
declarations, then those all being defined simply enough as a usual
sort
of HTTP Api with Pth, Hdr, Qpa, Req, Rsp, then Flt, Err, Cov, and so
on.
>
>
Anyways I got it running this way and it works pretty good,
works just great with plain vanilla framework, and today's.
>
Then, for the types, is sort of to indicate the Inner and Outer or
Inward and Outer types, and for branching, with the idea then
that the relations of types are defined first by inheritance for
the composition of their contents, then as with regards to
the document, basically for JSON and XML whether the document
has a root in it like XML or is a branching like JSON (or that most
usually it's a "JSON object" vis-a-vis plain values in JSON).
>
This gets into two major cases, where there are alternatives
on the outside, and where there are alternatives in the members,
with regards to "any" and these kinds of things.
>
Basically this seems for whenever extending a class, to provide
it its own type for differentiation and declaration, whether it
still is to be considered that it "is" the parent class, so that,
it's really of a copy-constructor in semantics, in terms of
assigning it values of the parent object,
>
Superclass superclass = subclass ; // is assignable
>
Subclass subclass = superclass ; // not assignable
>
>
Then, the idea of declaring "Subclass" and "Superclass",
or "Sub" and "Sup", is to make it so that it results sort
of the thing.
>
I.e., the object that only extends to establish its own
type in the interface and signature, is to have some sort
idiom to result that what it extends, is assignable to it,
that this would be overloading "=" assignment, in a sense,
for the superclass, as an instance of (the values in the structure
of) the subclass.
>
Superclass superclassInstance = subclassInstance; // is assignable
>
So, the idea is to implement a method named sup,
on these extensions, that accepts a superclass,
and returns an instance of the same-shape sub-class
for assignment.
>
Subclass subclassInstance = Subclass.sub(superclassInstance);
>
I.e., the "is-a" relation is reflective, or for, "asA", ..., "ofA".
>
Subclass subclassInstance = Subclass.ofA(superclassInstance);
>
>
For openApi then it seems for populating subtypes, but mostly
is the idea is that the Api Signature annotations will indicate
what openapi annotations get create, then to employ those.
>
>
class org.PojoXsdDefinedType {}
>
class MyPojo extends PojoXsdDefinedType {}
>
The idea is that inside the framework, each Api has its own type,
but on the wire, the XML-style with the document in the root,
or the JSON-style with the document projected into the root,
are two different styles, and the Serializer and Deserializer of
the bodies or payloads, make for marking for an object what
is its payload, then that the framework makes and returns the
things, so it is simple and thorough overall, while not much
encumbered or intrusive, and not very tightly-coupled, except
of course all defined well according to types.
>
Java has single inheritance of classes and multiple inheritance
of interfaces, with regards to patterns like diamond and so
on. Pretty much all the usual surround of Pojos are classes,
vis-a-vis Poji's or plain-old-Java-interfaces.
>
>
class MyGrp {
int id; // notOnTheCreate
String name;
List<Integer> memberIndividuals;
List<Integer> memberGroups;
>
String onlyOnTheCreate;
String onlyOnTheUpdate;
String onlyOnTheGet;
}
>
The idea is that often the POJO will have various fields in it,
and the validation or constraints, only apply with regards to
being a request or response, and they can't be differentiated
exactly and only by the type.
>
class MyGrp {
int id; // prefer Integer or boxed types everywhere, so,
validation
String name;
List<Integer> memberIndividualIds;
List<Integer> memberGroupIds;
>
}
>
class MyGrpCreateReq extends MyGrp {
String onlyOnTheCreate;
}
class MyGrpUpdateReq extends MyGrp {
String onlyOnTheUpdate;
}
>
class MyGrpGetRsp extends MyGrp {
String onlyOnTheGet;
}
>
>
There isn't a way to make a sub-class override the validation
constraints, about jakarta.validation nee javax.validation, where it's
figured exactly that the XSD constraints and the javax.validation
constraints go on the one POJO definition once then are to be same and
re-used throughout.
>
(Anybody know a good XJC plugin that translates the XSD constraints
exactly to javax.validation constraints? There's this krasa bit I
haven't.)
>
So, Java can't implement the "Diamond" in this sense, or, subclasses
of course inherit all members of superclasses, about what it results
then to just leave the constraints off the fields of the superclass
that are different in subclasses, with regards to "Mixins", that
usually
the goal would be to add a Mixin of onlyOnTheRequest and
onlyOnTheResponse apiece, ..., then with regards to that the
Api methods are in these types, and then that the external
Signature thoroughly encloses what all's in all the Apis among
a bunch of Apis, according to these ApiMappings, for XML and JSON.
>
About Mixins, the most usual sort of thing is BeanUtil copyProperties,
figuring that here that's just an associative-array of objects pretty
much,
>
<SUB,SUP super SUB> Mixin.copyInto(SUB sub, Class<SUP super SUB>
supClass, SUP sup);
>
<SUB, SUP super SUB> SUB Mixin.construct(Class<SUB> subClass, SUP sup);
>
>
About Xjc, basically the idea is this: a very slim xjc output, fields
only, then that adds lombok annotations to the output classes (yeah, I
know), so that the JAX/B binding annotations are on the fields, and
then
the lombok annotations go on the classes, then perhaps with some of the
jackson annotations on the fields/classes, but mostly the
javax.validation annotations on the fields/classes.
>
The XJC has a cool convention on List members, doesn't generate setters
by default, and always initializes empty (and, non-null) list members.
The is about the "otherwise behaviorless" structure, what the behavior
of access to list members should be, List or Map, or as with regards
to "getters" and "setters", "adders" and "putters". A usual idea is
that "if it's null it's null", very usual.
>
It's sort of like "isn't there something since XJC to translate XSD
schemas into suitable POJO's for JAX/B", and it's like, "XJC is about
one of the greatest things with regards to anything to do with Java,
XML, and JAX/B". XJC and JCodeModel are pretty much great.
>
https://github.com/kohsuke/jaxb/blob/master/jaxb-ri/xjc/src/main/java/com/sun/tools/xjc/ModelLoader.java
>
>
>
>
>
>
Then, it sort of seems like for making a slimmed-down inspired-by-Xjc
sort of thing, yet, there's still for any sort of WSDL using wscompile
or this sort of thing, about, XML and XSD, and SOAP and WS, ..., which
is very usual.
>
>
It's pretty much POJO's everywhere, though I'd be a big fan of POJI's,
but pretty much it sort of results that for plain-old-data (and no
behavior at all except as structured data in values), POJO's
everywhere,
..., here with the goals of declarative type-safety and validation,
while, not exploding the number of types, and, surfacing the relations
of inheritance of types, out of what results the framework into schema.
>
POJO's everywhere pretty much have "and it must be private fields and
getters/setters everywhere because the static analysis first thinks
so",
should be that whatever results from Schema the derived POJOs,
and vice-versa, should mostly work off the fields and their
annotations,
what with the getters and setters then being gratuitous in the
definition. (This is that any non-static member field is an otherwise
behaviorless property, and that any conversions or coercions are either
only boxing in the language or outside on the serialization and
validation, type conversion and coercion.)
>
There's mostly only one framework serializer in Spring about JSON,
and it's FasterXML Jackson, while for XML, mostly one would rely
on JAX/B annotations to reflect the richer structure and schema of XML.
In Spring Web, there's also to be considered the
MethodArgumentResolvers, about the corner case of headers and query
parameters whose keys aren't usual Java beans identifiers, and clubbing
those into the one or multiple Hdr or Qpa API Signature parameters,
above, because the usual RequestParam and RequestHeader don't have one
and MultiValueMap and so on, and KeyValuePairArray and KvpLiteral or
the
least-needful to model the API Mapping.
>
That Java had a plain "Struct" type, ..., though the "record" class
object is pretty first-class, ..., and most Bean-like property copiers
will discover the getters of the properties thusly, ..., has mostly
that
the getters are named "get" and the setters named "set", ..., that
there's something to be said for POJI's on records as immutables then
just adding setters as the property name field1(String 1 f1).
>
Then again some people want to replace _every single instance of
String_
with a strongly typed language of the String as a CharSequence, ....
Or,
at least I do, with an overall approach to Strings, Enums, and in
CharSequences.
>
Schema is one thing that seems missing the most in all the modern-ish
HTTP-JSON-RESTy world, which is good and bad. Luckily the whole XML
with XSD schemas really set a great example of how it should be done,
or rather, what use-cases it should fulfill. So, it's to be expected
that at some point JSON schema finally gets into the toolchain, because
what's derived should be derived.
>
So, about POJOs, they're pretty much fungible, and pretty much
ubiquitous. While that may be so, the construct-and-build and
stream-and-read use-cases are pretty much entirely different, for given
types, what one would hope would result POJI's, that basically for a
given POJO, it has two POJI's, the immutable part of the getters and
the
mutable part of the setters.
>
>
class Pojo{
String p;
>
String getP() { return p; }
void setP(String p) }{ this.p = p;}
}
>
interface PojiGet {
String p();
}
>
interface PojiSet {
void p(String p);
}
>
class PojoPojied implements PojoGet, PojoSet {
>
}
>
record PojoRecord implements PojoGet {
String p;
}
>
The serialization and deserialization frameworks pretty much expect
their various no-arg and all-arg constructors, about the other great
boojum of structured data in an associate-array class property world,
property order.
>
A usual sort of idea is to go through a world of POJOs that exist,
because they're everywhere and model all the things, and make
a "derived" framework of Pojis the getters and setters for them,
of a sort of "Imm" and "Mut" as it were, and "Get" and "Set",
and making constructors and property order and builders then
for whether builders result mutable or immutable, these kinds of
things.
>
>
class Pojo {
String p;
String getP() { return p;}
void setP(String p) { this.p = p; }
}
>
interface PojiGetter {
P p();
}
>
interface PojiSetter {
void p(String p);
}
>
interface PojiImmutable extends Setter {
default void p(String p) { throw new
UnsupportedOperationException(); }
}
>
interface PojiMutable extends Setter {
// eg, override some of the otherwise immutable
}
>
>
class PojoPoji implements PojiGetter, PojiSetter {
>
String p;
>
PojoPoji(Pojo pojo) {
this.p =
}
>
@Override
String p() { return p;}
>
@Override
void p(String p) { this.p = p; }
}
>
record PojoRecordPoji implement PojiGetter {
>
String p;
>
PojoRecordPoji(Pojo pojo) {
this(pojo.getP()); // propertyOrder for the initializer, ....
}
}
>
So, it's sort of the idea of an APT tool, to find everything marked
@lombok.Data, and derive and generate these things, then carry along
the
relevant @Json... annotations.
>
The property order is about the thing to get figured out, there's a
plethora of annotations relating it in java.beans, java.xml.bind,
the Jackson annotations, what Lombok makes, variously, all
should mean about same, and where it is so that -parameters
isn't necessarily so and that at runtime there isn't necessarily
byte-code introspection, only the language and runtime's
guaranteed reflections according to class, and record, and
java.lang.reflect, and java.lang.annotation.
>
Property order and one or the other of getP/setP or p-and/or-p.
>
Pretty much bog-standard and everywhere, ....
>
>
So, first there's the idea that HTTP APIs have a standard Signature,
pretty much a normative signature, then about what gets involved
as directly on the data structures to indicate their type relations,
anything extra the plain composition of their values as plain
old data objects, and "Beans" in a sense yet to distinguish from
both "J2EE Beans" and "Spring Beans", variously, and their notions
of the property editor and magic of J2EE beans vis-a-vis the module
instance name/type association of Spring Beans, just Pojo's and
Poji's, then plain getter/setter Pojo's and get/imm/mut Poji's.
>
Schema, ..., in the language.
>
>
>
>
>
So, the idea is that what results is a "Signature", or HTTP signature,
which follows a bit of reflection about these
>
request mapping annotations, Spring Web or Jersey
serialization annotations, Jackson or JAX/B, KvpLiteral
these SuccessResult and CovariantResult result annotations
these CovariantFault annotations on Exceptions
some Inner/Outer or Sub/Sup annotations to indicate things
>
then it results that for an <A extends Api, AM extends ApiMapping>,
there results a Signature, of the MethodParams, these various
Pth, Hdr, Qpa, Req, Rsp, and the Flt types,
that both implements ClientBuilder for the Api,
given serializers the framework's Jackson and JAX/B,
and client the frameworks Http, Rest, Web clients,
and java.lang.reflect.Proxy and InvocationHandler,
that HTTP ClientBuilders are derived from HTTP Signature.
>
Then, also the OpenApi annotations are derived from the Signature,
making it so that the Inner/Outer types of the APIs, then have
what results an OpenApi definition (or, for what should be
SOAP-WS and these types services, what it is), then it so results
that it all sort of follows from the Java language declarations
and definitions, naturally following extension of interfaces and
classes, in the most usual sort of world of Pojos, that it results
the Controller's just implement each of the ApiMappings and
the Client's just implement each of the Api's according to the
HTTP Signature of the ApiMappings, with that the ClientBuilders
each have a totally simple implementation with very well-known
and understood (and, guaranteed) semantics, that as well support
the Covariant and Error return types, according to exception
specification, in the language and neatly.
>
Then, the goal would seem to be to make it so that these same sorts
things get generated round-trip and derive round-trip, both the
schemas, OpenApi as it may be here, and the interface, the
Api and ApiMapping interfaces, all one neat little thing.
>
I wrote one of these last month so now I re-write the exact
same thing as it's only about ten or twenty classes then
adding MethodArgumentResolvers to WebMvcConfigurer
then some ExceptionHandler to the Controller to result
the Covariant return types, then a bit of implementing
client builders after an AbstractSignatureHttpClientBuilder,
then for all the validation being according to jakarta.validation,
as what results just dropping that code into any maven or gradle
"spring-boot microservice", bit, and making it all that way.
>
>
>
>
>
>
Another usual idea is to tag the API interfaces with their
roles,
>
R Read, Read-Only
W Write, "Write-only" or, Read/Write, Write-or-Read
B Basic, least access
A Admin, all access
S Supervisor (approvals)
T Technician (delegations)
>
then for usual sort role rules on each the APIs,
the expressions are very uniform and same.
>
R | W | A : read-only
W | A : write-or-read
>
S + R | S + W | A : Supervisor required
T+ R | T + W | A : Technician only
>
S + W | A : Supervisor required
T + W | A : Technician only
>
That what's available to Basic at all looks like
>
B | A | R | W | T | S
>
Or, just R or W.
>
These then get associated with the scopes and grants of the security
methods.
>
This is where the security methods or AuthN AuthZ
mostly just go in the client configuration for the
endpoint, annotating those on the Controller and
having them build into the Client, from just a
block of annotations on the Api and ApiMapping.
>
The Endpoints is another datum with regards to the Api,
usually about the "environment" or "stage", eg a usual
sort of "Local, Dev, Preprod, Prod", or along the lines of
"Local, Dev, Test, Preprod, Stage, Prod", then as with regards
to Endpoints by stage X zone, eg "East, West, EU, JP, CN",
or "NE, SE, NW, SW", cardinal and regional zones.
>
Then the Endpoints sort of relate and then to the various
notions of Principals the Identities and Grants and Scopes
the Roles, about a pretty simple table or catalog or source
of those, what are the APIs'.
>
About AuthN and AuthZ and the identities and roles,
and, delegations and the system account, and journaling
and auditing, it's a sort of usual thing, "HTTP web services".
>
Then, the idea of this Api and ApiMapping pattern,
is basically to result that it looks more like, "Remote
Procedure Call", from the caller's perspective being
the same, and indeed, the same code calling to a
given built Proxy Client or just wired right into the
Controller, or for test fixtures of same and all sorts
usual things, without then after that much after caring
about the protocol in the middle, at all.
>
>
>
>
>
>
The Annotation in Java is effectively final, and not really
extending other interfaces, and the framework (here
Spring + Jackson + JAX/B + JSR303 validation the jakarta
varieties, and Lombok the getter/setter generator),
and these Signature HTTP Api annotations mentioned above,
has that the framework is a great bit of convention,
what results the thing.
>
So, about annotations then, the goal is to have the annotation
only appear once, then to have its intent inherited, then that
the declarations and definitions follow so naturally in the
language, of classes and interfaces, singly and multiply inherited,
records, and in the semantics of calls and exceptions.
>
The validation annotations, have semantics variously about
the method arguments and return value, and the classes
and the fields of the classes. The idea is that all the method
arguments are annotated exactly the same, @Valid @NotNull,
and that's it. This is where, the only method argument that
might be a built-in are the path variables, and indeed the
path variable @PathVariable or matrix variable @MatrixVariable,
lives in the method signature, while otherwise the headers are
clubbed in a Hdr and the query parameters clubbed in a Qpa
and the request body is an object, a Req, each of those defined
as static inner classes of the API's S.A.M. (definable as a lambda
with an arrow function), the method arguments each get
@Valid @NotNull in the method signature.
>
Then, the validation annotations on the classes, have that
each class is marked @Valid, then that what's required is
marked @NotNull and the rest is whatever makes it valid,
according to "the schema".
>
The validation annotations have to go on the root of the
inheritance hierarchy of objects, subclasses can't override
them according to the validation implementation's
walking up the inheritance hierarchy finding the validation
annotations. So, they go on the Pojo's and on the Api methods,
once each, and same each.
>
It is since about Spring 5.2 or recently in the world of Spring
that's about 6.1, that RequestMapping annotations can
go on an interface that Controller implements, so that
Controller need not duplicate the annotations. However,
it only looks up one inheritance level to look for annotations,
so the RequestMapping annotations have to be directly on
the interface that the Controller thusly implements the convention.
>
Then, the OpenApi annotations, the OpenApi 3 spec, has
that the usual swagger-ui also looks up one inheritance level
from the Controller, so that way, whatever's annotated on
the RequestMappings the ApiMapping, gets picked up by
both the Controller and the OpenApi generator and resulting
swagger-ui.
>
Api
jakarta.validation "Validation annotations"
>
ApiMapping
org.springframework.web "RequestMapping annotations"
io.oas.v3.swagger "OpenApi annotations"
>
>
The "Data" objects, have involved the Lombok annotations,
and, the FasterXml JSON annotations, and, the Validation annotations.
>
The usual ideas of data objects include "DAO: Data Access Object",
"DTO: Data Transfer Object", "DPO: Data Presentation Object",
here basically is that Req and Rsp are DTO's while Hdr and Qpa
are clubbed key-value-pair-arrays/multimap, then that the
SuccessResult and CovariantResults are various DTO's the responses,
that all the DTO's get annotated with lombok.Data and they
get annotated with Json "serialize non-null" and "deserialize
ignore-unknown",
the annotations are the same on every DTO. When DTO's are
implemented by inheritance of composition, then there's an
extra bit involved for lombok.EqualsAndHashcode(callSuper=true),
so the annotations are not necessarily identical on every single
Pojo, yet they're identical for Pojos that extend others and they're
identical for Pojos that don't extend others.
>
Then the Validation annotations on the POJOs essentially
enforce required values. Since recently the
spring-boot-starter-validation,
actually sort of drops in neatly and then @Validated on the @Controller
results that it works alright, and pretty much @Validated on any
Spring Bean sort of works alright.
>
About the "default" values, that's a bit tougher to figure out.
The idea is that the Pojo's have no initializers and what's null
is absent and what's non-null is present. Otherwise one might
figure that primitives like int would mean required and int i = 0
would mean default, except 0's also just the default value of
primitive int. So, in the language, the idea is to use Integer
the boxed type instead of int, then as with regards to a default,
that it sort of deserves its own annotation, so that then
a "Defaulter" as it were can, "defaulticator", "defaultifier",
has that as the Controller receives the validated DTO request,
it sets the default on whatever's otherwise null.
>
Then, it's figured the clubbed Hdr and Qpa look like this,
as example
>
class Hdr {
String s;
Boolean b;
@Literal("X-Lit") @JsonProperty("X-Lit")
String lit;
List<String> repeated;
}
>
It's figured then that those headers result in the HTTP request
like so.
>
s: ...
b: true
X-Lit: ...
repeated: r1
repeated: r2
>
It's similar with Qpa query parameters, they just have a convention
that matches the key to a field name and the value to a field type.
>
Why there is this @Literal or @KvpLiteral, is because, where
everywhere in JSON serialization/deserialization the @JsonProperty
will keep intact the key name, in the MethodArgumentResolver
that would otherwise convert RequestHeader or RequestParam,
to the object that it invokes on the Controller or its proxy in Spring,
it will give exactly and only a LinkedMultiValueMap implements
MultiValueMap,
so that clubbed parameters in Spring will otherwise only accept
MultiValueMap
or concretely LinkedMultiValueMap, and don't have annotations to indicate
the @KvpLiteral, which would otherwise clutter the method signature.
So, without getting into the Binders or PropertyEditors, it's added
two MethodArgumentResolver's, in WebMvcConfigurer. Then, the
ApiMapping doesn't have @RequestHeader or @RequestParam on otherwise
these requests. These wouldn't be required, some @RequestHEaderKvp and
@RequestParamKvp, except, to get the @KvpLiteral to make the HTTP
header key or query parameter key that doesn't make a Java field
identifier,
in the convention of reflection.
>
Then, it's sort of figured to only support String, Integer, and Boolean,
in those, then List's of those or otherwise not adding new types to
the DTO's, the Pojo's, while still having them all strongly typed.
>
That's not to say the signature couldn't break those out variously,
>
interface Post extends Api {
>
static class Headers1 {}
static class Headers2 {}
>
static class Req{}
static class Rsp{}
>
Rsp post(Headers1, Headers2, Req req) throws ApiFlt;
>
}
>
interface PostMapping extends Post, ApiMapping {
@Override
@PostMapping(value = "/grp", produces = "application/json",
consumes = "application/json")
@ResponseBody
Rsp post(@RequestHeader Headers1, @RequestHeader Headers2,
@RequestBody Req req) throws ApiFlt;
>
}
>
>
Yet, it's to be avoided, with exactly and only one method argument for each
of the Hdr, Qpa, and Req. The Pth and Mtx or PathVariable and
MatrixVariable,
they each get their own one, figuring they definitely must be satisified
to fulfill
the request mapping, while the other, though non-null, may otherwise be
empty,
what with regards to what validates them.
>
interface Get extends Api {
static class Rsp {}
>
static class Flt extends ApiFlt {}
>
Rsp get(String pth1, String pth2, String pth3) throws ApiFlt, Flt;
>
}
>
interface GetMapping extends Get, ApiMapping {
@Override
@GetMapping(value = "/grp/{pth1}/{pth2}/{pth3}", consumes =
"application/json")
@ResponseBody Rsp get(@PathVariable("pth1") String pth1,
@PathVariable("pth2") String pth2, @PathVariable("pth3") String pth3)
throws ApiFlt;
}
>
It's figured to leave the Controller just marked with Controller not
RestController,
and specifically just mark the @ResponseBody on the ApiMapping, and that
the consumes and produces as most usually application/json, isn't that
much to be saying.
>
import api.ApiFlt;
import my.Get;
import my.GetMapping;
import my.Post;
import my.PostMapping
>
@RequestMapping(value = "/srv/v1")
class Controller implements GetMapping, PostMapping {
>
@Override
Get.Rsp get(pth1, pth2, pth3) throws ApiFlt {
throw new ApiFlt();
}
>
@Override
Post.Rsp post(Post.Headers1 h1, Post.Headers2 h2, Post.Req req) throws
ApiFlt {
throw new ApiFlt();
}
>
}
>
>
This way the Controller inherits the RequestMapping annotations from
GetMapping,
while as the names are unambiguous according to import, then it starts
looking
more brief than "MyServiceGroupApiMethod" types everywhere, with
"import my.service.Srv.Group.Get" then just referencing Get's member
inner static classes all in the Api interface.
>
It works pretty well this way though it's only since about Spring 5.2 that
the RequestMapping interface can be separated from the Controller,
if only one deep, and also recently then that OpenApi reads off the
v3 OpenApi annotations from the interface, also, so that Controller
starts looking un-cluttered. The Validation implementation sort of
smoothly works with Spring Web this way also sort of recently.
So, it's nice to get it all together.
>
>
>
One especially great thing is that the compiler in interface
implementation,
by declaring @Override, it's great that extension interfaces definitely
declare the same API method its signature, and otherwise the compiler
guarantees that that types are all about the same and about the declaration
of the exception specification, then resulting what it does.
>
>
The Defaulticator, basically is to effect that after validation establishes what's required and notnull, then then defaulticator, has to append what would otherwise be the default, on the Controller side, then as with regards to that it's not part of the Validity of the default to be present, over the wire and deserialized, then as whether the deserializer is the defaulticator, or, there's a bit of custom defaulticator, to reflect the same value as what's on the RequestMapping and the OpenApi.
It's figured that the default would be on a field, and usually,
that the default is exactly a scalar value, not a default Pojo.
So, the idea for the default, is that it's sort of required to be valid,
and about getting the default on the deserializer, so that when
it arrives that the parameter is otherwise required (@Valid @NotNull),
then the defaultification gets applied first.
With the Headers and QueryParameters clubbed together, and at
most a @KvpLiteral annotation, then also is for a @Default annotation,
that gets ignored on the serialization, then populated on the
deserialization, that the Controller can be ignorant and not check
its absence to establish its presence, instead rely on its presence.
Spring
PathVariable no defaultValue
RequestBody no defaultValue
RequestParam defaultValue
MatrixVariable defaultValue
RequestHeader defaultValue
Jackson
JsonProperty defaultValue, note, intends "... [only] to _document_
expected default value..."
JsonPropertyDescription, field annotation
JsonPropertyOrder, class annotation
Jersey / JakartaJersey
jakarta.ws.rs.DefaultValue
https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/web/bind/annotation/package-summary.htmlhttps://jakarta.ee/specifications/platform/9/apidocs/https://fasterxml.github.io/jackson-annotations/javadoc/2.8/com/fasterxml/jackson/annotation/package-summary.htmlhttps://jakarta.ee/specifications/bean-validation/3.0/apidocs/So it seems pretty much that Spring makes for "defaultValue",
and implicitly sets "required" to false, while Jackson's "defaultValue"
is only informative, so what seems the idea is to have @KvpDefaultValue,
and all what it applies is to the Spring MethodArgumentResolver,
then to figure that Jersey has something similar to MethodArgumentResolver, what results the KvpRequestParam and KvpRequestHeader, would have the same meaning to both frameworks, for the goal of having an ApiMapping, for Spring, or as for ApiSpringMapping and ApiJerseyMapping, or with respect to whatever framework. Then setting the KvpDefaultValue would make it so that whether the Validation @NotNull would be expected to be applied, has that it should be. The Validation happens after the MethodArgumentResolver, then though with regards to re-using the interface and that the Defaulticator would otherwise be an Aspect
before the Validator aspect, or caller beware, as it were.
Jersey has a similar notion to MethodArgumentResolver in ParamConverter
and ParamConverterProvider, about @KvpRequestHeaders, @KvpRequestParams,
and @KvpLiteral and @KvpDefault. (Since 2.0.)
The OpenApi mentions "default" under schema, but doesn't much say
except that the default expectedness is not-required, not about
defaultValue. Under parameter schema, "default" is an attribute value of the type, of the schema contained only within the parameter definition. Then XSD does or doesn't have a notion of defaultValue, as whether JSON schema internally does or doesn't have a notion of defaultValue. I.e., defaultValue is only relevant to the request headers and parameters, not the body.
XSD under simpleContent where it has the restrictions which would be
the same thing as the constraints, doesn't have a notion of defaultValue.
https://www.w3.org/TR/xmlschema11-1/I'm not too familiar with XSD 1.1 circa 2012, while XSD 1.0 circa 1999 with a bit of 2000 is pretty much what all the XSD's are written in.
https://datatracker.ietf.org/doc/html/draft-wright-json-schema-00#section-4.2Well I'm terrified because this RFC says "JSON Schema interperts [sic]
documents ...". Then it says "A JSON value interperted [sic] according to this ...".
XSD's have their URI's and namespaces, JSD's as it were, base URI and "id". Then JSD basically is only shape and the names of object keys, declaring that any extensions are allowed and if not understood to be ignored, while OpenApi then adds constraints. XSD of course is really great and thorough and describes the shape and type of things what result validation.
https://docs.swagger.io/swagger-core/v2.0.0-RC3/apidocs/io/swagger/v3/oas/annotations/package-summary.htmlhttps://docs.swagger.io/swagger-core/v2.0.0-RC3/apidocs/io/swagger/v3/oas/annotations/media/Schema.html#defaultValue--So, mostly it seems that these OpenApi annotations would be inferred,
yet pretty much they're all to be derived, and when they're all put on
the ApiMapping, then it does look sort of nice when they're all on
the page.
About enums, is for the great thing that is Enum, and the least needful
to make Enums have a natural match, to values. So, that would start
with Jackson, and about how Jackson serializes and deserializes Enums.
The idea is that the Enum has value, yet, often enough, in Java there
will be some reason to have a naming convention for Enums, that
is any different from the String stringValue, or with regards to any
other type of value eg Integer the restriction is. Now Jackson has
an interesting JsonEnumDefaultValue annotation, about the ideas
of "Enums" and a minimal sort of "StandardEnum", with regards to
Enums to and from strings, or, integers, say, or other named values
within large ranges. Enums can't extend or be extended as classes,
yet there's an idea that interfaces with default methods make for
treating them as has methods of a type and templating for their
types, then for having an UNK for "unknown" member and an
"isKnown()" method, then for some EnumString and EnumInteger
and EnumURN type interfaces, then what result return values in
those and from those, about for toString/fromString and
toInteger/fromInteger and these kinds of things.
https://docs.jboss.org/hibernate/stable/validator/reference/en-US/html_single/Then it seems there would be for Validator ValueExtractors to
make for that otherwise an Enum would be valid as NotNull,
because a valid enumerated value is any in the range, while,
when there are excluded values like UNK, how to make it so
that standard sort of enumerated values, get into the framework
for where they are String or Integer, then as for that Boolean
usually suffices with regards to implicit null unknown or don't care,
and explicit "indeterminate" or "U" a usual value for "unknown".
Then it's figured that for Enum type, the XJC and other schema
derivatives, will have exactly the values, though as with regards
to the various types, has for there either being a Deserialization
exception or a Validation exception, or as whether Deserialization
of unknown Enum values results null, or throws. Then if the
Enum is defined inside, and has an UNK or other reserved values,
is to make the JsonCreator and JsonValue, be on methods that
throw for the reserved values.
The goal here is to have everything in the framework, annotations
as necessary declared exactly once and in a normative place for each,
then to have the pattern of the implementation all in the language,
with very natural interpretations, or interpertations if you will,
and an uncluttered Api method signature, and a fully self-contained
ApiMapping HTTP Signature, well-defined after reflection, for mostly
uncluttered Controller implementations, and, automatic ClientBuilders.
Then, what seems gets added is a MethodArgumentResolver for Spring Web
and a ParamConverterProvider for Jersey.
https://github.com/spring-projects/spring-framework/blob/main/spring-web/src/main/java/org/springframework/web/method/annotation/RequestHeaderMethodArgumentResolver.javaThe point is to support clubbing the Hdr and Qpa arguments into one
argument, and to support them having KvpLiteral or KvpDefaultValue on the properties, then otherwise their "required" is defined by @NotNull, and they get validated just like regular arguments.
That being the very least, provision to support X-Literal and query
parameters mapping to String, Integer, Boolean, Enum, and Lists of same or some specific extends of List to StringList, IntegerList, BooleanList, EnumList<E extends Enum>, makes the Kvpa's (key-value-pair-arrays), for it to result that all these HTTP APIs get treated in a very similar way, and where all the common factors of elements in schema just result a usual and intuitive class hierarchy.
Then, two things that seems to make some sense are "XJC slim",
I've written XJC plugins before in JCodeModel and it's a very flexible
thing, to basically omit writing the getters and setters and add @lombok.Data and to add any needful @Json annotations and the relevant Validation annotations, or to put the annotations on the relevant properties where there's property instead of field annotation, then so to result that what's standard is standard and what's schema is schema and what's derived is derived, and the parts both work together and keep out of each others' way.
Then another is that the SuccessResult and CovariantResult make for
what makes for altogether generating the OpenApi annotations to
complement the framework annotations, so that of course it so results
that the parts of the OpenApi annotations related get so derived.
(And that the ClientBuilders and the Controller ExceptionHandler
all work on the same definitions and according to the language.)
The other thing then is the Inner/Outer or Super/Sub, basically
about XML/JSON, to make it so that the Api in its interface
extending the body/payload type as the Req or Rsp, has
returned a Req or Rsp, that subclasses the Document/Root.
This kind of thing, ....
Java HTTP API Signatures, schemas, XML and JSON, Pojo's and Poji's, Java and Spring and schema
Re: Java HTTP API Signatures, schemas, XML and JSON, Pojo's and Poji's, Java and Spring and schema