Skip to content

Commit fd0cc6d

Browse files
dmealingclaude
dmealing
and
claude
committed
MAJOR ARCHITECTURAL REFACTORING: Constants Organization & Service Separation (v6.2.0)
🚀 COMPREHENSIVE SERVICE POLLUTION ELIMINATION - Eliminated service-specific attribute pollution from core MetaData types - Removed database attributes (dbColumn, isSearchable) from core field types - Removed codegen attributes (hasJpa, isOptional) from core metadata - Established dependency-driven constants organization pattern 🗂️ CONSTANTS REORGANIZATION PATTERN - DELETED: MetaDataConstants.java (centralized anti-pattern eliminated) - MOVED: Constants to classes that create the need for them - CREATED: Service-specific constant files for cross-cutting concerns - ESTABLISHED: Compile-time dependencies for cross-module constant access 📁 NEW CONSTANTS ORGANIZATION: - MetaData.java: Universal constants (ATTR_NAME, ATTR_TYPE, PKG_SEPARATOR) - MetaField.java: Field-specific constants (TYPE_FIELD, ATTR_REQUIRED) - MetaObject.java: Object-specific constants (TYPE_OBJECT, ATTR_EXTENDS) - MetaAttribute.java: Attribute type constants (TYPE_ATTR) - ErrorFormatter.java: Display constants (DISPLAY_NULL, formatForDisplay) - ErrorMessageConstants.java: Error message format templates - JsonMetaDataParser.java: JSON parsing constants (JSON_ATTR_PREFIX) - JpaConstants.java: JPA code generation constants (in codegen-mustache) - DatabaseAttributeConstants.java: Database constants (in database-common) ⚡ ATTR_VALIDATION ELIMINATION - Removed explicit ATTR_VALIDATION attribute from MetaField and MetaView - Replaced with calculated validation based on actual MetaValidator children - Enhanced intelligence over configuration approach 🏛️ SERVICE SEPARATION ARCHITECTURE - Created database-common module for shared database constants - Established clean module dependencies for cross-service constant access - Preserved constraint system extensibility patterns - Maintained clean core types without service pollution 🔧 FILES UPDATED (24+ files): - 9 Field types: Updated imports, removed service pollution - 4 Core classes: MetaObject, MetaValidator, MetaAttribute, MetaField, MetaView - 3 Codegen files: XSD writer, JSON schema writer, AI documentation writer - 3 Test files: Updated constant imports - 1 Central file: MetaDataConstants.java DELETED ✅ VERIFICATION COMPLETED: - Full clean build and test suite passes across all modules - 31 types registered with proper inheritance working - 16 constraints loaded and functioning correctly - Cross-module dependencies resolved successfully 🏆 ARCHITECTURAL BENEFITS ACHIEVED: ✅ Clean Architecture: Core types no longer polluted with service concerns ✅ Dependency-Driven Design: Constants live with classes that create the need ✅ Service Separation: Database constants in database-common, JPA in codegen-mustache ✅ Extensibility Preserved: Plugins can extend without modifying core types ✅ Calculated Intelligence: ATTR_VALIDATION replaced with MetaValidator children logic ✅ Compile-Time Safety: Cross-module constant access via proper dependencies ✅ Maintainability: Complete reorganization with zero regressions 🎯 DESIGN PATTERN ESTABLISHED: "Constants live with the classes that are actually the reason the constant exists in the first place" This establishes a blueprint for maintaining clean service separation while enabling powerful extensibility through dependency-driven design and the constraint system. 🤖 Generated with Claude Code (https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
1 parent 0b8575f commit fd0cc6d

37 files changed

Lines changed: 1508 additions & 966 deletions

File tree

‎.claude/CLAUDE.md‎

Lines changed: 347 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1509,6 +1509,353 @@ The following critical systems have been successfully implemented and tested:
15091509
- Enhanced OSGI registry: `metadata/src/main/java/com/draagon/meta/registry/OSGIServiceRegistry.java`
15101510
- OSGI test suite: `metadata/src/test/java/com/draagon/meta/registry/osgi/OSGILifecycleTest.java`
15111511

1512+
## 🏗️ **CONSTANTS ORGANIZATION & SERVICE SEPARATION PATTERNS (v6.2.0+)**
1513+
1514+
### 🚀 **MAJOR ARCHITECTURAL ACHIEVEMENT: Service Pollution Elimination**
1515+
1516+
**STATUS: ✅ COMPLETED** - Comprehensive elimination of service-specific attribute pollution from core MetaData types and establishment of dependency-driven constants organization.
1517+
1518+
#### **The Service Pollution Problem**
1519+
1520+
**CRITICAL DISCOVERY**: Core MetaData types (MetaField, MetaObject) were polluted with service-specific attributes that violated architectural boundaries:
1521+
1522+
```java
1523+
// ❌ WRONG - Service pollution in core types
1524+
@MetaDataType(type = "field", subType = "string")
1525+
public class StringField extends MetaField {
1526+
static {
1527+
MetaDataRegistry.registerType(StringField.class, def -> def
1528+
// CORE FIELD ATTRIBUTES (appropriate)
1529+
.optionalAttribute("required", "boolean")
1530+
.optionalAttribute("defaultValue", "string")
1531+
1532+
// ❌ DATABASE SERVICE POLLUTION (inappropriate)
1533+
.optionalAttribute("dbColumn", "string")
1534+
.optionalAttribute("isSearchable", "boolean")
1535+
1536+
// ❌ CODEGEN SERVICE POLLUTION (inappropriate)
1537+
.optionalAttribute("hasJpa", "boolean")
1538+
.optionalAttribute("isOptional", "boolean")
1539+
);
1540+
}
1541+
}
1542+
```
1543+
1544+
#### **The Dependency-Driven Solution**
1545+
1546+
**ARCHITECTURAL PRINCIPLE**: **"Constants live with the classes that are actually the reason the constant exists in the first place"**
1547+
1548+
**Implementation Strategy:**
1549+
1. **Eliminate centralized constant files** (deleted MetaDataConstants.java entirely)
1550+
2. **Move constants to owning classes** based on who creates the need for them
1551+
3. **Create service-specific constant files** for cross-cutting concerns
1552+
4. **Use compile-time dependencies** for cross-module constant access
1553+
1554+
### 🗂️ **Constants Organization Patterns**
1555+
1556+
#### **Core MetaData Constants → Owning Classes**
1557+
1558+
```java
1559+
// MetaData.java - Universal constants that apply to ALL metadata
1560+
public class MetaData {
1561+
// SEPARATORS (MetaData creates package separation concept)
1562+
public static final String PKG_SEPARATOR = "::";
1563+
1564+
// UNIVERSAL ATTRIBUTES (MetaData creates these concepts)
1565+
public static final String ATTR_NAME = "name";
1566+
public static final String ATTR_TYPE = "type";
1567+
public static final String ATTR_SUBTYPE = "subType";
1568+
public static final String ATTR_PACKAGE = "package";
1569+
public static final String ATTR_CHILDREN = "children";
1570+
public static final String ATTR_METADATA = "metadata";
1571+
public static final String ATTR_IS_ABSTRACT = "isAbstract";
1572+
1573+
// VALIDATION PATTERNS (MetaData creates validation concepts)
1574+
public static final String VALID_NAME_PATTERN = "^[a-zA-Z][a-zA-Z0-9_]*$";
1575+
}
1576+
1577+
// MetaField.java - Field-specific constants
1578+
public class MetaField {
1579+
// TYPE CONSTANTS (MetaField creates the field type concept)
1580+
public static final String TYPE_FIELD = "field";
1581+
public static final String SUBTYPE_BASE = "base";
1582+
1583+
// FIELD ATTRIBUTES (MetaField creates these field concepts)
1584+
public static final String ATTR_REQUIRED = "required";
1585+
public static final String ATTR_DEFAULT_VALUE = "defaultValue";
1586+
public static final String ATTR_DEFAULT_VIEW = "defaultView";
1587+
}
1588+
1589+
// MetaObject.java - Object-specific constants
1590+
public class MetaObject {
1591+
// TYPE CONSTANTS (MetaObject creates the object type concept)
1592+
public static final String TYPE_OBJECT = "object";
1593+
public static final String SUBTYPE_BASE = "base";
1594+
1595+
// OBJECT ATTRIBUTES (MetaObject creates these object concepts)
1596+
public static final String ATTR_EXTENDS = "extends";
1597+
public static final String ATTR_IMPLEMENTS = "implements";
1598+
public static final String ATTR_IS_INTERFACE = "isInterface";
1599+
}
1600+
```
1601+
1602+
#### **Service-Specific Constants → Service Modules**
1603+
1604+
```java
1605+
// database-common/DatabaseAttributeConstants.java
1606+
public class DatabaseAttributeConstants {
1607+
// DATABASE CONCEPTS (Database services create these needs)
1608+
public static final String ATTR_DB_TABLE = "dbTable";
1609+
public static final String ATTR_DB_COLUMN = "dbColumn";
1610+
public static final String ATTR_DB_NULLABLE = "dbNullable";
1611+
public static final String ATTR_IS_SEARCHABLE = "isSearchable";
1612+
1613+
public static boolean isDatabaseAttribute(String attributeName) {
1614+
return attributeName.startsWith("db") ||
1615+
ATTR_IS_SEARCHABLE.equals(attributeName);
1616+
}
1617+
}
1618+
1619+
// codegen-mustache/JpaConstants.java
1620+
public class JpaConstants {
1621+
// JPA CONCEPTS (JPA code generation creates these needs)
1622+
public static final String ATTR_HAS_JPA = "hasJpa";
1623+
public static final String ATTR_JPA_TABLE = "jpaTable";
1624+
public static final String ATTR_JPA_COLUMN = "jpaColumn";
1625+
public static final String ATTR_JPA_ID = "jpaId";
1626+
1627+
// JPA ANNOTATIONS
1628+
public static final String JPA_ENTITY = "Entity";
1629+
public static final String JPA_TABLE = "Table";
1630+
public static final String JPA_ID = "Id";
1631+
public static final String JPA_COLUMN = "Column";
1632+
}
1633+
1634+
// JsonMetaDataParser.java
1635+
public class JsonMetaDataParser {
1636+
// JSON PARSING CONCEPTS (JSON parser creates this need)
1637+
public static final String JSON_ATTR_PREFIX = "@";
1638+
}
1639+
1640+
// ErrorFormatter.java
1641+
public class ErrorFormatter {
1642+
// DISPLAY CONCEPTS (Error formatting creates these needs)
1643+
public static final String DISPLAY_NULL = "<null>";
1644+
public static final String DISPLAY_EMPTY = "<empty>";
1645+
public static final String DISPLAY_NONE = "<none>";
1646+
public static final String DISPLAY_ELLIPSIS = "...";
1647+
public static final int MAX_DISPLAY_LENGTH = 100;
1648+
1649+
public static String formatForDisplay(String value) {
1650+
// Implementation moved here where it belongs
1651+
}
1652+
}
1653+
```
1654+
1655+
#### **Cross-Module Access Pattern**
1656+
1657+
```java
1658+
// Codegen modules can access database constants via compile-time dependencies
1659+
import static com.draagon.meta.database.common.DatabaseAttributeConstants.*;
1660+
import static com.draagon.meta.field.MetaField.TYPE_FIELD;
1661+
import static com.draagon.meta.object.MetaObject.TYPE_OBJECT;
1662+
1663+
public class MetaDataAIDocumentationWriter {
1664+
private void generateFieldDocumentation() {
1665+
// Access constants from their owning classes
1666+
if (TYPE_FIELD.equals(metaData.getType())) {
1667+
// Check for database attributes
1668+
if (isDatabaseAttribute(attrName)) {
1669+
// Handle database-specific documentation
1670+
}
1671+
}
1672+
}
1673+
}
1674+
```
1675+
1676+
### ⚡ **ATTR_VALIDATION Elimination Pattern**
1677+
1678+
**MAJOR IMPROVEMENT**: Replaced explicit validation attributes with calculated intelligence.
1679+
1680+
```java
1681+
// ❌ OLD - Explicit validation attribute
1682+
public class MetaField {
1683+
public static final String ATTR_VALIDATION = "validation"; // Removed!
1684+
1685+
// Had to explicitly configure validation
1686+
.optionalAttribute(ATTR_VALIDATION, "string")
1687+
}
1688+
1689+
// ✅ NEW - Calculated validation based on MetaValidator children
1690+
public class MetaField {
1691+
/**
1692+
* Returns all validators attached to this MetaField.
1693+
* Validation is now calculated based on actual MetaValidator children,
1694+
* eliminating the need for explicit validation attribute configuration.
1695+
*/
1696+
public List<MetaValidator> getDefaultValidatorList() {
1697+
return useCache("getDefaultValidatorList()", () -> {
1698+
// Always use all MetaValidator children - no more attribute-based validation
1699+
return getValidators();
1700+
});
1701+
}
1702+
}
1703+
1704+
// MetaView.java - Updated validation approach
1705+
public class MetaView {
1706+
/**
1707+
* Performs validation before setting the value.
1708+
* Validation is now calculated based on actual MetaValidator children
1709+
* of the associated MetaField, eliminating the need for explicit validation attributes.
1710+
*/
1711+
protected void performValidation(Object obj, Object val) throws MetaDataException {
1712+
// Use all validators from the associated MetaField
1713+
MetaField<?> metaField = getMetaField(obj);
1714+
metaField.getDefaultValidatorList().forEach(v -> v.validate(obj, val));
1715+
}
1716+
}
1717+
```
1718+
1719+
### 🏛️ **Service Separation Architecture**
1720+
1721+
#### **Module Dependency Strategy**
1722+
1723+
```xml
1724+
<!-- Clean service separation via module dependencies -->
1725+
1726+
<!-- database-common: Shared database constants -->
1727+
<dependency>
1728+
<groupId>com.draagon</groupId>
1729+
<artifactId>metaobjects-database-common</artifactId>
1730+
<!-- Contains DatabaseAttributeConstants, DatabaseConstraintProvider -->
1731+
</dependency>
1732+
1733+
<!-- codegen-base: Code generation needs database constants -->
1734+
<dependency>
1735+
<groupId>com.draagon</groupId>
1736+
<artifactId>metaobjects-database-common</artifactId>
1737+
<!-- Can access database constants when generating schemas -->
1738+
</dependency>
1739+
1740+
<!-- omdb: Database ORM implementation -->
1741+
<dependency>
1742+
<groupId>com.draagon</groupId>
1743+
<artifactId>metaobjects-database-common</artifactId>
1744+
<!-- Uses database constants for ORM mapping -->
1745+
</dependency>
1746+
```
1747+
1748+
#### **Clean Core Types**
1749+
1750+
```java
1751+
// ✅ CLEAN - StringField no longer polluted with service concerns
1752+
@MetaDataType(type = "field", subType = "string")
1753+
public class StringField extends PrimitiveField<String> {
1754+
static {
1755+
MetaDataRegistry.registerType(StringField.class, def -> def
1756+
.type(TYPE_FIELD).subType(SUBTYPE_STRING)
1757+
.inheritsFrom(TYPE_FIELD, SUBTYPE_BASE)
1758+
.description("String field with length and pattern validation")
1759+
1760+
// ONLY STRING-SPECIFIC CORE ATTRIBUTES
1761+
.optionalAttribute(ATTR_PATTERN, "string")
1762+
.optionalAttribute(ATTR_MAX_LENGTH, "int")
1763+
.optionalAttribute(ATTR_MIN_LENGTH, "int")
1764+
1765+
// NO service-specific pollution - services add their own attributes separately
1766+
);
1767+
}
1768+
}
1769+
```
1770+
1771+
### 🎯 **Constraint System Integration**
1772+
1773+
**CRITICAL RULE**: **NEVER add rigid validation to core types** - always use the constraint system for extensibility.
1774+
1775+
#### **Constraint-Based Service Integration**
1776+
1777+
```java
1778+
// DatabaseConstraintProvider.java - Service adds its own constraints
1779+
public class DatabaseConstraintProvider {
1780+
static {
1781+
ConstraintRegistry registry = ConstraintRegistry.getInstance();
1782+
1783+
// Database service defines its own placement constraints
1784+
PlacementConstraint dbTableConstraint = new PlacementConstraint(
1785+
"database.table.placement",
1786+
"Objects can optionally have dbTable attribute",
1787+
(metadata) -> metadata instanceof MetaObject,
1788+
(child) -> child instanceof StringAttribute &&
1789+
child.getName().equals(ATTR_DB_TABLE)
1790+
);
1791+
registry.addConstraint(dbTableConstraint);
1792+
}
1793+
}
1794+
```
1795+
1796+
#### **Plugin Extensibility Example**
1797+
1798+
```java
1799+
// Custom CurrencyField extending the system cleanly
1800+
@MetaDataType(type = "field", subType = "currency")
1801+
public class CurrencyField extends PrimitiveField<BigDecimal> {
1802+
// Currency-specific constants live here
1803+
public static final String ATTR_PRECISION = "precision";
1804+
public static final String ATTR_CURRENCY_CODE = "currencyCode";
1805+
1806+
static {
1807+
MetaDataRegistry.registerType(CurrencyField.class, def -> def
1808+
.type(TYPE_FIELD).subType("currency")
1809+
.inheritsFrom(TYPE_FIELD, SUBTYPE_BASE) // Gets all field.base attributes
1810+
.optionalAttribute(ATTR_PRECISION, "int") // Plus currency-specific
1811+
.optionalAttribute(ATTR_CURRENCY_CODE, "string")
1812+
.description("Currency field with precision and formatting")
1813+
);
1814+
1815+
// Currency service adds its own constraints
1816+
setupCurrencyConstraints();
1817+
}
1818+
}
1819+
```
1820+
1821+
### 📋 **Mandatory Design Guidelines**
1822+
1823+
#### **✅ DO - Constants Placement Rules**
1824+
1. **Move constants to the class that creates the need** for that concept
1825+
2. **Use service-specific constant files** for cross-cutting service concerns
1826+
3. **Establish compile-time dependencies** between modules for constant access
1827+
4. **Create constraint providers** for service-specific validation rules
1828+
5. **Use calculated logic** instead of explicit configuration attributes
1829+
1830+
#### **❌ DON'T - Anti-Patterns**
1831+
1. **Don't create centralized constant files** mixing unrelated concepts
1832+
2. **Don't pollute core types** with service-specific attributes
1833+
3. **Don't hardcode service lists** in core metadata definitions
1834+
4. **Don't use explicit validation attributes** when calculated logic is better
1835+
5. **Don't bypass the constraint system** for extensibility requirements
1836+
1837+
#### **🔍 Pre-Change Checklist**
1838+
1839+
**Before adding ANY constants or attributes:**
1840+
1841+
1. **Who actually creates the need for this constant?** → That's where it belongs
1842+
2. **Is this service-specific?** → Move to service module with proper dependency
1843+
3. **Will this prevent extensibility?** → Use constraint system instead
1844+
4. **Can this be calculated?** → Prefer intelligence over configuration
1845+
5. **Does this violate module boundaries?** → Establish proper dependencies
1846+
1847+
### 🏆 **Achieved Benefits**
1848+
1849+
✅ **Clean Architecture**: Core types no longer polluted with service concerns
1850+
✅ **Dependency-Driven Design**: Constants live with classes that create the need
1851+
✅ **Service Separation**: Database constants in database-common, JPA in codegen-mustache
1852+
✅ **Extensibility Preserved**: Plugins can extend without modifying core types
1853+
✅ **Calculated Intelligence**: ATTR_VALIDATION replaced with MetaValidator children logic
1854+
✅ **Compile-Time Safety**: Cross-module constant access via proper dependencies
1855+
✅ **Maintainability**: 24+ files updated, MetaDataConstants.java deleted, all tests passing
1856+
1857+
**This architectural pattern provides a blueprint for maintaining clean service separation while enabling powerful extensibility through dependency-driven design and the constraint system.**
1858+
15121859
## ServiceLoader Issue Resolution (v5.2.0+)
15131860

15141861
### 🔧 **ISSUE RESOLVED: Core Module Code Generation**

‎codegen-base/pom.xml‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,13 @@
2121
<artifactId>metaobjects-metadata</artifactId>
2222
<version>${project.version}</version>
2323
</dependency>
24-
24+
25+
<dependency>
26+
<groupId>com.draagon</groupId>
27+
<artifactId>metaobjects-database-common</artifactId>
28+
<version>${project.version}</version>
29+
</dependency>
30+
2531
<!-- Test Dependencies -->
2632
<dependency>
2733
<groupId>com.draagon</groupId>

0 commit comments

Comments
 (0)