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.