Repository navigation
java(plugins): extend building-plugins guide with ecosystem conventions - #2870
Merged
Merged
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. :) |
![hyperspace-pr-bot[bot]](https://avatars.githubusercontent.com/u/2531208?s=60&v=4){kind=small}
Contributor
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
Akatuoro
reviewed
Oct 29, 2026
Co-authored-by: hyperspace-pr-bot[bot] <209611008+hyperspace-pr-bot[bot]@users.noreply.github.com>
Contributor
Author
|
Internal fragment for the SAP-specific repo hygiene details extracted from this PR: https://github.tools.sap/cap/docs/pull/2737 |
- Use {{ versions.java_services }} instead of hardcoded CAP Java version
- Fix undefined `runtime` variable; use configurer.getCdsRuntime()
- Add missing eventHandlers() registration alongside services()
- Mention that generated service interfaces can be used when the plugin compiles CDS
- Move local integration-test setup into Configuration & Enablement as a core feature
- Strip SAP-internal repo hygiene details (Artifactory, Black Duck) into internal fragment
via anchor #building-plugins-repo-hygiene-internal (see cap/docs#2737)
Akatuoro
approved these changes
Oct 30, 2026
Akatuoro
reviewed
Oct 30, 2026
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
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