Skip to content

MIGRATION.md

Latest commit

 

History

History
139 lines (93 loc) · 9.09 KB

MIGRATION.md

File metadata and controls

139 lines (93 loc) · 9.09 KB
Raw

Migration Guide

Migrating from 7.0.0 to 7.1.0

7.1.0 is a cleanup release with three breaking packaging changes for consumers already on 7.0.0, plus additive features (full list in RELEASE_NOTES.md).

  1. OSGi runtime variant removed. If you consumed the OSGi bundles or called the OSGi-specific ServiceRegistry methods, see OSGi support removed below for the exact API delta and the bnd / pax-url wrap path.
  2. metaobjects-dynamic-core folded into metaobjects-metadata. Drop any com.metaobjects:metaobjects-dynamic-core dependency — its CoreObjectsMetaDataProvider now ships inside metaobjects-metadata. The value* / data* attribute extensions it used to contribute onto object.base (e.g. valueObjectType, dataBuilderClass, dataImmutable) have been removed — generated-object flavor is now derived from the codegen generator's configuration, not from metamodel attributes. If you authored any of those attributes in metadata, delete them.
  3. archetype / examples directories deleted. No action unless you referenced them as source.

Additive (opt-in) in 7.1.0: programmatic provider registration, the TemplateGenerator render API in metaobjects-render, codegen-spring hasFoo() presence helpers for nullable record fields, and codegen-kotlin text() mapping for jsonb-backed string fields.

Otherwise it is a version bump:

<version>7.1.0</version>

Migrating from 6.x to 7.0.0

7.0.0 is the first publish from the consolidated server/java/ reactor under the cross-language MetaObjects monorepo. Most consumers' migration is a version bump — the bulk of the work moved underneath the API. The full release notes are in RELEASE_NOTES.md.

Step 1 — bump the version

<dependency>
    <groupId>com.metaobjects</groupId>
    <artifactId>metaobjects-metadata</artifactId>
    <version>7.0.0</version>
</dependency>

Maven coordinates are unchanged from 6.x — com.metaobjects:* on Maven Central. Group IDs and artifact names stay the same except for new modules listed below.

Step 2 — module additions you can opt into

Five module additions in 7.0.0 (none required; opt in per stack):

Module When you need it
metaobjects-codegen-spring Generate Spring REST controllers + DTOs + JPA repositories + filter allowlists from metadata
metaobjects-codegen-kotlin Generate idiomatic Kotlin (entity / Exposed table / Spring controller / payload / validator / stored-proc) on KotlinPoet
metaobjects-render Mustache render + payload-VO codegen + drift-verify (the prompt-construction pillar)
metaobjects-metadata-ktx Kotlin facade over the Java metadata core
metaobjects-omdb-ktx Kotlin facade over OMDB

The metaobjects-dynamic-core module from 6.x is gone — its CoreObjectsMetaDataProvider now ships inside metaobjects-metadata. The value* / data* attribute extensions it once contributed onto object.base (dataBuilderClass, valueObjectType, dataImmutable, etc.) have since been removed: generated-object flavor is derived from the codegen generator's configuration rather than from metamodel attributes, so there is nothing for consumers to register or author. Consumers of the metaobjects-dynamic-core artifact coordinate should drop the dependency; any of those attributes still present in authored metadata should be deleted.

OSGi support removed

The OSGi runtime variant (OSGIServiceRegistry, BundleLifecycleManager, the maven-bundle-plugin packaging on every reactor module) was dropped in 7.1.0. The artifacts are now plain JARs. Decision rationale: ADR-0012.

Consumers running inside an OSGi container can still wrap MetaObjects' JARs with bnd / pax-url to produce bundles with the appropriate manifest headers — the code itself works in any classloader environment. What changes:

  • <packaging>bundle</packaging> is now <packaging>jar</packaging> on every module; no Bundle-SymbolicName / Export-Package manifest entries are emitted.
  • ServiceRegistry.isOSGIEnvironment(), onBundleEvent(Object), cleanupForBundle(Object), isBundleLifecycleActive(), getBundleLifecycleStatus() are gone from the interface (they had no callers outside the OSGi implementation itself).
  • StandardServiceRegistry is the only ServiceRegistry implementation.
  • ServiceRegistryFactory.create() and .getDefault() return a StandardServiceRegistry. The OSGi auto-detection / createOSGI(BundleContext) factories are gone.

The WeakReference patterns in MetaData, HybridCache, and StandardServiceRegistry stay — they are general ClassLoader-leak prevention, not OSGi-specific.

Programmatic provider registration (new in 7.1.0)

MetaDataRegistry now ships a compose(...) / registerProviders(...) API that mirrors the cross-port pattern already in TypeScript (composeRegistry(providers)) and Python (compose_registry(providers)):

MetaDataRegistry registry = MetaDataRegistry.compose(List.of(
    new CoreTypesProvider(),
    new MyDomainProvider(),
    new MyTenantProvider()
));

Use this when ServiceLoader is awkward — embedded scenarios, fat-jar consolidation, GraalVM native-image, conditional / tenant-driven composition, and tests that want to inject a fixture provider without touching META-INF/services. Strict error contract matches the cross-port spec: duplicate provider id, missing dependency, or dependency cycle throws MetaDataException with the matching ErrorCode.

The default MetaDataRegistry.getInstance() still uses ServiceLoader auto-discovery with warn-and-continue semantics — no change for the typical app.

The metaobjects-codegen-mustache and metaobjects-codegen-plantuml modules from 6.x continue unchanged.

Step 3 — source paradigm v2 (ADR-0007)

If your 6.x metadata declared a writable table via the legacy source.dbTable subtype, or a view via source.dbView, the canonical form is now:

{ "object.entity": {
    "name": "Subscriber",
    "children": [
      { "source.rdb": {
          "@kind": "table",
          "@table": "subscribers",
          "@schema": "public"
      }},
      { "field.string": {
          "name": "email",
          "@column": "email_address"
      }}
    ]
}}
  • Source subtype: source.rdb (only) — @kind selects table / view / materializedView / storedProc / tableFunction. Read-only-ness is derived from @kind. Multi-source per object via @role (exactly one primary).
  • Source physical name: @table (replaces @name on the source).
  • Field physical name: @column (replaces @dbColumn).
  • DB schema: @schema on the source (public default for Postgres; SQLite rejects non-default values).
  • Referential actions on relationships: @onDelete / @onUpdate on the relationship, not on the source.

The legacy source.dbTable / source.dbView subtypes and the @dbColumn attribute are retired.

Step 4 — FR5 actionable loader errors (ADR-0009)

Loader errors now ship as structured envelopes with errorCode, path, position, message, and hint fields. If you parse loader-error output, switch to the envelope shape — the legacy flat-string format is gone.

Step 5 — verify and prompt-construction (optional)

mvn meta:verify extends drift detection beyond entity codegen to prompt templates, output parsers, and database schema. Adopt it where you ship typed prompts or want compile-time gates against schema/code divergence.

The render pillar's payload-VO generator emits typed records for every template.input projection; FR-006 emits typed output parsers for every template.output schema. Both are opt-in additions — your existing entity codegen is unaffected.

Step 6 — reactor housekeeping

The archetype and examples directories are still on disk as scaffold source but are no longer in the 7.0.0 reactor and are not deployed to Central. If you depended on them as Maven artifacts, copy the scaffold material into your own project tree.

Migrating from 5.x to 6.x

The 5.x → 6.x migration changed the Maven group ID from com.draagon to com.metaobjects and refactored the package namespace from com.draagon.meta.* to com.metaobjects.*. The 6.x release notes have the per-package mapping. The recommended path for 5.x consumers today is 5.x → 7.0.0 directly — there is no benefit to landing at an intermediate 6.x version.

For the 5.x → 6.x package rename, replace com.draagon group IDs and com.draagon.meta.* import statements with com.metaobjects and com.metaobjects.* respectively, then proceed with the 6.x → 7.0.0 steps above.

Getting help