Principle:Apache Shardingsphere Persistence Facade Construction
| Knowledge Sources | |
|---|---|
| Domains | Cluster_Mode, Distributed_Coordination |
| Last Updated | 2026-02-10 00:00 GMT |
Overview
Building a layered facade pattern to abstract persistence operations provides a unified API for metadata, rules, and configuration storage regardless of the underlying repository technology.
Description
Persistence Facade Construction is the principle of organizing all persistence-related services behind a hierarchical facade structure. In Apache ShardingSphere, this is realized through two main facade classes:
- MetaDataPersistFacade -- the lower-level facade that directly wraps the PersistRepository and exposes domain-specific persistence services for version tracking, data source units, database metadata, database rules, global rules, properties, and statistics.
- PersistServiceFacade -- the higher-level facade that composes MetaDataPersistFacade with additional services for state management, qualified data source state, and mode-specific persistence (loaded via SPI).
This two-tier structure achieves several design goals:
- Encapsulation: Consumers of the facade never interact with the raw PersistRepository directly. All read/write operations are mediated through typed, domain-specific service objects.
- Single Construction Point: Each facade is constructed once during initialization and passed through the system. The constructor wires all internal services to the same repository instance, ensuring consistency.
- Composition Over Inheritance: Rather than inheriting from the repository, the facades compose multiple service objects, each responsible for a specific domain (data sources, rules, metadata, etc.).
- Mode Abstraction: The PersistServiceFacade constructor uses SPI to load a ModePersistServiceFacade appropriate for the current mode (Standalone or Cluster), enabling mode-specific persistence behavior without changing the facade's public interface.
- Resource Lifecycle: PersistServiceFacade implements AutoCloseable, ensuring that the mode facade and repository are properly shut down when the context manager is closed.
The internal service hierarchy of MetaDataPersistFacade is:
| Service | Type | Responsibility |
|---|---|---|
| versionService | VersionPersistService | Tracks configuration version numbers |
| dataSourceUnitService | DataSourceUnitPersistService | Persists and loads data source pool configurations |
| databaseMetaDataFacade | DatabaseMetaDataPersistFacade | Manages database and schema metadata persistence |
| databaseRuleService | DatabaseRulePersistService | Persists per-database rule configurations |
| globalRuleService | GlobalRulePersistService | Persists global rule configurations |
| propsService | PropertiesPersistService | Persists system properties |
| statisticsService | StatisticsPersistService | Persists cluster statistics data |
Usage
Use this principle when initializing the cluster context manager. The MetaDataPersistFacade is constructed first (receiving the repository) and is then used by MetaDataContextsFactory to load or persist metadata. The PersistServiceFacade is constructed later as part of the ContextManager assembly, wrapping the metadata facade with state and mode-specific services.
Theoretical Basis
The Persistence Facade Construction principle applies classic facade and composition patterns to distributed persistence:
1. Facade Pattern
A facade provides a simplified interface to a complex subsystem. Here, the MetaDataPersistFacade hides the complexity of seven distinct persistence services behind a single object:
FUNCTION constructMetaDataPersistFacade(repository, persistSchemasEnabled):
facade = new MetaDataPersistFacade()
facade.versionService = new VersionPersistService(repository)
facade.dataSourceUnitService = new DataSourceUnitPersistService(repository)
facade.databaseMetaDataFacade = new DatabaseMetaDataPersistFacade(repository, facade.versionService, persistSchemasEnabled)
facade.databaseRuleService = new DatabaseRulePersistService(repository)
facade.globalRuleService = new GlobalRulePersistService(repository, facade.versionService)
facade.propsService = new PropertiesPersistService(repository, facade.versionService)
facade.statisticsService = new StatisticsPersistService(repository)
RETURN facade
2. Hierarchical Composition
The PersistServiceFacade composes the MetaDataPersistFacade with additional services, creating a layered architecture:
FUNCTION constructPersistServiceFacade(repository, modeConfig, metaDataContextManager):
facade = new PersistServiceFacade()
facade.metaDataFacade = new MetaDataPersistFacade(repository, persistSchemasEnabled)
facade.stateService = new StatePersistService(repository)
facade.qualifiedDataSourceStateService = new QualifiedDataSourceStatePersistService(repository)
facade.modeFacade = loadModeFacadeViaSPI(modeConfig.getType(), metaDataContextManager, repository)
RETURN facade
3. Constructor Telescoping with Defaults
The MetaDataPersistFacade provides two constructors: a full constructor accepting persistSchemasEnabled and a convenience constructor that defaults it to true. This reduces boilerplate for the common case while preserving configurability:
CONSTRUCTOR MetaDataPersistFacade(repository):
CALL MetaDataPersistFacade(repository, persistSchemasEnabled=true)
4. Repository Sharing
All services within both facades share the same PersistRepository instance. This ensures that persistence operations are consistent and that connection resources are not duplicated.