Add a extensions philosophy section to the guide #2242
Conversation
|
|
||
| === Why an extension framework | ||
|
|
||
| Quarkus’ mission is to transform your full applications and the libraries it uses into an optimal output for GraalVM. |
There was a problem hiding this comment.
Quarkus's mission (yeah, English is weird, I know) ... your full application and the libraries
There was a problem hiding this comment.
@LightGuard funny enough @n1hility wrote that part. I guess Madison English is different than US English :D
| Less common properties can live in the library namespace. | ||
|
|
||
| To fully enable the close world assumptions that Quarkus can optimize best, it is better to consider configuration options as build time settled vs overridable at runtime. | ||
| Of course properties like host, post, password should be overridable at runtime. |
| ** The extension framework facilitates reading metadata, scanning classes as well as generating classes as needed | ||
| * Send metadata to GraalVM for example classes in need of reflection | ||
| ** This information is not static per library (e.g. Hibernate) but the framework has the semantic knowledge and knows which classes need to have reflection (for example @Entity classes) | ||
| * Opinionated choices based on the close world view of the application including configuration |
There was a problem hiding this comment.
I think I would first have the general points valid for HotSpot + GraalVM then the GraalVM specific points.
|
|
||
| To fully enable the close world assumptions that Quarkus can optimize best, it is better to consider configuration options as build time settled vs overridable at runtime. | ||
| Of course properties like host, post, password should be overridable at runtime. | ||
| But many properties like enable caching, using a given security model (basic, JWT etc) can safely require a rebuild of the application. |
There was a problem hiding this comment.
The datasource driver is a good example too. Maybe clearer than the security model.
| @@ -119,10 +165,10 @@ has no suffix (and is what the end user adds to their project). | |||
| NOTE: The above `maven-compiler-plugin` configuration requires version 3.5+. | |||
|
|
|||
| [WARNING] | |||
| ==== | |||
| ===== | |||
There was a problem hiding this comment.
I don't think that was necessary or even if Asciidoc supports it correctly.
There was a problem hiding this comment.
It allows multiline admonitions or admonitions containing other blocks. It also allows adding title.
But, yes, in this case, no need.
There was a problem hiding this comment.
I did s/^===/====/, sorry :D
| @@ -740,20 +786,20 @@ An example of parsing a XML config file using JAXB is shown in the `TestProcesso | |||
| <2> If found, parse using JAXB context for `XmlConfig.class` | |||
|
|
|||
| [NOTE] | |||
| ==== | |||
| ===== | |||
There was a problem hiding this comment.
Same here and for all the other ===== on a single line. A simple regexp replace should do it: sed -r -i 's/^=====$/====/g' docs/src/main/asciidoc/extension-authors-guide.adoc.
| The Quarkus extension framework makes a significant impact even when GraalVM is not used (e.g. in HotSpot). | ||
| Let’s list the actions an extension does: | ||
|
|
||
| * An extension hosts Substrate VM code substitution so that libraries can run on GraalVM |
There was a problem hiding this comment.
should you distinguish between the runtime / deployment sides of the extension?
There was a problem hiding this comment.
I added a sentence as a bullet point below Gather build time metadata and generate code
| Quarkus’ mission is to transform your full applications and the libraries it uses into an optimal output for GraalVM. | ||
| To do this you need to analyze and understand the full "closed world" of the application. | ||
| Without the full and complete context, the best that can be achieved is partial and limited generic support. | ||
| By using the Quarkus extension approach, we can bring high density to Java applications. |
There was a problem hiding this comment.
not sure high-density is clear in this sentence.
Maybe says something like reduces memory and footprint.
| To fully enable the close world assumptions that Quarkus can optimize best, it is better to consider configuration options as build time settled vs overridable at runtime. | ||
| Of course properties like host, post, password should be overridable at runtime. | ||
| But many properties like enable caching, using a given security model (basic, JWT etc) can safely require a rebuild of the application. | ||
|
|
There was a problem hiding this comment.
So far it's very focused on the native aspect
Do we want to say something about:
- general build time approach
- reactive AND imperative
- where should be the user API (if any)
- where should be the substitutions, templates ...
Also, it might make sense to provide some stereotypes:
- Get a library running - only substitutions
- Get a framework running - move the initialization to the build (Template, configuration, SPI...)
- Migrate a CDI portable extension - or rather how you need to change your extension to work
There was a problem hiding this comment.
@cescoffier I'm taking this comment into account, I think we should have an imperative + reactive but it's a bit unclear for me how conscise and specific we can be in this paragraph (sebsection really). Can you take a shot whenever?
emmanuelbernard
force-pushed
the
extension-guide
branch
from
dd74397 to
67fa008
Compare
|
oops I mean @cescoffier and @gsmet |
emmanuelbernard
changed the title
|
I've opened #2277 for the follow up actions |
I'm interested in early feedback.
I'm building the infra int he guide to be able to add recommendations and guidelines around extension writing.
CC @gsmet @n1hility etc.