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.
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