java(plugins): extend building-plugins guide with ecosystem conventions - #2870
Open
rjayasinghe wants to merge 1 commit into
Open
java(plugins): extend building-plugins guide with ecosystem conventions#2870rjayasinghe wants to merge 1 commit into
rjayasinghe 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
rjayasinghe
requested review from
danjoa,
renejeglinsky and
smahati
as code owners
September 9, 2026 09:49
Contributor
Author
|
@Akatuoro I asked Claude to reverse-engineer some information on how to build CAP Java plugins. Let me know what you think about it. :) |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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