# Workflow Components

The XSD Adapter provides the following workflow components:

### `XSDMetaModel`

The XSDMetaModel loads the specified XSD, transforms them to Ecore models and makes them available for the other oAW components. If XSDs include/import other XSDs or if XML files reference XSDs via schemaLocation, theses XSDs are also loaded (details: the section called “How to declare XML Schemas” ). The most common scenario is to declare the `XSDMetaModel` within an `XMLReader`:

    <component class="org.eclipse.xtend.typesystem.xsd.XMLReader">
      <modelSlot value="model" />
      <uri value="model.xml" />
      <metaModel id="mm" class="org.eclipse.xtend.typesystem.xsd.XSDMetaModel">
        <schemaFile value="metamodel.xsd" />
        <registerPackagesGlobally value="true" />
      </metaModel>
    </component>

Another option is to specify an `XSDMetaModel` independently of other components as a bean:

    <bean id="
    mymetamodel
    " class="org.eclipse.xtend.typesystem.xsd.XSDMetaModel">
      <schemaFile value="metamodel.xsd" />
    </bean>
    <component class="org.eclipse.xtend.typesystem.xsd.XMLReader">
      <modelSlot value="model" />
      <uri value="model.xml" />
      <metaModel
    idRef="mymetamodel"
     />
    </component>

Attention: It can lead to errors when XSDs are loaded multiple times, which can only happen when using multiple `XSDMetaModels` within one workflow. The safe way to go is to declare just one `XSDMetaModel` per workflow and reference it from all components that need it.

Properties:

- schemaFile: optional, allowed multiple times: Specifies an XSD file which is being loaded. The path can be a complete URI, or relative to the project root or classpath.

- registerPackagesGlobally: optional, default "false": If true, generated EPackages are registered to `org.eclipse.emf.ecore.EPackage.Registry.INSTANCE`, EMF's global package registry. Warning: when running workflows from your own java code, make sure to remove the generated packages from the registry before the next run!

### `XMLReader`

The `XMLReader` reads one XML file which is valid according to the XSDs loaded by the `XSDMetaModel`. The XML file is loaded as a model and stored in the specified slot. Example:

    <component class="org.eclipse.xtend.typesystem.xsd.XMLReader">
      <modelSlot value="model" />
      <uri value="model.xml" />
      <metaModel idRef="mymetamodel" />
    </component>

Properties:

- slot: required: The name of the slot which in which the loaded model is stored. Other workflow components can access the model via referring to this slot.

- uri: required: The file name of the XML file which should be read. Absolute URIs, and pathnames relative to the project root or to the classpath are valid.

- metaModel: optional: Specifies the `XSDMetaModel` (see the section called “ `XSDMetaModel` ”) for the `XMLReader`. In case no `XSDMetaModel` is specified, an `XSDMetaModel` with default configuration is instantiated implicitly. It is important to pay attention that all needed XSDs can be found while the loading process: the section called “How to declare XML Schemas”.

- useDocumentRoot: optional, default "false": Dealing with XML files as models, most people think of the XML's root element as the model's root object. This is the default used by the `XMLReader`. But the XML's root element actually has a parent, the so-called DocumentRoot. Additionally the DocumentRoot contains comments/processing instructions and CDATA section which appears before or after the XML's root element, and, most notably, the DocumentRoot contains information about the used namespaces. If useDocumentRoot is set to true, the `XMLReader` stores the DocumentRoot-Object instead the XML's root element's object to the specified slot.

- option: optional, can be specified multiple times: Option specifies a key-value-pair, which is handed on to the EMF's XMLResource in the loading process. Valid options are documented via JavaDoc in interface `org.eclipse.emf.ecore.xmi.XMLResource` . Additionally, the `XMLReader` supports these options:

  - DEFAULT_NAMESPACE: Specifies a default namespace, in case the XML file does not declare one:

        <option key="DEFAULT_NAMESPACE" val="http://www.dlese.org/Metadata/opml" />

  - NAMESPACE_MAP: Specifies a mapping for namespaces, which is applied when loading XML files.

        <option key="NAMESPACE_MAP">
          <val class="org.eclipse.xtend.typesystem.xsd.lib.MapBean">
            <mapping from="http://www.eclipse.org/modeling/xpand/example/model/wrong"
                     to="http://www.eclipse.org/modeling/xpand/example/model/loadcurve" />
          </val>
        </option>

### `XMLWriter`

The `XMLWriter` writes the model stored in a slot to an XML file. If the slot contains a collection of models, each one is written to a separate file. The model(s) must have been instantiated using an XSD-based meta model. Example:

    <component class="org.eclipse.xtend.typesystem.xsd.XMLWriter">
      <metaModel idRef="svgmm" />
      <modelSlot value="svgmodel" />
      <uri value="src-gen/mycurve.svg" />
    </component>

Properties:

- slot: required: The name of the slot which holds the model or the collection of models which shall be serialized to XML.

- metaModel: required: The instance of `XSDMetaModel`, which holds the XSD that the supplied models are based on. Also see the section called “ `XSDMetaModel` ”

- uri: required if no uriExpression is specified: The file name of the XML file which should be written. Absolute URIs are valid. Use relative path names on your own risk.

- uriExpression: required if no uri is specified: In the scenario where multiple XML files are written, this provides a mechanism to determine the file name for each of them. The oAW-expression specified in `expression` is evaluated for each file and has to return a file name. The model that is going to be written is accessible in the expression via a variable that has the name specified in `varName`. Example:

      <uriExpression varName="docroot" expression="'src-gen/'+ecore2xsd::getFileName(docroot)" />

- option: optional, can be specified multiple times: Option specifies a key-value-pair, which is handed on to the EMF's XMLResource in the writing process. Valid options are documented via JavaDoc in interface `org.eclipse.emf.ecore.xmi.XMLResource` .

### `XMLBeautifier`

The `XMLBeautifier` uses EMF to load the XML file, formats the mixed content (elements and text contained by the same element) and writes the file back to disk applying a nice indentation for the elements. The `XMLBeautifier` is not intended to be used in combination with the `XMLWriter`, since the `XMLWriter` cares about indentation by itself. Instead, use it for "manually" constructed XML files using Xpand. Since the frameworks for loading/storing XML always load the whole file into a complex data structure in memory, this approach does not scale well for huge XML files. Example:

    <component class="org.eclipse.xpand2.Generator">
      <metaModel idRef="mm" />
      <expand value="${src-pkg}::${file}::Root FOR '${out}'" />
      <outlet path="${src-gen-dir}" />
      <beautifier class="org.eclipse.xtend.typesystem.xsd.XMLBeautifier">
        <maxLineWidth value="60" />
        <formatComments value="true" />
        <fileExtensions value=".xml, .html" />
      </beautifier>
    </component>

Properties:

- maxLineWidth: optional: Specifies the number of character after which a linewrap should be performed.

- formatComments: optional, default true: Specifies if formatting should also be applied to comments.

- fileExtensions: optional, default ".xml, .xsl, .xsd, .wsdd, .wsdl": Specifies a filter for which files formatting should be applied. Only files that match one of the specified file extensions are processed.

- loadOption: optional, can be specified multiple times: Option specifies a key-value-pair, which is handed on to the EMF's XMLResource in the loading process. Valid options are documented via JavaDoc in interface `org.eclipse.emf.ecore.xmi.XMLResource` .

- saveOption: optional, can be specified multiple times: Same as loadOption, except for the difference that these options are applied while the writing process. Example:

      <saveOption key="XML_VERSION" val="1.1" />
      <saveOption key="ENCODING" val="ASCII" />