<?xml version="1.0" encoding="UTF-8"?>
<!--
  ~ ModeShape (http://www.modeshape.org)
  ~
  ~ See the COPYRIGHT.txt file distributed with this work for information
  ~ regarding copyright ownership.  Some portions may be licensed
  ~ to Red Hat, Inc. under one or more contributor license agreements.
  ~ See the AUTHORS.txt file in the distribution for a full listing of 
  ~ individual contributors.
  ~
  ~ ModeShape is free software. Unless otherwise indicated, all code in ModeShape
  ~ is licensed to you under the terms of the GNU Lesser General Public License as
  ~ published by the Free Software Foundation; either version 2.1 of
  ~ the License, or (at your option) any later version.
  ~
  ~ ModeShape is distributed in the hope that it will be useful,
  ~ but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  ~ or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License
  ~ for more details.
  ~
  ~ You should have received a copy of the GNU Lesser General Public License
  ~ along with this distribution; if not, write to:
  ~ Free Software Foundation, Inc.
  ~ 51 Franklin Street, Fifth Floor
  ~ Boston, MA  02110-1301  USA
  -->
<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"	[
<!ENTITY % CustomDTD SYSTEM "../../custom.dtd">
%CustomDTD;
]>
<chapter id="teiid-model-sequencer">
  <title>Teiid Relational Model Sequencer</title>
    <para>
		  <ulink url="http://www.jboss.org/teiiddesigner">Teiid Designer</ulink>,
		  is a visual tool that enables rapid, model-driven definition, integration, management and testing of data services without programming 
		  using the Teiid runtime engine. It is capable of modeling several different kinds of data structures, but the most common and widely-used
		  are relational models that describe a relational database schema, including the catalogs/schemas, tables, views, columns, primary keys, 
		  foreign keys, indexes, procedures, procedure results, procedure results, and logical relationships. Teiid Designer can reverse-engineer
		  a relational model from a JDBC relational database or DDL file. It can also define "virtual" models that are transformations of other 
		  models (where the transformations are defined in terms of SQL select, insert, update, and delete statements). These models can then
		  be packaged into a <emphasis>virtual database</emphasis>, which can be deployed to a Teiid runtime engine.
		</para>
		<para>
			<ulink url="http://www.jboss.org/teiid">Teiid</ulink> is a high-performance database virtualization engine that allows JDBC and ODBC 
			client applications access the virtual database as if it were a real database, using relational, XML, XQuery and procedural queries.  
			Teiid dynamically (and in real-time) figures out how to answer the queries and operations issued by clients by efficiently
			accessing and manipulating the data inside the underlying data sources. Teiid's sophisticated engine is able to plan and optimize
			these operations, even when multiple heterogeneous relational and non-relational data sources must be accessed to obtain the required
			information.
		</para>
		<para>
			The Teiid relational model sequencer parses the model files produced by the Teiid Designer, and extracts the structured relational
			data model described by the XMI file. This means that when these models are uploaded into a ModeShape repository, the sequencer
			writes to the repository all this relational metadata, where it can be queried and accessed by JCR, RESTful, and even JDBC clients.
		</para>
		<para>
			The &ModelSequencer; has a single JavaBean properties for changing behavior:
		</para>
	<table frame='all'>
		<title>&ClassFileSequencer; properties</title>
		<tgroup cols='2' align='left' colsep='1' rowsep='1'>
      <colspec colname='c1' colwidth="1*"/>
      <colspec colname='c2' colwidth="1*"/>
			<thead>
				<row>
		  		<entry>Property</entry>
		  		<entry>Description</entry>
				</row>
			</thead>
			<tbody>
				<row>
					<entry>useXmiUuidsAsJcrUuids</entry>
					<entry>
						Optional property that, if set to 'true', reuses the model's "<code>xmi:uuid</code>" values as the generated nodes' "<code>jcr:uuid</code>" 
						identifiers. In such cases, a model may only appear in the repository once, so even those a model might be uploaded into the repository
						multiple times, each time the model is sequenced the newly generated output will overwrite any output from previous sequencing operations.
						If set the 'false', a model (or different versions of a model) can be uploaded into the repository multiple times, where they all can
						be accessed at any time. The default value for this property is 'false'; changing it may have drastic ramifications and is suggested
						only for advanced users.
					</entry>
				</row>
			</tbody>
		</tgroup>
	</table>
  <sect1 id="teiid-model-sequencer-uuids">
    <title>UUIDs</title>
		<para>
			As mentioned above, the Teiid model sequencer can operate in two modes. The behavior you choose will dramatically change what you can do
			with the sequenced relational models.
		</para>
		<para>
			The first mode reuses the "<code>xmi:uuid</code>" identifiers
			on each object in the model as the "<code>jcr:uuid</code>" node identifiers. In this mode, the sequencer represents each model reference
			as a JCR WEAKREFERENCE, making it very easy to navigate and query relationships. However, there is one major disadvantage of this approach:
			each time a model is uploaded into the repository, the sequencer will override any output generated by earlier sequencing operations upon
			that file (or other versions of it). Thus, the sequenced representation of an uploaded model can ever appear only once within the repository,
			even though different versions of that model might exist in the repository at different locations.
			This may be desirable in some situations, but for most situations it is simply not acceptable.
		</para>
		<para>
			In the second mode of operation (which is the default mode), there is no correlation between the model's "<code>xmi:uuid</code>" 
			and "<code>jcr:uuid</code>" node identifiers.  Various versions of a given model can be uploaded into the repository at multiple locations, 
			yet each model's relational schema will exist in the repository. The downside of this approach is that references are no longer simply
			WEAKREFERENCE properties. Instead, each single-valued reference will be represented as a series of four properties:
			<itemizedlist>
        <listitem>
          <para>
						<code>{referenceName}Href</code> - stores the href literal value from the XMI file; this is always set
				  </para> 
        </listitem>
        <listitem>
          <para>
						<code>{referenceName}XmiUuid</code> - stores the XMI UUID to the referenced node; this is set only if the href had an embedded UUID (hrefs to data types and XSD components don't use UUIDs)
				  </para> 
        </listitem>
        <listitem>
          <para>
						<code>{referenceName}Name</code> - stores the name of the resolved node, though this may not be set if the object being
						referenced is in another model
				  </para> 
        </listitem>
        <listitem>
          <para>
						<code>{referenceName}</code> - stores the JCR weak reference to the resolve node, though this may not be set if the object being
						referenced is in another model
				  </para> 
        </listitem>
			</itemizedlist>
			where "<emphasis>{referenceName}</emphasis>" is the name of the model reference.
			Multi-value references are also represented as a series of four properties, but with a slightly different naming pattern:
			<itemizedlist>
        <listitem>
          <para>
						<code>{singularReferenceName}Href</code> - stores the href literal values from the XMI file; this is always set
				  </para> 
        </listitem>
        <listitem>
          <para>
						<code>{singularReferenceName}XmiUuid</code> - stores the XMI UUID to the referenced nodes; this is set only if the hrefs have 
						an embedded UUID (hrefs to data types and XSD components don't use UUIDs)
				  </para> 
        </listitem>
        <listitem>
          <para>
						<code>{singularReferenceName}Name</code> - stores the name of the resolved nodes, though this may not be set if the object being
						referenced is in another model
				  </para> 
        </listitem>
        <listitem>
          <para>
						<code>{pluralReferenceName}</code> - stores the JCR weak reference to the resolve nodes, though this may not be set if the object being
						referenced is in another model
				  </para> 
        </listitem>
			</itemizedlist>
			Here, "<emphasis>{singularReferenceName}</emphasis>" is the singular form of the model reference name, 
			and "<emphasis>{pluralReferenceName}</emphasis>" is the plural form of the model reference name. For example, for a reference named "columns",
			the "<emphasis>{singularReferenceName}</emphasis>" value would be "column" and the plural form is "columns".  If the reference name is "properties",
			the singular form is "property" and the plural form is "properties".  (ModeShape uses a novel algorithm to determine the singular and plural
			forms of many English words.)
		</para>
		<para>
			References to model objects within the same model are easily resolved upon sequencing, and so we set all of the properties (regardless of
			the mode). However, references to objects in other models cannot be resolved at sequencing time.
		</para>
		<note>
			<para>
				The <link linkend="teiid-vdb-sequencer">Teiid VDB sequencer</link> behavior is unrelated to this mode, since it always sequences models
				with new "<code>jcr:uuid</code>" identifiers that are unrelated to the "<code>xmi:uuid</code>" values. In this manner, each sequencing
				of a VDB will produce the relational model representation for each model in the VDB (with all valid references resolved between all models), 
				independent of any generated output from the Teiid model sequencer.
			</para>
		</note>
	</sect1>
  <sect1 id="teiid-model-sequencer-nodetypes">
    <title>Node Types</title>
		<para>
			The model sequencer follows JCR best-practices by defining all nodes to have a primary type of "<code>nt:unstructured</code>" (or a node type that extends
			"<code>nt:unstructured</code>"), meaning it's possible and valid for any node to have any property (with single or multiple values). 
			However, it is still useful to capture the metadata about what that node represents, and so the sequencer use mixins for this. 
			For example, there is a "<code>xmi:referenceable</code>" mixin with a single "<code>xmi:uuid</code>" property (patterned after the 
			built-in "<code>mix:referenceable</code>" mixin). Since all model objects have mmuuids, all nodes produced by this sequencer will have this mixin. 
		</para>
		<para>
			The rest of this section covers the various (and many!) node types defined for and used by this sequencer. Note that these are non-normative
			definitions of the node types; see the CND files in the "<code>modeshape-sequencer-teiid</code>" JAR file (or source) for the official
			definitions.
		</para>
	  <sect2 id="teiid-model-sequencer-nodetypes-xmi">
	    <title>XMI Namespace</title>
			<para>
				The compact node definitions for the "xmi" namespace are as follows:
			</para>
<programlisting><![CDATA[
<nt  = "http://www.jcp.org/jcr/nt/1.0">
<xmi = "http://www.omg.org/XMI">

//------------------------------------------------------------------------------
// N O D E T Y P E S
//------------------------------------------------------------------------------

[xmi:referenceable] mixin
 - xmi:uuid (string) mandatory

[xmi:model] > nt:unstructured, xmi:referenceable orderable
 - xmi:version (double) = '2.0'
]]></programlisting>
		</sect2>
	  <sect2 id="teiid-model-sequencer-nodetypes-core">
	    <title>Core Namespace</title>
			<para>
				The compact node definitions for the "mmcore" namespace are as follows:
			</para>
<programlisting><![CDATA[
<nt  = "http://www.jcp.org/jcr/nt/1.0">
<xmi = "http://www.omg.org/XMI">
<mmcore = "http://www.metamatrix.com/metamodels/Core">
<mode = "http://www.modeshape.org/1.0">

[mmcore:model] > xmi:referenceable, mode:hashed mixin
  - mmcore:modelType (string) = 'UNKNOWN' < 'PHYSICAL','VIRTUAL','TYPE','VDB_ARCHIVE',
                                            'UNKNOWN','FUNCTION','CONFIGURATION','METAMODEL',
                                            'EXTENSION','LOGICAL','MATERIALIZATION'
  - mmcore:primaryMetamodelUri (string)
  - mmcore:description (string)
  - mmcore:nameInSource (string)
  - mmcore:maxSetSize (long) = '100'
  - mmcore:visible (boolean) = 'true'
  - mmcore:supportsDistinct (boolean) = 'true'
  - mmcore:supportsJoin (boolean) = 'true'
  - mmcore:supportsOrderBy (boolean) = 'true'
  - mmcore:supportsOuterJoin (boolean) = 'true'
  - mmcore:supportsWhereAll (boolean) = 'true'
  - mmcore:supportsDistinct (boolean) = 'true'
  - mmcore:producerName (string)
  - mmcore:producerVersion (string)
  - mmcore:originalFile (string)
  - mmcore:sha1 (string)

[mmcore:import] > nt:unstructured, xmi:referenceable orderable
  - mmcore:modelType (string) = 'UNKNOWN' < 'PHYSICAL','VIRTUAL','TYPE','VDB_ARCHIVE',
                                            'UNKNOWN','FUNCTION','CONFIGURATION','METAMODEL',
                                            'EXTENSION','LOGICAL','MATERIALIZATION'
  - mmcore:primaryMetamodelUri (string)
  - mmcore:path (string)
  - mmcore:name (string)
  - mmcore:modelLocation (string)

[mmcore:annotated] mixin
  - mmcore:description (string)
  - mmcore:keywords (string) multiple

[mmcore:tags] mixin
  - * (undefined) multiple 
  - * (undefined) 
]]></programlisting>
		</sect2>
	  <sect2 id="teiid-model-sequencer-nodetypes-relational">
	    <title>Relational Namespace</title>
			<para>
				The compact node definitions for the "relational" namespace are as follows:
			</para>
<programlisting><![CDATA[
<nt  = "http://www.jcp.org/jcr/nt/1.0">
<relational='http://www.metamatrix.com/metamodels/Relational'>
<xmi = "http://www.omg.org/XMI">

//------------------------------------------------------------------------------
// N O D E T Y P E S
//------------------------------------------------------------------------------

[relational:relationalEntity] > xmi:referenceable abstract mixin
 - relational:nameInSource (string) 

[relational:relationship] > nt:unstructured, relational:relationalEntity abstract

// -------------------------------------------
// Columns and Column Sets
// -------------------------------------------

[relational:column] > nt:unstructured, relational:relationalEntity
 - relational:nativeType (string) 
 - relational:type (weakreference)  
 - relational:typeHref (string) 
 - relational:typeXmiUuid (string) 
 - relational:typeName (string) 
 - relational:length (long) 
 - relational:fixedLength (boolean) 
 - relational:precision (long) 
 - relational:scale (long) 
 - relational:nullable (string) = 'NULLABLE' < 'NO_NULLS', 'NULLABLE', 'NULLABLE_UNKNOWN'
 - relational:autoIncremented (boolean) = 'false' 
 - relational:defaultValue (string) 
 - relational:minimumValue (string) 
 - relational:maximumValue (string) 
 - relational:format (string) 
 - relational:characterSetName (string) 
 - relational:collationName (string) 
 - relational:selectable (boolean) = 'true' 
 - relational:updateable (boolean) = 'true' 
 - relational:caseSensitive (boolean) = 'true' 
 - relational:searchability (string) = 'SEARCHABLE' < 'SEARCHABLE', 
                                       'ALL_EXCEPT_LIKE', 'LIKE_ONLY', 'UNSEARCHABLE'
 - relational:currency (boolean) = 'false'
 - relational:radix (long) = '10'
 - relational:signed (boolean) = 'true' 
 - relational:distinctValueCount (long) = '-1' 
 - relational:nullValueCount (long) = '-1' 
 - relational:uniqueKeys (weakreference) multiple 
 - relational:uniqueKeyHrefs (string) multiple 
 - relational:uniqueKeyXmiUuids (string) multiple 
 - relational:uniqueKeyNames (string) multiple 
 - relational:indexes (weakreference) multiple 
 - relational:indexHrefs (string) multiple 
 - relational:indexXmiUuids (string) multiple 
 - relational:indexNames (string) multiple 
 - relational:foreignKeys (weakreference) multiple 
 - relational:foreignKeyHrefs (string) multiple 
 - relational:foreignKeyXmiUuids (string) multiple 
 - relational:foreignKeyNames (string) multiple 
 - relational:accessPatterns (weakreference) multiple 
 - relational:accessPatternHrefs (string) multiple 
 - relational:accessPatternXmiUuids (string) multiple 
 - relational:accessPatternNames (string) multiple

[relational:columnSet] > nt:unstructured, relational:relationalEntity abstract orderable
 + * (relational:column) = relational:column copy

// -------------------------------------------
// Constraints
// -------------------------------------------

[relational:uniqueKey] > nt:unstructured, relational:relationalEntity abstract
 - relational:columns (weakreference) multiple
 - relational:columnXmiUuids (string) multiple
 - relational:columnNames (string) multiple 
 - relational:foreignKeys (weakreference) multiple 
 - relational:foreignKeyHrefs (string) multiple
 - relational:foreignKeyXmiUuids (string) multiple 
 - relational:foreignKeyNames (string) multiple 

[relational:uniqueConstraint] > relational:uniqueKey

[relational:primaryKey] > relational:uniqueKey

[relational:foreignKey] > relational:relationship
 - relational:foreignKeyMultiplicity (string) = 'ZERO_TO_MANY' < 'ONE', 'MANY', 
                                                'ZERO_TO_ONE', 'ZERO_TO_MANY', 'UNSPECIFIED'
 - relational:primaryKeyMultiplicity (string) = 'ONE' < 'ONE', 'MANY', 'ZERO_TO_ONE', 
                                                'ZERO_TO_MANY', 'UNSPECIFIED'
 - relational:columns (weakreference) multiple
 - relational:columnXmiUuids (string) multiple 
 - relational:columnNames (string) multiple 
 - relational:uniqueKeys (weakreference) multiple 
 - relational:uniqueKeyHrefs (string) multiple 
 - relational:uniqueKeyXmiUuids (string) multiple 
 - relational:uniqueKeyNames (string) multiple 

[relational:index] > nt:unstructured, relational:relationalEntity
 - relational:filterCondition (string) 
 - relational:nullable (boolean) = 'true' 
 - relational:autoUpdate (boolean) 
 - relational:unique (boolean) 
 - relational:columns (weakreference) multiple
 - relational:columnXmiUuids (string) multiple 
 - relational:columnNames (string) multiple 

[relational:accessPattern] > nt:unstructured, relational:relationalEntity orderable
 - relational:columns (UNDEFINED) multiple 

// -------------------------------------------
// Tables and Views
// -------------------------------------------

[relational:table] > relational:columnSet abstract orderable
 - relational:system (boolean) = 'false' 
 - relational:cardinality (long) 
 - relational:supportsUpdate (boolean) = 'true' 
 - relational:materialized (boolean) = 'false' 
 - relational:logicalRelationships (weakreference) multiple 
 - relational:logicalRelationshipHrefs (string) multiple 
 - relational:logicalRelationshipXmiUuids (string) multiple 
 - relational:logicalRelationshipNames (string) multiple 
 + * (relational:primaryKey) = relational:primaryKey copy
 + * (relational:foreignKey) = relational:foreignKey copy
 + * (relational:accessPattern) = relational:accessPattern copy sns

[relational:baseTable] > relational:table orderable

[relational:view] > relational:table orderable


// -------------------------------------------
// Procedures
// -------------------------------------------

[relational:procedureParameter] > nt:unstructured, relational:relationalEntity
 - relational:direction (string) < 'IN', 'OUT', 'INOUT', 'RETURN', 'UNKNOWN'
 - relational:defaultValue (string) 
 - relational:nativeType (string) 
 - relational:type (weakreference) 
 - relational:typeXmiUuid (string) 
 - relational:typeName (string) 
 - relational:length (long) 
 - relational:precision (long) 
 - relational:scale (long) 
 - relational:nullable (string) = 'NULLABLE' < 'NO_NULLS', 'NULLABLE', 'NULLABLE_UNKNOWN'
 - relational:radix (long) = '10' 

[relational:procedureResult] > relational:columnSet orderable

[relational:procedure] > nt:unstructured, relational:relationalEntity orderable
 - relational:function (boolean) 
 - relational:updateCount (string) < 'AUTO', 'ZERO', 'ONE', 'MULTIPLE'
 + * (relational:procedureParameter) = relational:procedureParameter copy sns
 + * (relational:procedureResult) = relational:procedureResult copy


// -------------------------------------------
// Logical Relationships
// -------------------------------------------

[relational:logicalRelationshipEnd] > nt:unstructured, relational:relationalEntity
 - relational:multiplicity (string) < 'ONE', 'MANY', 'ZERO_TO_ONE', 'ZERO_TO_MANY', 'UNSPECIFIED'
 - relational:table (weakreference)
 - relational:tableHref (string)
 - relational:tableXmiUuid (string)
 - relational:tableName (string)

[relational:logicalRelationship] > relational:relationship orderable
 + * (relational:logicalRelationshipEnd) = relational:logicalRelationshipEnd copy sns

// -------------------------------------------
// Catalogs and Schemas
// -------------------------------------------

[relational:schema] > nt:unstructured, relational:relationalEntity orderable
 + * (relational:table) = relational:baseTable copy
 + * (relational:procedure) = relational:procedure copy sns
 + * (relational:index) = relational:index copy
 + * (relational:logicalRelationship) = relational:logicalRelationship copy

[relational:catalog] > nt:unstructured, relational:relationalEntity orderable
 + * (relational:schema) = relational:schema copy
 + * (relational:table) = relational:baseTable copy
 + * (relational:procedure) = relational:procedure copy sns
 + * (relational:index) = relational:index copy
 + * (relational:logicalRelationship) = relational:logicalRelationship copy
]]></programlisting>
		</sect2>
	  <sect2 id="teiid-model-sequencer-nodetypes-jdbcs">
	    <title>JDBC Source Namespace</title>
			<para>
				The compact node definitions for the "jdbcs" namespace are as follows:
			</para>
<programlisting><![CDATA[
<nt  = "http://www.jcp.org/jcr/nt/1.0">
<xmi = "http://www.omg.org/XMI">
<jdbcs = "http://www.metamatrix.com/metamodels/JDBC">

//------------------------------------------------------------------------------
// N O D E T Y P E S
//------------------------------------------------------------------------------

[jdbcs:source] > nt:unstructured, xmi:referenceable
 - jdbcs:name (string) 
 - jdbcs:driverName (string) 
 - jdbcs:driverClass (string) 
 - jdbcs:username (string) 
 - jdbcs:url (string) 

[jdbcs:imported] > nt:unstructured, xmi:referenceable
 - jdbcs:createCatalogsInModel (boolean) = 'true' 
 - jdbcs:createSchemasInModel (boolean) = 'true' 
 - jdbcs:convertCaseInModel (string) < 'NONE', 'TO_UPPERCASE', 'TO_LOWERCASE'
 - jdbcs:generateSourceNamesInModel (string) = 'UNQUALIFIED' < 'NONE', 'UNQUALIFIED', 'FULLY_QUALIFIED'
 - jdbcs:includedCatalogPaths (string) multiple 
 - jdbcs:includedSchemaPaths (string) multiple 
 - jdbcs:excludedObjectPaths (string) multiple 
 - jdbcs:includeForeignKeys (boolean) = 'true' 
 - jdbcs:includeIndexes (boolean) = 'true' 
 - jdbcs:includeProcedures (boolean) = 'false' 
 - jdbcs:includeApproximateIndexes (boolean) = 'true' 
 - jdbcs:includeUniqueIndexes (boolean) = 'false' 
 - jdbcs:includedTableTypes (string) multiple 
]]></programlisting>
		</sect2>
	  <sect2 id="teiid-model-sequencer-nodetypes-transformation">
	    <title>Transformation Namespace</title>
			<para>
				The compact node definitions for the "transformation" namespace are as follows:
			</para>
<programlisting><![CDATA[
<transform='http://www.metamatrix.com/metamodels/Transformation'>

//------------------------------------------------------------------------------
// N O D E T Y P E S
//------------------------------------------------------------------------------

[transform:transformed] mixin
 - transform:transformedFrom (weakreference)
 - transform:transformedFromHrefs (string)
 - transform:transformedFromXmiUuids (string)
 - transform:transformedFromNames (string)

[transform:withSql] mixin
 - transform:selectSql (string) 
 - transform:insertSql (string) 
 - transform:updateSql (string) 
 - transform:deleteSql (string) 
 - transform:insertAllowed (boolean) = 'true' 
 - transform:updateAllowed (boolean) = 'true' 
 - transform:deleteAllowed (boolean) = 'true' 
 - transform:outputLocked (boolean) = 'false' 
 - transform:insertSqlDefault (boolean) = 'true' 
 - transform:updateSqlDefault (boolean) = 'true' 
 - transform:deleteSqlDefault (boolean) = 'true' 
]]></programlisting>
		</sect2>
	</sect1>
  <sect1 id="teiid-model-sequencer-default-values">
    <title>Default values</title>
    <para>
      Teiid Designer does not persist default values in the XMI files. The sequencer knows these default values, and includes
			them in the sequenced output so that they can be accessed and queried.
		</para>
	</sect1>
  <sect1 id="teiid-model-sequencer-annotations">
    <title>Annotations</title>
    <para>
      Rather than creating a separate "Annotation" object like what exist in the XMI models, the annotation's description and keywords 
			are simply recorded as a "<code>mmcore:description</code>" and "<code>mmcore:keywords</code>" properties on the node created for 
			the target of the annotation. This is really nice, because if a description is placed on a relational column object in a model, 
			then that description appears as a property directly on the corresponding "<code>relational:column</code>" node. 
			Note that when any annotation properties are placed on a node, the "<code>mmcore:annotated</code>" mixin is added to that node.
		</para>
	</sect1>
  <sect1 id="teiid-model-sequencer-tags">
    <title>Tags</title>
    <para>
      Tags are also stored on "Annotation" objects, and each tag consist of a key-value pair. The sequencer does two things depending 
			upon what the key looks like. When the key is a simple string without a ':', then a property is created on the annotation's 
			target object using this string as the property name and the tag's value as the property's value. More recently Teiid 
			Designer has started to use tags with keys of the form "<code>namespace:name</code>", where "<code>namespace</code>" is really
			informal and can theoretically be any string value. While this format is the same as JCR property names, treating them as 
			namespaced JCR property names would require there be a namespace URI registered with the prefix matching the "namespace" value.
		</para>
		<para>
			The sequencer tries to parse the tag key as a property name, and if it works then the tag is added as a property just as mentioned earlier. 
			However, if the namespace does not exist, then the sequencer splits the key into the two parts, where the first is used to 
			identify a child node and the second is used as a property name. 
		</para>
		<para>
			For example, a tag on the "ID" column object under the "MyTable" base table: 
		</para>
		<para>
		<programlisting>foo="bar"</programlisting>
		</para>
		<para>
			will be stored as a property "<code>foo</code>" with value "<code>bar</code>" on the "<code>MyTable/ID</code>" node. However, the 
		</para>
		<programlisting>connection:driver-class="oracle.jdbc.OracleDriver"</programlisting>
		<para>
			tag on the same object would be stored as the "<code>driver-class</code>" property (with value "<code>oracle.jdbc.OracleDriver</code>")
			on the "<code>MyTable/ID/connection</code>" object.
		</para>
	</sect1>
  <sect1 id="teiid-model-sequencer-transformations">
    <title>Transformation</title>
    <para>
      The transformation information, like with annotations, is projected onto the nodes representing the model objects that are the 
			"output" of the transformation, where the objects that are "inputs" to the transformation are recorded as a (potentially multi-valued) 
			property on the "output" object, and the "<code>transform:transformed</code>" mixin is added to the output node. In other words, 
			virtual base tables, columns, procedures, etc., are marked as "transform:transformed" and have an "input" property pointing to the 
			node(s) that are the inputs for the transformation. The SQL statements, supports flags, and defaults flags are also added as 
			properties on the output virtual base table and procedures, and the "<code>transform:withSql</code>" mixin that defines these 
			properties is added to that output node.
		</para>
	</sect1>
  <sect1 id="teiid-model-sequencer-using">
    <title>Configuration</title>
    <para>
        To use this sequencer, simply include the <code>modeshape-sequencer-teiid-&versionNumber;.jar</code> file
        in your application and define a sequencing configuration in the ModeShape configuration it using something similar to:
    </para>
   	<programlisting language="XML" role="XML"><![CDATA[
<configuration xmlns:mode="http://www.modeshape.org/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0">
    <mode:sequencers>
	      ...
        <mode:sequencer jcr:name="Teiid Model Sequencer" mode:classname="org.modeshape.sequencer.teiid.ModelSequencer">
            <mode:description>Sequences Teiid relational models (e.g., *.xmi) loaded into the repository under '/files', extracting the structure defined in the models.</mode:description>
            <!-- Note this path expression captures the path below '/files' but excludes the filename, and places the sequenced
                 content under the same relative path below '/sequenced/teiid/models'. For example, if an XMI model is uploaded
                 to '/files/my/favorites/CustomerDetails.xmi', then the sequenced output will be placed at
                 the '/sequenced/teiid/models/CustomerDetails' node, which will have a primary type of 'xmi:model' and will
                 contain under it the nodes representing the catalogs, schemas, tables, views, columns, etc. Of course, the 
                 path expression can be modified as needed; for example, to include the filename of the XMI model in the 
                 sequenced output path. -->
            <mode:pathExpression>/files(//)(*.xmi[*])/jcr:content[@jcr:data] => /sequenced/teiid/models$1 </mode:pathExpression>
        </mode:sequencer>
        ...
    </mode:sequencers>
    ...
</configuration>
]]></programlisting>
		<para>or using the &JcrConfiguration;:</para>
   	<programlisting language="JAVA" role="JAVA"><![CDATA[
JcrConfiguration config = ...

config.sequencer("Teiid Model Sequencer")
      .usingClass(ModelSequencer.class)
      .setDescription("Sequences Teiid relational models")
      .sequencingFrom("/files(//)(*.xmi[*])/jcr:content[@jcr:data]")
      .andOutputtingTo("/sequenced/teiid/models$1");
]]></programlisting>
	</sect1>
  <sect1 id="teiid-model-sequencer-example">
    <title>Example</title>
    <para>
       Here is a representation of the nodes output by the sequencing of an example virtual relational model:
    </para>
  	<programlisting><![CDATA[
PartsVirtual jcr:primaryType="xmi:model" 
   - jcr:mixinTypes=["mmcore:model","mix:referenceable","xmi:referenceable", "mode:derived"]
   - mode:derivedAt="2011-05-13T13:12:03.925Z" 
   - mode:derivedFrom="/files/foo.xmi"
   - jcr:uuid="d1a1b82f-055b-4db2-a3e7-a9668f3a70b6"
   - mmcore:maxSetSize="100"
   - mmcore:modelType="VIRTUAL"
   - mmcore:originalFile="/model/parts/PartsVirtual.xmi"
   - mmcore:primaryMetamodelUri="http://www.metamatrix.com/metamodels/Relational"
   - mmcore:producerName="Teiid Designer"
   - mmcore:producerVersion="6.0"
   - mode:sha1="84a77940f9140a358861d12d4bbb4160afadc08c"
   - mmcore:supportsDistinct="true"
   - mmcore:supportsJoin="true"
   - mmcore:supportsOrderBy="true"
   - mmcore:supportsOuterJoin="true"
   - mmcore:supportsWhereAll="true"
   - xmi:uuid="fb52cb80-128a-1eec-8518-c32201e76066"
   - xmi:version="2.0"
   - mmcore:visible="true"
   PartSupplier_SourceB jcr:primaryType="mmcore:import"
     - jcr:mixinTypes=["mix:referenceable","xmi:referenceable"]
     - jcr:uuid="c3a98bf2-7dbf-4c46-8baa-bf32e389cddd"
     - mmcore:modelType="PHYSICAL"
     - mmcore:primaryMetamodelUri="http://www.metamatrix.com/metamodels/Relational"
     - xmi:uuid="mmuuid:980de782-b1e5-1f55-853c-ed5dfdd1bb78"
   PartsSupplier_SourceA jcr:primaryType="mmcore:import"
     - jcr:mixinTypes=["mix:referenceable","xmi:referenceable"]
     - jcr:uuid="55385418-01c9-4d5c-9f79-91b8e10c6946"
     - mmcore:modelType="PHYSICAL"
     - mmcore:primaryMetamodelUri="http://www.metamatrix.com/metamodels/Relational"
     - xmi:uuid="mmuuid:980de784-b1e5-1f55-853c-ed5dfdd1bb78"
   XMLSchema jcr:primaryType="mmcore:import"
     - jcr:mixinTypes=["mix:referenceable","xmi:referenceable"]
     - jcr:uuid="8b5c2268-0770-405b-a4d8-12a868cc27a4"
     - mmcore:modelType="PHYSICAL"
     - mmcore:primaryMetamodelUri="http://www.eclipse.org/xsd/2002/XSD"
     - xmi:uuid="mmuuid:a6591280-bf1d-1f2c-9911-b53abd16b14e"
   SupplierInfo jcr:primaryType="relational:baseTable" 
     - jcr:mixinTypes=["transform:transformed","mix:referenceable","xmi:referenceable"] 
     - jcr:uuid="37bf368e-0618-4f2f-b4c2-2ab4c0729502"
     - transform:deleteAllowed="true"
     - transform:deleteSqlDefault="true"
     - transform:inputHrefs="PartsSupplier_SourceA.xmi#mmuuid/bc400080-1284-1eec-8518-c32201e76066"
     - transform:inputXmiUuids="bc400080-1284-1eec-8518-c32201e76066"
     - transform:insertAllowed="true"
     - transform:insertSqlDefault="true"
     - relational:materialized="false"
     - transform:selectSql="SELECT PartSupplier_Oracle.SUPPLIER_PARTS.SUPPLIER_ID, PartSupplier_Oracle.SUPPLIER_PARTS.PART_ID, PartSupplier_Oracle.SUPPLIER_PARTS.QUANTITY, PartSupplier_Oracle.SUPPLIER_PARTS.SHIPPER_ID, PartsSupplier_SQLServer.SUPPLIER.SUPPLIER_NAME, PartsSupplier_SQLServer.SUPPLIER.SUPPLIER_STATUS, PartsSupplier_SQLServer.SUPPLIER.SUPPLIER_CITY, PartsSupplier_SQLServer.SUPPLIER.SUPPLIER_STATE FROM PartSupplier_Oracle.SUPPLIER_PARTS, PartsSupplier_SQLServer.SUPPLIER WHERE PartSupplier_Oracle.SUPPLIER_PARTS.SUPPLIER_ID = PartsSupplier_SQLServer.SUPPLIER.SUPPLIER_ID"
     - relational:supportsUpdate="true"
     - relational:system="false"
     - transform:updateAllowed="true"
     - transform:updateSqlDefault="true"
     - xmi:uuid="2473dbc0-128c-1eec-8518-c32201e76066"
     SUPPLIER_ID jcr:primaryType="relational:column"
       - jcr:mixinTypes=["transform:transformed","mix:referenceable","xmi:referenceable"]
	     - jcr:uuid="5f62a519-7948-4c9d-95df-131b489cec8e"
       - relational:autoIncremented="false"
       - relational:caseSensitive="true"
       - relational:currency="false"
       - relational:distinctValueCount="-1"
       - transform:inputHrefs="PartSupplier_SourceB.xmi#mmuuid/55e12d01-1275-1eec-8518-c32201e76066"
       - transform:inputXmiUuids="55e12d01-1275-1eec-8518-c32201e76066"
       - relational:length="10"
       - relational:nativeType="VARCHAR2"
       - relational:nullValueCount="-1"
       - relational:nullable="NULLABLE"
       - relational:radix="10"
       - relational:searchability="SEARCHABLE"
       - relational:selectable="true"
       - relational:signed="true"
       - relational:typeHref="http://www.w3.org/2001/XMLSchema#string"
       - relational:typeName="string"
       - relational:typeXmiUuid="bf6c34c0-c442-1e24-9b01-c8207cd53eb7"
       - relational:updateable="true"
       - xmi:uuid="143ff680-1291-1eec-8518-c32201e76066"
     PART_ID jcr:primaryType="relational:column"
       - jcr:mixinTypes=["transform:transformed","mix:referenceable","xmi:referenceable"]
	     - jcr:uuid="bcce191f-acfd-48b9-8be8-ea04c0d37283"
       - relational:autoIncremented="false"
       - relational:caseSensitive="true"
       - relational:currency="false"
       - relational:distinctValueCount="-1"
       - relational:fixedLength="true"
       - transform:inputHrefs="PartSupplier_SourceB.xmi#mmuuid/54ed0902-1275-1eec-8518-c32201e76066"
       - transform:inputXmiUuids="54ed0902-1275-1eec-8518-c32201e76066"
       - relational:length="4"
       - relational:nativeType="CHAR"
       - relational:nullValueCount="-1"
       - relational:nullable="NULLABLE"
       - relational:radix="10"
       - relational:searchability="SEARCHABLE"
       - relational:selectable="true"
       - relational:signed="true"
       - relational:typeHref="http://www.w3.org/2001/XMLSchema#string"
       - relational:typeName="string"
       - relational:typeXmiUuid="bf6c34c0-c442-1e24-9b01-c8207cd53eb7"
       - relational:updateable="true"
       - xmi:uuid="1d9b97c0-1291-1eec-8518-c32201e76066"
     QUANTITY jcr:primaryType="relational:column"
       - jcr:mixinTypes=["transform:transformed","mix:referenceable","xmi:referenceable"]
	     - jcr:uuid="126d6138-ce5e-40e3-92d9-48a239453dbb"
       - relational:autoIncremented="false"
       - relational:caseSensitive="true"
       - relational:currency="false"
       - relational:distinctValueCount="-1"
       - relational:fixedLength="true"
       - transform:inputHrefs="PartSupplier_SourceB.xmi#mmuuid/55e12d02-1275-1eec-8518-c32201e76066"
       - transform:inputXmiUuids="55e12d02-1275-1eec-8518-c32201e76066"
       - relational:nativeType="NUMBER"
       - relational:nullValueCount="-1"
       - relational:nullable="NULLABLE"
       - relational:precision="3"
       - relational:radix="10"
       - relational:searchability="SEARCHABLE"
       - relational:selectable="true"
       - relational:signed="true"
       - relational:typeHref="http://www.w3.org/2001/XMLSchema#short"
       - relational:typeName="short"
       - relational:typeXmiUuid="5bbcf140-b9ae-1e21-b812-969c8fc8b016"
       - relational:updateable="true"
       - xmi:uuid="250ef100-1291-1eec-8518-c32201e76066"
     SHIPPER_ID jcr:primaryType="relational:column"
       - jcr:mixinTypes=["transform:transformed","mix:referenceable","xmi:referenceable"]
	     - jcr:uuid="d9856363-6950-40ea-9c9a-44c4af43ec38"
       - relational:autoIncremented="false"
       - relational:caseSensitive="true"
       - relational:currency="false"
       - relational:distinctValueCount="-1"
       - relational:fixedLength="true"
       - transform:inputHrefs="PartSupplier_SourceB.xmi#mmuuid/54ed0903-1275-1eec-8518-c32201e76066"
       - transform:inputXmiUuids="54ed0903-1275-1eec-8518-c32201e76066"
       - relational:nativeType="NUMBER"
       - relational:nullValueCount="-1"
       - relational:nullable="NULLABLE"
       - relational:precision="2"
       - relational:radix="10"
       - relational:searchability="SEARCHABLE"
       - relational:selectable="true"
       - relational:signed="true"
       - relational:typeHref="http://www.w3.org/2001/XMLSchema#short"
       - relational:typeName="short"
       - relational:typeXmiUuid="5bbcf140-b9ae-1e21-b812-969c8fc8b016"
       - relational:updateable="true"
       - xmi:uuid="2b8e2640-1291-1eec-8518-c32201e76066"
     SUPPLIER_NAME jcr:primaryType="relational:column"
       - jcr:mixinTypes=["transform:transformed","mix:referenceable","xmi:referenceable"]
	     - jcr:uuid="d0b9d5cc-f95a-4e97-a3f9-59571f58e206"
       - relational:autoIncremented="false"
       - relational:caseSensitive="true"
       - relational:currency="false"
       - relational:distinctValueCount="-1"
       - transform:inputHrefs="PartsSupplier_SourceA.xmi#mmuuid/bc400084-1284-1eec-8518-c32201e76066"
       - transform:inputXmiUuids="bc400084-1284-1eec-8518-c32201e76066"
       - relational:length="30"
       - relational:nativeType="varchar"
       - relational:nullValueCount="-1"
       - relational:nullable="NULLABLE"
       - relational:radix="10"
       - relational:searchability="SEARCHABLE"
       - relational:selectable="true"
       - relational:signed="true"
       - relational:typeHref="http://www.w3.org/2001/XMLSchema#string"
       - relational:typeName="string"
       - relational:typeXmiUuid="bf6c34c0-c442-1e24-9b01-c8207cd53eb7"
       - relational:updateable="true"
       - xmi:uuid="34da8540-1291-1eec-8518-c32201e76066"
     SUPPLIER_STATUS jcr:primaryType="relational:column"
       - jcr:mixinTypes=["transform:transformed","mix:referenceable","xmi:referenceable"]
	     - jcr:uuid="06253965-9f6f-4d6e-8219-2eb70a2745ed"
       - relational:autoIncremented="false"
       - relational:caseSensitive="true"
       - relational:currency="false"
       - relational:distinctValueCount="-1"
       - relational:fixedLength="true"
       - transform:inputHrefs="PartsSupplier_SourceA.xmi#mmuuid/bc400083-1284-1eec-8518-c32201e76066"
       - transform:inputXmiUuids="bc400083-1284-1eec-8518-c32201e76066"
       - relational:nativeType="numeric"
       - relational:nullValueCount="-1"
       - relational:nullable="NULLABLE"
       - relational:precision="2"
       - relational:radix="10"
       - relational:searchability="SEARCHABLE"
       - relational:selectable="true"
       - relational:signed="true"
       - relational:typeHref="http://www.w3.org/2001/XMLSchema#short"
       - relational:typeName="short"
       - relational:typeXmiUuid="5bbcf140-b9ae-1e21-b812-969c8fc8b016"
       - relational:updateable="true"
       - xmi:uuid="3c4dde80-1291-1eec-8518-c32201e76066"
     SUPPLIER_CITY jcr:primaryType="relational:column"
       - jcr:mixinTypes=["transform:transformed","mix:referenceable","xmi:referenceable"]
	     - jcr:uuid="a9cfd1fd-1a99-4b7d-83dc-3dbeb86c7f0a"
       - relational:autoIncremented="false"
       - relational:caseSensitive="true"
       - relational:currency="false"
       - relational:distinctValueCount="-1"
       - transform:inputHrefs="PartsSupplier_SourceA.xmi#mmuuid/bc400081-1284-1eec-8518-c32201e76066"
       - transform:inputXmiUuids="bc400081-1284-1eec-8518-c32201e76066"
       - relational:length="30"
       - relational:nativeType="varchar"
       - relational:nullValueCount="-1"
       - relational:nullable="NULLABLE"
       - relational:radix="10"
       - relational:searchability="SEARCHABLE"
       - relational:selectable="true"
       - relational:signed="true"
       - relational:typeHref="http://www.w3.org/2001/XMLSchema#string"
       - relational:typeName="string"
       - relational:typeXmiUuid="bf6c34c0-c442-1e24-9b01-c8207cd53eb7"
       - relational:updateable="true"
       - xmi:uuid="43c137c0-1291-1eec-8518-c32201e76066"
     SUPPLIER_STATE jcr:primaryType="relational:column"
       - jcr:mixinTypes=["transform:transformed","mix:referenceable","xmi:referenceable"]
	     - jcr:uuid="8e040c5d-acf8-407f-a090-4bc1feac45cc"
       - relational:autoIncremented="false"
       - relational:caseSensitive="true"
       - relational:currency="false"
       - relational:distinctValueCount="-1"
       - transform:inputHrefs="PartsSupplier_SourceA.xmi#mmuuid/bc400082-1284-1eec-8518-c32201e76066"
       - transform:inputXmiUuids="bc400082-1284-1eec-8518-c32201e76066"
       - relational:length="2"
       - relational:nativeType="varchar"
       - relational:nullValueCount="-1"
       - relational:nullable="NULLABLE"
       - relational:radix="10"
       - relational:searchability="SEARCHABLE"
       - relational:selectable="true"
       - relational:signed="true"
       - relational:typeHref="http://www.w3.org/2001/XMLSchema#string"
       - relational:typeName="string"
       - relational:typeXmiUuid="bf6c34c0-c442-1e24-9b01-c8207cd53eb7"
       - relational:updateable="true"
       - xmi:uuid="4a4faf40-1291-1eec-8518-c32201e76066"
]]></programlisting>
	</sect1>
</chapter>
