coulomb/shard-wiki
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

research: XWiki deep dive (impl, extension interfaces, ecosystem); UC-38/39

Browse Source 
Deep dive into XWiki past the landscape scan: component/DI architecture,
document + class/object data model, oldcore, Hibernate storage + xwikircs
history, ObservationManager events, rendering pipeline, multi-wiki; the full
extension-interface surface (components, Java/wiki macros, script services,
UIX/UIXP, JAX-RS REST, event listeners, resource handlers); and the
extensions.xwiki.org ecosystem (XAR/JAR/WebJar, 900+ extensions).

Catalog:
- UC-38 make a wiki engine federation-capable via its native extension API
  (composable integration — first engine-side-direction UC; XWiki is proof)
- UC-39 attach a wiki-as-application-platform shard (bodiless typed pages)
- enrich UC-31 (ObservationManager event-driven sync), UC-34 (XObject model),
  UC-36 (xwikircs internal history) with concrete XWiki specifics

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Bernd Worsch
2026-06-13 19:20:42 +02:00
parent 0473c3f043
commit 27da940df1
3 changed files with 302 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files

35
research/260613-xwiki-deep-dive/README.md Normal file
View File

@@ -0,0 +1,35 @@
# 260613 — XWiki deep dive (implementation, extension interfaces, ecosystem)
Date: 2026-06-13
## What this is
A focused study of **XWiki** — the canonical "wiki-as-application-platform"
engine flagged in `research/260608-wikiengines-overview/`. Goes past the landscape
scan into XWiki's **implementation** (component/DI architecture, document data
model, storage, rendering, events), the **interfaces it exposes to extend the core
engine** (components, macros, UI extension points, script services, REST), and the
**extension ecosystem** (extensions.xwiki.org repository, XAR/JAR/WebJar types,
notable extensions).
Read through one lens: **what does XWiki teach shard-wiki about (a) adapting a
structured app-platform engine as a shard, and (b) how a host engine can become
federation-capable through its own extension mechanism** (INTENT *composable
integration*).
Complements:
- `research/260608-wikiengines-overview/` — the landscape scan that surfaced XWiki
- `research/260608-federation-concepts/` — already covered XWiki's ActivityPub extension
## Contents
| Path | Role |
|------|------|
| `findings.md` | Architecture, extension-interface catalog, ecosystem, capability profile, INTENT mapping, UC seeds, sources |
## Status
Initial deep dive complete. Two new use cases promoted to
`spec/UseCaseCatalog.md` (UC-38, UC-39); existing UC-34/UC-36/UC-31 enriched with
XWiki specifics. Adapter-contract implications feed
`workplans/SHARD-WP-0002-federation-architecture.md`.

217
research/260613-xwiki-deep-dive/findings.md Normal file
View File

@@ -0,0 +1,217 @@
# Findings — XWiki: implementation, extension interfaces, ecosystem
Date: 2026-06-13 · Status: research draft
Scope: XWiki as **prior art for two shard-wiki concerns** — (1) attaching a
structured "wiki-as-application-platform" engine as a shard, and (2) how an engine
exposes extension interfaces rich enough to *host* a federation adapter
(INTENT *composable integration*). Sources are XWiki's own dev docs, the
DeepWiki code analysis of `xwiki/xwiki-platform`, and the extensions repository.
**Complements:** `research/260608-wikiengines-overview/` (landscape) and
`research/260608-federation-concepts/` §3.2 (XWiki ActivityPub).
---
## 1. What XWiki is
A **programmable, component-based wiki platform** (Java/Jakarta EE, Hibernate ORM)
that blurs wiki and lightweight application platform. Pages are not just prose:
they carry **typed structured objects**, so an XWiki page can be a form, a record,
or a small application. This is the defining property the landscape scan flagged —
and the reason XWiki is the hardest case for shard-wiki's Markdown-first page model.
## 2. Implementation architecture
### 2.1 Component system (the spine)
- **Dependency-injection component model.** Components are interfaces (roles)
discovered via `META-INF/components.txt` and instantiated by a `ComponentManager`.
Implementations declare `@Component`, an optional `@Named` **role hint**, and
`@Singleton`. No interface→impl dependency — impls can ship in separate JARs and
**replace defaults at runtime**.
- Core replaceable roles include `XWikiStoreInterface` (storage), `ObservationManager`
(events), `XWikiRightService` (authorization), `XWikiAuthService` (authentication).
### 2.2 oldcore vs modular platform
- `xwiki-platform-oldcore` holds the foundational document model, persistence, and
legacy APIs (`com.xpn.xwiki.*`). A bridge connects it to the newer component world
to avoid circular dependencies.
- Newer modules layer on top: `model` (entity references), `rendering`, `security`,
`web` (HTTP actions/templates), `search-solr`.
### 2.3 Data model — document-centric + class/object
- Central entity: **`XWikiDocument`**, addressed by `DocumentReference`
(wiki / space / page). Content is parsed into an **XDOM** (rendering tree).
- **Structured data via a class-object pattern** (OOP-like):
- `BaseClass` / **XClass** — schema (field definitions), like a class declaration
- `BaseObject` / **XObject** — an instance conforming to a class, attached to a page
- `PropertyClass` / `BaseProperty` — field definition / value
- Property types: String, LargeString, Date, Number, List, …
- A single page can hold content **plus N typed objects** plus attachments. This is
the structural fact shard-wiki must represent without flattening.
### 2.4 Storage & history
- Two-tier: **`XWikiCacheStore`** over **`XWikiHibernateStore`** (Hibernate, multi-DB).
- Tables: `xwikidoc`, `xwikiobject`, `xwikiproperties`, `xwikiattachment`, and
**`xwikircs`** — internal **RCS-style version history**. History is real but
**engine-internal and non-portable** (directly relevant to shard-wiki UC-36).
### 2.5 Events & rendering
- **`ObservationManager`** event bus: cancelable (`DocumentCreatingEvent`,
`DocumentUpdatingEvent`, `DocumentDeletingEvent`) and post-facto
(`DocumentCreatedEvent`, `DocumentUpdatedEvent`, …). Listeners are components —
a natural **change-notification source for incremental sync**.
- **Rendering pipeline:** source syntax → parse → XDOM → transformations (macros) →
serialize (HTML, PDF, …). Pluggable parsers/renderers; XWiki can parse **Markdown**
as an input syntax even though its native syntax differs.
### 2.6 Multi-wiki
- One installation hosts many wikis (`WikiReference`), each with separate documents
and configuration — XWiki's own multi-tenancy, conceptually adjacent to
shard-wiki's root-entity/tenant boundary.
### 2.7 APIs & security
- **Dual API surface:** internal `com.xpn.xwiki.*` (full power) and script
`com.xpn.xwiki.api.*` (wrapped, enforces **programming rights** and view rights).
Privilege is enforced at the script boundary, not the storage boundary.
## 3. Interfaces to extend the core engine
XWiki's extensibility is unusually layered. From lowest/most-powerful to highest:
| # | Mechanism | What it extends | How |
|---|-----------|-----------------|-----|
| 1 | **Components** | anything | implement a role interface, `@Component` + `@Named` hint; ship in a JAR with `components.txt`; can override defaults (store, auth, rights) |
| 2 | **Rendering macros (Java)** | content processing | register `Macro.class` role + hint; participates in the XDOM transformation pipeline |
| 3 | **Wiki macros** | content processing | a wiki page following a spec — **no Java, no compile**; in-wiki authoring |
| 4 | **Script services** | scripting API | implement `org.xwiki.script.service.ScriptService`; exposed to Velocity/Groovy as `$services.<hint>` |
| 5 | **UI Extensions (UIX)** at **UI Extension Points (UIXP)** | the interface, no skin edit | UIX stored as XObjects of `XWiki.UIExtensionClass` (label/target/icon); injected at named hooks (since v4.2), e.g. `org.xwiki.platform.panels.Applications` |
| 6 | **REST API (JAX-RS)** | remote integration | resources for pages, spaces, **objects**, classes, attachments, comments, tags, annotations, users/groups, **history**; custom JAX-RS resources can be added |
| 7 | **Event listeners** | reactive behavior | register a component on `ObservationManager` to react to document lifecycle events |
| 8 | **Resource reference handlers** | new URL/resource types | implement `ResourceReferenceHandler` on the root component manager |
| 9 | **Skins / templates / Velocity** | presentation | Flamingo skin macros, templates |
Two things stand out for shard-wiki: (a) the **component model lets an extension
replace authentication, authorization, and storage** — i.e. an XWiki instance could
delegate auth exactly as shard-wiki's blueprint prescribes; (b) the **REST API plus
event bus** give a federation adapter both a transport (read/write pages+objects+
history) and a push-based freshness signal.
## 4. Extension ecosystem
- **`extensions.xwiki.org`** repository: **900+ extensions** (applications, macros,
skins, panels, themes, legacy plugins). Browsed/installed/upgraded at runtime via
the **Extension Manager Application** from the admin UI.
- **Extension types:**
- **XAR** — a package of wiki pages (an application, a wiki macro, or a snippet)
- **JAR** — server-side Java: **components and script services**
- **WebJar** — JAR of web resources (JS/CSS/Less)
- **"Plugin" (legacy) vs Component (modern):** the old plugin API is superseded by
the component system; new code is components.
- **Notable extensions** (relevance to shard-wiki in parentheses):
- **AppWithinMinutes** — build structured apps (XClass+XObjects) from the UI
(→ pages-as-records, the UC-39 case)
- **LDAP / Active Directory** and **Entra ID (Azure AD)** authentication
(→ confirms pluggable `XWikiAuthService`; mirrors shard-wiki's delegated authn)
- **ActivityPub** — fediverse federation (→ adapter transport, cf. UC-31)
- **LiveData / LiveTable** — queryable tabular views over XObjects
- draw.io diagrams, PDF viewer, Task Manager, Blog — content/app breadth
## 5. XWiki as a shard — capability profile
Read through shard-wiki's capability-aware adapter lens:
| Capability | XWiki | Note |
|------------|-------|------|
| Read | ✓ | REST + render to HTML/Markdown |
| Write | ✓ | REST PUT page/object; **per-document** granularity (page + its objects) |
| Structured payload | ✓✓ | XObjects/XClass — *richer* than Markdown; must not be flattened (UC-34/UC-39) |
| Version/diff | ✓ (internal) | `xwikircs`; **not git-portable** → coordination journal supplies that (UC-36) |
| Merge | partial | no native git-style 3-way merge |
| Change events | ✓ | `ObservationManager` → push-based sync/freshness (enriches UC-31) |
| Auth model | pluggable | `XWikiAuthService`/`XWikiRightService` replaceable — authorize through shard-wiki core, don't trust engine ACLs |
| Federation hooks | ✓✓ | component + REST + UIX make XWiki able to **host** a shard-wiki adapter (UC-38) |
| Multi-tenancy | ✓ | `WikiReference` farm → multiple shards / root entities |
## 6. Mapping to shard-wiki INTENT (compare, do not equate)
### 6.1 Reinforcements
| Observation | INTENT principle |
|-------------|------------------|
| Pages = content + typed XObjects | **Markdown-first, backend-neutral** must carry structure, not flatten (UC-34/39) |
| `xwikircs` internal-only history | **Git-addressable coordination** adds the portable layer (UC-36) |
| Pluggable `XWikiAuthService` | **authorization in core, authentication delegated** — XWiki already does exactly this |
| Component + REST + UIX extension surface | **composable integration** — engine becomes federation-capable via its own API (UC-38) |
| `ObservationManager` events | **explicit provenance/freshness** via push, not poll (UC-31, UC-24) |
| `WikiReference` multi-wiki | root-entity / tenant boundary has prior art |
### 6.2 Deliberate divergences (design bugs if conflated)
| XWiki assumption | shard-wiki correction |
|------------------|----------------------|
| Native XWiki syntax + macro render is the page | shard-wiki keeps **Markdown-first**; engine render stays out of core, structure travels as metadata |
| ACLs/rights live in the engine DB | **authorize in core**; engine rights are advisory, not trusted |
| History is the engine's RCS table | **coordination journal** is space-level and git-backed |
| Federation = an XWiki extension talking to other XWikis | shard-wiki federates **heterogeneous** backends; XWiki is one shard among many |
| App = XObjects rendered by XWiki | shard-wiki must represent records **without** depending on XWiki to render them |
### 6.3 What XWiki teaches that shard-wiki should not lose
1. **A clean role/hint component model** is what makes auth/store/rights swappable —
shard-wiki's adapter contract should be similarly role-based and override-friendly.
2. **Structured objects are first-class**, not an afterthought — the page model needs
a typed-metadata escape hatch from day one.
3. **An engine with a real extension API can host the adapter itself** — the cheapest
path to a high-fidelity shard is engine-side, not screen-scraping.
## 7. Use-case seeds → catalog (promoted 2026-06-13)
| Seed | Catalog UC | Disposition |
|------|------------|-------------|
| Engine hosts a federation adapter via its native extension API | **UC-38** (new) | composable integration — first UC for the engine-side direction |
| Attach a wiki-as-application-platform shard (pages are typed records/forms) | **UC-39** (new) | extends UC-34 toward bodiless structured pages |
| Structured page carries semantic data | UC-34 | enriched with XObject/XClass concretes |
| Internal-only revision history | UC-36 | enriched with `xwikircs` example |
| Subscribe to remote shard changes | UC-31 | enriched with `ObservationManager` event-driven transport |
## 8. Open questions (for spec / workplans)
1. **Page-model representation of XObjects** — typed frontmatter, sidecar file, or
opaque provenance blob? (shared with `wikiengines` §6 Q1; XWiki makes it urgent)
2. **Bodiless record pages** — does shard-wiki's page model require a Markdown body,
or can a page be purely structured (AppWithinMinutes apps)?
3. **Adapter placement** — engine-side extension (high fidelity, needs deploy access)
vs external REST adapter (zero engine change, lower fidelity). Both? Capability-gated?
4. **Event transport** — consume `ObservationManager` via a JAR listener, or poll REST
history? Affects freshness guarantees (UC-31/UC-24).
5. **Rights mapping** — translate XWiki `XWikiRightService` rights into shard-wiki
actions (read/write/patch/merge/administer), or ignore and authorize purely in core?
## 9. Sources
| Source | URL |
|--------|-----|
| XWiki — Developer Guide | https://www.xwiki.org/xwiki/bin/view/Documentation/DevGuide/ |
| XWiki — Creating XWiki Components | https://www.xwiki.org/xwiki/bin/view/Documentation/DevGuide/Tutorials/WritingComponents/ |
| XWiki — Available Extension Points | https://www.xwiki.org/xwiki/bin/view/Documentation/DevGuide/ExtensionPoint/ |
| XWiki — UI Extension Point Tutorial | https://www.xwiki.org/xwiki/bin/view/Documentation/DevGuide/Tutorials/UIXTutorial/ |
| XWiki — Wiki Macro Tutorial | https://www.xwiki.org/xwiki/bin/view/Documentation/DevGuide/Tutorials/WritingMacros/WikiMacroTutorial/ |
| XWiki — RESTful API | https://www.xwiki.org/xwiki/bin/view/Documentation/UserGuide/Features/XWikiRESTfulAPI |
| XWiki Rendering — Writing a Macro | https://rendering.xwiki.org/xwiki/bin/view/Main/ExtendingMacro |
| Extension Manager Application | https://extensions.xwiki.org/xwiki/bin/view/Extension/Extension%20Manager%20Application |
| Extension Module — Extensions/types | https://extensions.xwiki.org/xwiki/bin/view/Extension/Extension%20Module/Extensions/ |
| DeepWiki — xwiki/xwiki-platform (code analysis) | https://deepwiki.com/xwiki/xwiki-platform |
| Mancinelli — Overview of XWiki's RESTful API | http://blog.fabio.mancinelli.me/2011/03/07/XWikis_RESTful_API.html |
| shard-wiki — wiki engines overview | `research/260608-wikiengines-overview/findings.md` |
| shard-wiki — federation concepts | `research/260608-federation-concepts/findings.md` |
---
## 10. Traceability
| This document section | Informs (future) |
|-----------------------|------------------|
| §2 architecture | adapter design for app-platform engines |
| §3 extension interfaces | UC-38 engine-side adapter; composable-integration API shape |
| §5 capability profile | adapter capability-profile vocabulary (`SHARD-WP-0002`) |
| §6 INTENT mapping | architecture-blueprint guardrails |
| §7 UC seeds | `spec/UseCaseCatalog.md` (UC-38, UC-39; UC-31/34/36 enrichment) |
| §8 open questions | spec — page model for structured/bodiless pages |