Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "Authoring XML Schemas for use with EMF"

(→‎Reference Section)
m
Line 79: Line 79:
 
#; Your EMF Model
 
#; Your EMF Model
 
#: References to the schemas you imported are kept so that you can invoke a reload later. Generations options are configured the first time with different defaults, under the assumption that you'll be reading and writing to XML files.
 
#: References to the schemas you imported are kept so that you can invoke a reload later. Generations options are configured the first time with different defaults, under the assumption that you'll be reading and writing to XML files.
 +
 +
=Mapping an XSD to Ecore=
 +
 +
==Mapping Schema to EPackage==
 +
 +
Each XML Schema is mapped to an EPackage.
 +
 +
==Mapping Attributes and Elements to EAttributes and EReferences==
 +
 +
===Attribute to Attribute===
 +
 +
Simple attributes in your schema are mapped by default to EAttributes. The upper bound on the EAttribute must be 1 in these cases.
 +
 +
{{AnnotatedSourceCode}}
 +
|- style="text-align:left" |
 +
! XML Schema
 +
! Description
 +
 +
|-
 +
{{CodeCell|0}}<xsd:attribute name="message"
 +
| EAttribute
 +
 +
|-
 +
{{CodeCell|2}}type="xsd:string"
 +
 +
{{AnnotatedLine}}
 +
{{CodeCell|2}}use="'''optional'''|required|prohibited"
 +
| "Required" causes the Lower Bound of the EAttribute to be 1. Note that unsettable is TRUE by default
 +
 +
{{AnnotatedLine}}
 +
{{CodeCell|2}}ecore:unsettable="false|<u>true</u>"
 +
|
 +
 +
{{AnnotatedLine}}
 +
{{CodeCell|2}}ecore:transient="<u>false</u>|true"
 +
| False is assumed
 +
 +
{{AnnotatedLine}}
 +
{{CodeCell|2}}ecore:volatile="<u>false</u>|true"
 +
| False is assumed
 +
 +
{{AnnotatedLine}}
 +
{{CodeCell|2}}default="hello world"
 +
| Stored in defaultValueLiteral
 +
 +
|-
 +
{{CodeCell|2}}… />
 +
 +
|}
 +
  
 
=Cheatsheet: An XML Schema with commonly-used Ecore markup=
 
=Cheatsheet: An XML Schema with commonly-used Ecore markup=

Revision as of 13:28, 15 June 2007

This article focuses on authoring and using XML Schemas for the purpose of generating an EMF model.

Introduction

An EMF Model (files of type *.genmodel) is your hub for importing/exporting other metamodel formats, linking to other EMF models, and generating implementation code. Out-of-the-box, EMF can import XML Schema Definitions (XSDs) into Ecore Models (files of type *.ecore). Similarly, EMF can export Ecore Models to XSDs. But without some additional information, EMF uses a default set of transformations that rarely yields the desired results.

Luckily, both Ecore models and XML Schemas have support for annotations. Annotations can be almost anything, but for this discussion, annotations will serve two main purposes:

  • Provide additional information when transforming one metamodel to another
  • Provide additional information on how to serialize/deserialize your model objects

EMF supports transformations in both directions (to and from XSDs). Currently, if you start with an Ecore model, round-tripping to XSD and back to Ecore should be lossless. However, Ecore supports some structures that have no XSD equivalent, such as multiple inheritance. Information will be lost in such cases. Also, if you start with an XSD, not all of the information will be captured in the Ecore model. Therefore, XSD->Ecore->XSD is not a recommended practice as of the Europa release.

This article will focus only on authoring and annotating XSDs, and importing them into Ecore models. However, it is often a useful learning tool to model certain structures first in Ecore, and then export to see the XSD equivalent, including the ecore annotations.

Reasons to use XSDs with EMF

  • The XSD already exists
  • An XSD is needed in the final product/API
  • An XSD is one way to customize how EMF models are persisted

Important Differences between XSDs and Ecore Models

Multiple Inheritance

Ecore Models XML Schemas

EMF's EClass supports multiple inheritance, which allows you to mix-in structural features like attributes at multiple places in your generated class hiearchy. However, the java language does not support multiple class inheritance, so the actual implementation behind the shared java interface is generated multiple times.

One benefit to using multiple inheritance with EMF is that the metamodel is shared. Clients that use the reflective API or receive model events will see the same shared feature even though the implementation has been duplicated.

XML Schemas do not support multiple inheritance. A Complex Type can only extend one other Complex Type.

As an approximation, XSDs allow attribute groups do be define. They can be reused multiple times. However, each time an attribute group is reused, it is treated as a copy of those attributes, rather than a shared reference.

Global Elements and Attributes

Ecore Models XML Schemas
Ecore's Attributes and References always occur in the context of a containing EClass. They can not be declared on their own, and later pulled in to one or more EClasses. XSDs allow global elements and attributes to be defined and then referenced multiple times. This type of "referencing" actually results in a copy.

The Transformation Process

  1. An EMF Model is created and associated with one or more XSDs
  2. When the Wizard finishes, the conversion process creates *.ecore files
  3. At this point, EMF will not read your XSDs again. All information needed by EMF has been tucked away somewhere else.
  4. If you modify your schemas, the transformation can be performed again from the .genmodel Editor. Affected Ecore models are completely replaced.

Which Parts of an XML Schema are Processed?

Without being told otherwise, EMF will process your Schema, all of its globally declared Elements, and all Types contained therein. Other content (e.g. globally-declared Attributes, AttributeGroups, and Groups) is ignored by EMF. These entries are just macros that Elements and Types can reference, effectively in-lining a copy. If two Types reference the same global Attribute, AttributeGroup, or Element, EMF sees them as two distinct features which happen to have identical information.

What is the Output of the Process?

The Process generates, updates, or replaces the following:

  1. Ecore Models
    Schemas become Packages; Simple/Complex Types become EClasses, EDataTypes, and EEnums; Elements and Attributes become EStructuralFeatures
    Annotations in your Ecore Models
    Ecore annotations are added in several places to capture the way your model should be serialized/deserialized. These annotations are what enable EMF to read and write XML documents that don't conform to EMF's default serialization format.
    A Helper EClass named "DocumentRoot"
    In certain cases, EMF must create a DocumentRoot class to store additional information.
    Helper EStructuralFeatures, such as feature maps with the suffix "group"
    To handle XSD features like substitution groups, the substitution rule to be used when writing must be known. To handle these cases, your Class' EReferences don't hold onto the actual content, but are instead derived from these "group" references which contains keys in addition to the actual referenced object.
    Your EMF Model
    References to the schemas you imported are kept so that you can invoke a reload later. Generations options are configured the first time with different defaults, under the assumption that you'll be reading and writing to XML files.

Mapping an XSD to Ecore

Mapping Schema to EPackage

Each XML Schema is mapped to an EPackage.

Mapping Attributes and Elements to EAttributes and EReferences

Attribute to Attribute

Simple attributes in your schema are mapped by default to EAttributes. The upper bound on the EAttribute must be 1 in these cases.


XML Schema Description
<xsd:attribute name="message" EAttribute
type="xsd:string"
use="optional|required|prohibited" "Required" causes the Lower Bound of the EAttribute to be 1. Note that unsettable is TRUE by default
ecore:unsettable="false|true"
ecore:transient="false|true" False is assumed
ecore:volatile="false|true" False is assumed
default="hello world" Stored in defaultValueLiteral
… />


Cheatsheet: An XML Schema with commonly-used Ecore markup

XML Schema File Description
<xs:schema
xmlns:cc="http://www.example.org/GolfCountryClub"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:ecore="http://www.eclipse.org/emf/2002/Ecore" Defining a namespace prefix for Ecore is necessary when using EMF markup
ecore:nsPrefix="cc" Setting the nsPrefix will control the prefix used when saving your EMF documents
ecore:package="org.example.core.model.countryclub" The package statement determines both the name of the EPackage, and the full name for the java package of the generated implementation
targetNamespace="http://www.example.org/GolfCountryClub"
...
>

Schemas contain globally declared elements for the following purposes:

  1. To define root elements which can appear in a document
  2. To declare a replaceable element, which can be substituted by other global elements
  3. For convenience, to define an Element once, and reference it multiple times from other elements

If the element exists for one of the first two reasons, EMF needs to map the element, which results in a reference on the magical DocumentRoot class in the same Package. Otherwise, you can instruct EMF to ignore the element.

...
<xs:element name="GolfCourse"
type="tns:GolfCourse"
ecore:ignore="true" EMF should ignore not only this element, but any anonymous types, etc., it contains
ecore:name="overrideName" Overrides the name assigned to the feature that is created on the DocumentRoot class
</xs:element>
...

Simple and Complex Types Section

(Description missing)

<xs:simpleType name="RGB"
ecore:ignore="true" Ignores this type
ecore:name="overrideName" Determines the name
ecore:instanceClass="full.java.class.Name" Determines the fully qualified java class that is used to represent the datatype
>
<xs:restriction base="xs:string"/>
</xs:simpleType>
...


<xs:simpleType name="Align"
ecore:ignore="true" Ignores this Simple Type
ecore:name="overrideName" Change the name
...
>
<xs:restriction>
<xs:enumeration value="Left"/>
<xs:enumeration value="Center"/>
<xs:enumeration value="Right"/>
</xs:restriction>
</xs:simpleType>
...
</xs:schema>
Retrieved from "https://wiki.eclipse.org/index.php?title=Authoring_XML_Schemas_for_use_with_EMF&oldid=39273"

Back to the top