xmi 0.3.21 → 0.5.0

data/README.adoc

@@ -6,6 +6,13 @@ This Ruby object mapper is a module designed to convert XMI (XML Metadata Interc
 
 == Installation
 
+=== Requirements
+
+* Ruby 3.0 or later
+* lutaml-model 0.8.0 or later (for `Lutaml::Xml::Namespace` support)
+
+=== Installing the gem
+
 Add this line to your application's Gemfile:
 
 [source,ruby]
@@ -37,7 +44,7 @@ To convert XMI file into Ruby objects, run:
 ----
 xml = "path/to/your/file.xmi"
 xml_content = File.read(xml)
-xmi_root_model = Xmi::Sparx::SparxRoot.parse_xml(xml_content)
+xmi_root_model = Xmi::Sparx::Root.parse_xml(xml_content)
 ----
 
 This method takes the path to an XMI file and generate the Ruby objects.
@@ -52,12 +59,12 @@ Xmi::EaRoot.load_extension("path/to/your/extension.xml")
 
 xml = "path/to/your/file.xmi"
 xml_content = File.read(xml)
-xmi_root_model = Xmi::Sparx::SparxRoot.parse_xml(xml_content)
+xmi_root_model = Xmi::Sparx::Root.parse_xml(xml_content)
 ----
 
 `Xmi::EaRoot.load_extension` takes the path to an XML file and generate the
 Ruby classes and modules defined in XML file dynamically.
-Then, you can generate Ruby objects by `Xmi::Sparx::SparxRoot.parse_xml`.
+Then, you can generate Ruby objects by `Xmi::Sparx::Root.parse_xml`.
 
 === Output Classes and Modules Generated from Extension into Ruby Files
 
@@ -154,14 +161,320 @@ module Xmi
 end
 ----
 
+== Namespace Architecture
+
+=== General
+
+The XMI library normalizes all input namespace versions to a canonical version
+(20131001) before parsing. This allows the library to handle XMI files with
+different namespace versions (2011, 2013, 2016) using a single set of model
+classes.
+
+=== Namespace Normalization
+
+The normalization is performed by [`SparxRoot.replace_xmlns`](lib/xmi/sparx.rb:1158) which rewrites
+namespace URIs in the input XML:
+
+.Example of namespace normalization
+====
+[source,xml]
+----
+<!-- Input XMI with various namespace versions -->
+<xmi:XMI xmlns:xmi="http://www.omg.org/spec/XMI/20110701"
+         xmlns:uml="http://www.omg.org/spec/UML/20161101">
+  <!-- content -->
+</xmi:XMI>
+
+<!-- After normalization, becomes -->
+<xmi:XMI xmlns:xmi="http://www.omg.org/spec/XMI/20131001"
+         xmlns:uml="http://www.omg.org/spec/UML/20131001">
+  <!-- content -->
+</xmi:XMI>
+----
+====
+
+=== Namespace Classes
+
+Namespace classes are defined in [`lib/xmi/namespace/omg.rb`](lib/xmi/namespace/omg.rb:1):
+
+* **Version-specific classes**: `Xmi20110701`, `Uml20131001`, etc.
+* **Version-agnostic aliases**: `Xmi`, `Uml`, `UmlDi`, `UmlDc`
+
+The aliases inherit from the 20131001 versions (the normalized version):
+
+.Alias class definitions
+====
+[source,ruby]
+----
+class Xmi < Lutaml::Xml::Namespace
+  uri "http://www.omg.org/spec/XMI/20131001"
+  prefix_default "xmi"
+end
+
+class Uml < Lutaml::Xml::Namespace
+  uri "http://www.omg.org/spec/UML/20131001"
+  prefix_default "uml"
+end
+----
+====
+
+This allows models to use clean namespace references without worrying about
+specific versions:
+
+.Using namespace aliases in model definitions
+====
+[source,ruby]
+----
+class MyModel < Lutaml::Model::Serializable
+  xml do
+    root "Model"
+    namespace ::Xmi::Namespace::Omg::Uml
+    namespace_scope [
+      ::Xmi::Namespace::Omg::Xmi,
+      ::Xmi::Namespace::Omg::Uml,
+      ::Xmi::Namespace::Omg::UmlDi,
+    ]
+  end
+end
+----
+====
+
+
+=== Namespace-Qualified Mapping Declaration
+
+All element and attribute mappings explicitly declare their namespace to ensure
+proper XML parsing and serialization. This is required even when types have
+`xml_namespace` declared.
+
+.Element mapping with namespace
+====
+[source,ruby]
+----
+xml do
+  root "Model"
+  namespace ::Xmi::Namespace::Omg::Uml
+
+  # Element mapping with explicit namespace
+  map_element "packagedElement", to: :packaged_element,
+              namespace: "http://www.omg.org/spec/UML/20131001",
+              prefix: "uml"
+end
+----
+====
+
+=== Attribute Namespace Handling
+
+For attributes with namespace prefixes in XML (e.g., `<uml:Model xmi:id="...">`),
+both `namespace:` and `prefix:` parameters are required in `map_attribute`, even
+when the attribute type has `xml_namespace` declared.
+
+.Attribute mapping with namespace prefix
+====
+[source,ruby]
+----
+xml do
+  root "Model"
+  namespace ::Xmi::Namespace::Omg::Uml
+
+  # XMI-typed attribute with explicit namespace declaration
+  map_attribute "id", to: :id,
+                namespace: "http://www.omg.org/spec/XMI/20131001",
+                prefix: "xmi"
+  
+  # Regular attribute without namespace prefix
+  map_attribute "name", to: :name
+end
+----
+
+Without explicit namespace declarations in `map_attribute`, attributes with
+namespace prefixes will parse as `nil`.
+====
+
+=== Sparx Systems Namespaces
+
+Sparx-specific namespaces are defined in [`lib/xmi/namespace/sparx.rb`](lib/xmi/namespace/sparx.rb:1):
+
+* **SysPhS** - System Physical Systems profile
+* **GML** - Geography Markup Language profile
+* **EaUml** - Enterprise Architect UML extensions
+* **CustomProfile** - Custom profile support
+* **CityGML** - City Geography Markup Language
+
+.Using Sparx namespaces
+====
+[source,ruby]
+----
+xml do
+  root "ModelicaParameter"
+  namespace ::Xmi::Namespace::Sparx::SysPhS
+
+  map_attribute "base_Package", to: :base_package
+  map_attribute "name", to: :name
+end
+----
+====
+
+=== Extension Namespaces
+
+Dynamically loaded extensions (via [`EaRoot.load_extension`](lib/xmi/ea_root.rb:54)) also use
+namespace-qualified mappings:
+
+.Extension with namespace mapping
+====
+[source,ruby]
+----
+map_element "ApplicationSchema", to: :gml_application_schema,
+            namespace: "http://www.sparxsystems.com/profiles/GML/1.0",
+            prefix: "GML"
+----
+====
+
 === Limitation
 
 This module is designed to work with XMI files generated by Enterprise
 Architect. It may not work with other XMI files.
 
-Some XML elements, for example `GML:ApplicationSchema`, use `xmlns` as
-attributes. As `Lutaml::Model::Serializable` uses `xmlns` as an internal
-keyword, these attributes will be renamed to `altered_xmlns`.
+== Version-Aware Parsing
+
+The XMI gem supports parsing XMI files from different versions (2.1, 2.5.1, 2.5.2) without preprocessing normalization.
+
+=== Automatic Version Detection
+
+[source,ruby]
+----
+require 'xmi'
+
+# Parse with automatic version detection
+doc = Xmi.parse(xml_content)
+
+# Get version information without parsing
+info = Xmi::Parsing.detect_version(xml_content)
+puts info[:xmi_version]  # => "20131001"
+puts info[:uml_version]  # => "20131001"
+----
+
+=== Explicit Version Specification
+
+[source,ruby]
+----
+# Parse with explicit version
+doc = Xmi.parse_with_version(xml_content, "20131001")
+
+# Check if version is supported
+Xmi::Parsing.version_supported?("20131001")  # => true
+Xmi::Parsing.supported_versions  # => ["20110701", "20131001", "20161101"]
+----
+
+=== Supported Versions
+
+| Version | Date | XMI Namespace |
+|---------|------|---------------|
+| XMI 2.1 | 20110701 | `http://www.omg.org/spec/XMI/20110701` |
+| XMI 2.5.1 | 20131001 | `http://www.omg.org/spec/XMI/20131001` |
+| XMI 2.5.2 | 20161101 | `http://www.omg.org/spec/XMI/20161101` |
+
+=== Fallback Chain
+
+Version-specific registers form a fallback hierarchy:
+
+....
+xmi_20161101
+    ↓ fallback
+xmi_20131001
+    ↓ fallback
+xmi_20110701
+    ↓ fallback
+xmi_common
+    ↓ fallback
+default
+....
+
+Types not found in a version fall back to older versions. For example,
+XMI 2.5.2 uses XMI 2.5.1's `Documentation` model (same structure).
+
+=== Migration from Old API
+
+The old API used `SparxRoot.parse_xml` with automatic namespace normalization:
+
+[source,ruby]
+----
+# Old API (still works, but version-aware API is recommended)
+doc = Xmi::Sparx::SparxRoot.parse_xml(xml_content)
+----
+
+The new version-aware API:
+
+[source,ruby]
+----
+# New API - explicit about version handling
+doc = Xmi::Sparx::SparxRoot.parse_xml_with_versioning(xml_content)
+
+# Or use the module-level API
+doc = Xmi.parse(xml_content)
+----
+
+=== Enterprise Architect Quirks
+
+Enterprise Architect (EA) generates XMI files with several non-standard
+behaviors that this library handles through preprocessing.
+
+==== OMG Namespace Version Normalization
+
+OMG publishes XMI and UML specifications with dated namespace URIs
+(e.g., `http://www.omg.org/spec/XMI/20110701`, `20131001`, `20161101`).
+While these represent different specification versions, the core XMI
+structure is compatible across versions.
+
+This library normalizes all OMG namespace versions to the canonical
+`20131001` version during parsing, allowing a single set of model classes
+to handle all versions.
+
+[source,xml]
+----
+<!-- Input with mixed versions -->
+<xmi:XMI xmlns:xmi="http://www.omg.org/spec/XMI/20110701"
+         xmlns:uml="http://www.omg.org/spec/UML/20161101">
+
+<!-- After normalization -->
+<xmi:XMI xmlns:xmi="http://www.omg.org/spec/XMI/20131001"
+         xmlns:uml="http://www.omg.org/spec/UML/20131001">
+----
+
+==== EA's Misuse of the `xmlns` Attribute
+
+In standard XML, the `xmlns` attribute has special meaning—it declares the
+default namespace for an element and its descendants. The XML specification
+reserves this attribute name for namespace declarations.
+
+However, Enterprise Architect incorrectly uses `xmlns` as a *regular data
+attribute* on certain stereotype elements, storing arbitrary URI values that
+have nothing to do with XML namespace declarations. This is a violation of
+XML conventions.
+
+This quirk has been observed on:
+- `GML:ApplicationSchema` (Geography Markup Language profile)
+- `CityGML:ApplicationSchema` (City Geography Markup Language profile)
+
+[source,xml]
+----
+<!-- EA-generated XMI with xmlns as a data attribute -->
+<GML:ApplicationSchema xmlns="http://some-uri-value"
+                       targetNamespace="http://example.org/ns">
+----
+
+This creates parsing conflicts because XML libraries treat `xmlns` as a
+reserved keyword. This library works around the issue by renaming the
+`xmlns` attribute to `altered_xmlns` before parsing:
+
+[source,xml]
+----
+<!-- After preprocessing -->
+<GML:ApplicationSchema altered_xmlns="http://some-uri-value"
+                       targetNamespace="http://example.org/ns">
+----
+
+The corresponding model classes (e.g., `Xmi::Sparx::Gml::ApplicationSchema`)
+define an `altered_xmlns` attribute to receive this value.
 
 == Development
 

data/benchmark_parse.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+# Benchmark script for XMI parsing performance.
+# Usage: bundle exec ruby benchmark_parse.rb
+#
+# Parses the full-242.xmi fixture (3.5 MB) multiple times and reports
+# average, min, and max parse times.
+
+require "bundler/setup"
+require "xmi"
+
+FIXTURE_PATH = File.join(__dir__, "spec", "fixtures", "full-242.xmi")
+WARMUP_RUNS = 2
+BENCH_RUNS = 5
+
+abort "Fixture not found: #{FIXTURE_PATH}" unless File.exist?(FIXTURE_PATH)
+
+xml_content = File.read(FIXTURE_PATH)
+file_size_mb = File.size(FIXTURE_PATH).to_f / (1024 * 1024)
+
+puts "XMI Parsing Benchmark"
+puts "=" * 50
+puts "File: #{FIXTURE_PATH}"
+puts "Size: #{file_size_mb.round(2)} MB"
+puts "Ruby: #{RUBY_VERSION} (#{RUBY_PLATFORM})"
+puts "Warmup runs: #{WARMUP_RUNS}"
+puts "Benchmark runs: #{BENCH_RUNS}"
+puts
+
+# Warmup
+puts "Warming up..."
+WARMUP_RUNS.times do |i|
+  GC.start
+  Xmi::Sparx::SparxRoot.parse_xml(xml_content)
+  puts "  Warmup #{i + 1}/#{WARMUP_RUNS} complete"
+end
+
+# Benchmark
+puts "Benchmarking..."
+times = BENCH_RUNS.times.map do |i|
+  GC.start
+  t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  Xmi::Sparx::SparxRoot.parse_xml(xml_content)
+  t1 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  elapsed = t1 - t0
+  puts "  Run #{i + 1}/#{BENCH_RUNS}: #{elapsed.round(3)}s"
+  elapsed
+end
+
+avg = times.sum / times.size
+min = times.min
+max = times.max
+
+puts
+puts "Results"
+puts "-" * 50
+puts "Average: #{avg.round(3)} s"
+puts "Min:     #{min.round(3)} s"
+puts "Max:     #{max.round(3)} s"
+puts "StdDev:  #{Math.sqrt(times.sum { |t| (t - avg)**2 } / times.size).round(3)} s"

data/docs/migration.md

@@ -0,0 +1,141 @@
+# Migration Guide: Version-Aware Parsing
+
+## Overview
+
+This guide helps you migrate from the old XMI parsing API to the new version-aware parsing system.
+
+## Old API (Pre-Versioning)
+
+The old API used `SparxRoot.parse_xml` with automatic namespace normalization:
+
+```ruby
+require 'xmi'
+
+# Old approach - normalizes all namespaces to 20131001
+doc = Xmi::Sparx::SparxRoot.parse_xml(xml_content)
+```
+
+This approach:
+- Preprocesses XML to normalize namespace versions
+- Uses a single set of model classes
+- Works for all XMI versions
+
+## New API (Version-Aware)
+
+The new API detects and uses the correct version automatically:
+
+```ruby
+require 'xmi'
+
+# New approach - version-aware parsing
+doc = Xmi.parse(xml_content)
+
+# Or for Sparx EA files
+doc = Xmi::Sparx::SparxRoot.parse_xml_with_versioning(xml_content)
+```
+
+This approach:
+- Detects version from XML namespace
+- Uses version-specific model classes when needed
+- Falls back gracefully for shared types
+
+## Quick Migration
+
+### For Basic Parsing
+
+```ruby
+# Before
+doc = Xmi::Sparx::SparxRoot.parse_xml(xml_content)
+
+# After
+doc = Xmi::Sparx::SparxRoot.parse_xml_with_versioning(xml_content)
+
+# Or
+doc = Xmi.parse(xml_content)
+```
+
+### For Version Detection
+
+```ruby
+# Before
+# No built-in version detection
+
+# After
+info = Xmi::Parsing.detect_version(xml_content)
+puts info[:xmi_version]  # => "20131001"
+```
+
+### For Explicit Version
+
+```ruby
+# Before
+# No explicit version support
+
+# After
+doc = Xmi.parse_with_version(xml_content, "20131001")
+```
+
+## Benefits of Version-Aware Parsing
+
+1. **Correct Types**: Version-specific models are used when structures differ
+2. **No Preprocessing**: XML is parsed directly without modification
+3. **Graceful Fallback**: Shared types work across versions
+4. **Future Extensibility**: Easy to add new version support
+
+## When to Use Each API
+
+| Use Case | Recommended API |
+|----------|----------------|
+| Sparx EA files | `Xmi::Sparx::SparxRoot.parse_xml_with_versioning` |
+| General XMI files | `Xmi.parse` |
+| Version detection | `Xmi::Parsing.detect_version` |
+| Known version | `Xmi.parse_with_version(xml, version)` |
+
+## Backward Compatibility
+
+The old `parse_xml` method still works but normalizes namespaces:
+
+```ruby
+# Old API - still supported
+doc = Xmi::Sparx::SparxRoot.parse_xml(xml_content)
+
+# This internally normalizes to 20131001 namespace
+```
+
+## Troubleshooting
+
+### Version Not Detected
+
+If version detection fails:
+
+```ruby
+# Check what was detected
+info = Xmi::Parsing.detect_version(xml_content)
+
+# Use explicit version if needed
+doc = Xmi.parse_with_version(xml_content, "20131001")
+```
+
+### Type Resolution Fails
+
+If a type isn't resolved correctly:
+
+```ruby
+# Initialize versioning explicitly
+Xmi.init_versioning!
+
+# Check what version was detected
+info = Xmi::Parsing.detect_version(xml_content)
+
+# Use explicit version
+doc = Xmi.parse_with_version(xml_content, info[:xmi_version])
+```
+
+## API Comparison
+
+| Old API | New API |
+|---------|---------|
+| `SparxRoot.parse_xml` | `SparxRoot.parse_xml_with_versioning` |
+| (no detection) | `Xmi::Parsing.detect_version` |
+| (no explicit) | `Xmi.parse_with_version` |
+| `Xmi.parse` (not existed) | `Xmi.parse` (auto-detect) |