java(plugins): extend building-plugins guide with ecosystem conventions - #2870
java(plugins): extend building-plugins guide with ecosystem conventions#2870rjayasinghe wants to merge 1 commit into
Conversation
Adds a "Plugin Conventions & Reference Implementations" section to
building-plugins.md, grounded in an analysis of the real plugins in the
cap-java GitHub org (attachments, notifications, ord, event-hub,
advanced-event-mesh, auditlog-ng, cds-ai, print, console, n8n, and the
plugin-template-emoji skeleton).
The new section covers:
- Reference plugin table linking each pattern to a living example
- Recommended multi-module Maven project layout
- Maven skeleton: ${revision} + flatten-maven-plugin, cds-services-bom
import, versionless cds-services-api, cds-maven-plugin pinning,
and a package.json companion for hermetic cds-dk builds
- CdsRuntimeConfiguration hook decision matrix (environment / services /
eventHandlers / providers / order, with when-to-use and reference repo)
- Spring AutoConfiguration as the alternative when typed
@ConfigurationProperties / @ConditionalOn… wiring is needed
- Custom Service interface + DEFAULT_NAME + EventContext pattern
- Configuration & enablement: binding-driven mock-vs-productive handler
switching; no cds.<feature>.enabled convention
- Testing: cds-services-impl (test scope) for unit tests, a dedicated
integration-tests app module, CDS mock handlers for external services
- Repository hygiene: REUSE/Apache-2.0, CI workflows, Maven Central publishing
Also adds two small in-place edits:
- groupId caveat clarifying that cap-java example repos use com.sap.cds
as SAP-owned artifacts; the external-plugin rule still stands
- Ecosystem norm note pointing from the ServiceLoader-vs-Spring decision
to the new Configuration & Enablement subsection
|
@Akatuoro I asked Claude to reverse-engineer some information on how to build CAP Java plugins. Let me know what you think about it. :) |
![hyperspace-pr-bot[bot]](https://avatars.githubusercontent.com/u/2531208?s=60&v=4){kind=small}
There was a problem hiding this comment.
I posted two inline comments on issues that could mislead readers: an outdated CAP Java version example and a Java snippet that would not compile as shown. The rest of the added guide content looks broadly consistent with the existing page structure and intent.
PR Bot Information
Version: 1.31.30
- Correlation ID:
aebfeee0-adc6-11f1-8e03-6b2d1773d93a - Review Focus Files:
- LLM:
gpt-5.5 - Event Trigger:
issue_comment.created - File Content Strategy: Full file content
| ```xml [Root pom.xml — version & BOM] | ||
| <properties> | ||
| <revision>0.0.1-SNAPSHOT</revision> | ||
| <cds.services.version><!-- choose current LTS, e.g. 3.7.1 --></cds.services.version> |
There was a problem hiding this comment.
Bug: The example CAP Java version is outdated
The file now documents active CAP Java 5.x and maintenance 4.9.x elsewhere, so 3.7.1 can lead plugin authors to start from an unsupported baseline. Consider pointing to the maintained version overview instead of hard-coding an obsolete example.
| <cds.services.version><!-- choose current LTS, e.g. 3.7.1 --></cds.services.version> | |
| <cds.services.version><!-- choose a supported CAP Java version, see java/versions.md --></cds.services.version> |
Double-check suggestion before committing. Edit this comment for amendments.
Please provide feedback on the review comment by checking the appropriate box:
- 🌟 Awesome comment, a human might have missed that.
- ✅ Helpful comment
- 🤷 Neutral
- ❌ This comment is not helpful
| // Register in CdsRuntimeConfiguration | ||
| @Override | ||
| public void services(CdsRuntimeConfigurer configurer) { | ||
| configurer.service(new PrintServiceImpl(runtime)); |
There was a problem hiding this comment.
Bug: The example uses an undefined runtime variable
This code snippet will not compile as shown because runtime is not declared in the method or class. Instead, fetch the runtime from the CdsRuntimeConfigurer, as the later example also does.
| configurer.service(new PrintServiceImpl(runtime)); | |
| configurer.service(new PrintServiceImpl(configurer.getCdsRuntime())); |
Double-check suggestion before committing. Edit this comment for amendments.
Please provide feedback on the review comment by checking the appropriate box:
- 🌟 Awesome comment, a human might have missed that.
- ✅ Helpful comment
- 🤷 Neutral
- ❌ This comment is not helpful
1 participant
Summary
java/building-plugins.md, derived from an analysis of the real plugins in thecap-javaGitHub org (attachments, notifications, ord, event-hub, advanced-event-mesh, auditlog-ng, cds-ai, print, console, n8n, and the plugin-template-emoji skeleton).groupIdcaveat clarifying that the cap-java example repos usecom.sap.cdsas SAP-owned artifacts — the external-plugin rule still stands.New section covers
cds-feature-<x>module (+ optional integration-tests, coverage-report)${revision}+ flatten,cds-services-bomimport, versionlesscds-services-api,cds-maven-pluginpin,package.jsoncompanionCdsRuntimeConfigurationhooks + when to use Spring AutoConfigurationServiceinterface +DEFAULT_NAME+EventContextsubtype patterncds.<feature>.enabledconvention; Spring conditional alternativecds-services-impl(test scope); dedicated integration-tests app module; CDS mock handlersAll existing anchors (
#service-loader,#spring-autoconfiguration,#protocol-adapter,#reference-the-new-cds-model-in-an-existing-cap-java-project) are preserved.Test plan
npm run docs:devfrom repo root) and open/java/building-plugins— confirm new section renders with no parse errors#service-loader,#spring-autoconfiguration,#protocol-adapter(linked fromplugins/index.md,developing-applications/building.md,change-tracking.md)github.com/cap-java/<repo>links in the reference table to confirm all repos exist