Add Integrate Consumer and Producer Mappings Showcase (WIP) (#789)

showcases/data/End-to-end examples/Integrate Mappings/code.pure

@@ -0,0 +1,156 @@
+###Pure
+Class com::entity::LegalEntity
+{
+  entityId: String[1];
+  name: String[1];
+}
+
+Class com::trade::Trade
+{
+  id: String[1];
+  value: Integer[1];
+}
+
+Association com::trade::Trade_LegalEntity
+{
+  client: com::entity::LegalEntity[1];
+  trades: com::trade::Trade[*];
+}
+
+
+###Relational
+Database com::trade::TradeDatabase
+(
+  Schema Trade
+  (
+    Table Trade
+    (
+      id VARCHAR(32) PRIMARY KEY,
+      value INTEGER NOT NULL,
+      ENTITY_ID_FK VARCHAR(32) NOT NULL
+    )
+  )
+)
+
+Database com::entity::EntityDatabase
+(
+  Schema Entity
+  (
+    Table LegalEntity
+    (
+      ENTITY_ID VARCHAR(32) PRIMARY KEY,
+      name VARCHAR(32) NOT NULL
+    )
+  )
+)
+
+
+###Mapping
+Mapping com::entity::LegalEntityMapping
+(
+  *com::entity::LegalEntity: Relational
+  {
+    ~primaryKey
+    (
+      [com::entity::EntityDatabase]Entity.LegalEntity.ENTITY_ID
+    )
+    ~mainTable [com::entity::EntityDatabase]Entity.LegalEntity
+    entityId: [com::entity::EntityDatabase]Entity.LegalEntity.ENTITY_ID,
+    name: [com::entity::EntityDatabase]Entity.LegalEntity.name
+  }
+)
+
+Mapping com::trade::TradeWithLegalEntityMapping
+(
+  include dataspace com::entity::EntityDataspace
+
+  com::trade::Trade[trade]: Relational
+  {
+    ~primaryKey
+    (
+      [com::trade::TradeDatabase]Trade.Trade.id
+    )
+    ~mainTable [com::trade::TradeDatabase]Trade.Trade
+    id: [com::trade::TradeDatabase]Trade.Trade.id,
+    value: [com::trade::TradeDatabase]Trade.Trade.value,
+    +entityIdFk: String[1]: [com::trade::TradeDatabase]Trade.Trade.ENTITY_ID_FK
+  }
+
+  com::trade::Trade_LegalEntity: XStore
+  {
+    client[trade, com_entity_LegalEntity]: $this.entityIdFk ==
+  $that.entityId,
+    trades[com_entity_LegalEntity, trade]: $this.entityId ==
+  $that.entityIdFk
+  }
+)
+
+
+###DataSpace
+DataSpace com::entity::EntityDataspace
+{
+  executionContexts:
+  [
+    {
+      name: 'default';
+      mapping: com::entity::LegalEntityMapping;
+      defaultRuntime: com::entity::EntityRuntime;
+    }
+  ];
+  defaultExecutionContext: 'default';
+}
+
+
+###Connection
+RelationalDatabaseConnection com::entity::EntityConnection
+{
+  store: com::entity::EntityDatabase;
+  type: H2;
+  specification: LocalH2
+  {
+  };
+  auth: DefaultH2;
+}
+
+RelationalDatabaseConnection com::trade::TradeConnection
+{
+  store: com::trade::TradeDatabase;
+  type: H2;
+  specification: LocalH2
+  {
+  };
+  auth: DefaultH2;
+}
+
+
+###Runtime
+Runtime com::entity::EntityRuntime
+{
+  mappings:
+  [
+    com::entity::LegalEntityMapping
+  ];
+  connectionStores:
+  [
+    com::entity::EntityConnection:
+    [
+      com::entity::EntityDatabase
+    ]
+  ];
+}
+
+Runtime com::trade::TradeRuntime
+{
+  mappings:
+  [
+    com::trade::TradeWithLegalEntityMapping
+  ];
+  connectionStores:
+  [
+    com::trade::TradeConnection:
+    [
+      com::trade::TradeDatabase,
+      com::entity::EntityDatabase
+    ]
+  ];
+}

showcases/data/End-to-end examples/Integrate Mappings/info.md

@@ -0,0 +1,7 @@
+---
+title: Integrate Mappings
+description: How to integrate your mapping with another group's model without tying yourself to their underlying physical implementation or specific mapping.
+development: true
+---
+
+In this example, the producer of the LegalEntityMapping has released a mapping of LegalEntity. The consumers have created their own mapping (TradeMapping) which they would like to join against the producer mapping. In order to prevent unnecessarily tying their model to the implementation details of the producer's mapping, they include the producer's dataspace in TradeMapping. Including a dataspace rather than a mapping creates a layer of abstraction that protects the consumer and producer from unnecessary difficulty when a producer needs to migrate users onto a new mapping. Instead, the dataspace's underlying default mapping is always included behind-the-scenes by the compiler. The consumer then defines a XStore Association between their trade class and the default class mapping ID of the Legal Entity class (com_entity_LegalEntity), which is derived from the package address of the target class. This cross store join allows the consumer to tie their mapping to the target class without explicitly defining the SQL joins occurring behind the scenes. The TradeDB and EntityDB can exist independently as packageable elements without hard-coded dependencies on one another. The consumer then defines the locality of the stores within the runtime, by co-locating them underneath the same connection. With this language, the compiler can immediately understand whether to treat the XStore Associations between mappings as truly Cross-Store or Local.