Model Extension Framework

Extending a model adds extra properties to its model objects. One good use of these extension properties is for passing data to a customized Teiid translator. The Designer model extension framework consists of Model Extension Definitions (MEDs), a MED registry, a MED Editor, a MED Registry View, and MED-related modeling tasks.

 

Model Extension Definition (MED)

 

The purpose of a MED is to define one or more sets of extension properties. Each set of extension properties pertain to one model object type (or metaclass). Each MED consists of the following:

 

  • Namespace Prefix - a unique identifier. Typically only a small number of letters and can be used as an abbreviation for the namespace URI.
  • Namespace URI - a unique URI.
  • Extended Metamodel URI (Model Class) - the metamodel URI that is being extended. Each metamodel URI also has model class and that is typically what is shown in the Designer. Here are the model classes that currently can be extended: Relational, Web Service, XML Document, and Function.
  • Version- currently not being used.
  • Description - an optional description or purpose.
  • Extended Model Object Types (Metaclasses) - a set of model object types, or metaclasses, that have extension properties defined.
  • Properties - the extension property definitions grouped by model object type.

 

A MED file is an XML file with an extension of "mxd." A MED schema file (see attached modelExtension.xsd file) is used to validate a MED file. Here is a sample MED file:

 

 

<?xml version="1.0" encoding="UTF-8" standalone="no"?>

<modelExtension xmlns:p="http://org.teiid.modelExtension/2011"

                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

                metamodelUri="http://www.metamatrix.com/metamodels/Relational"

                namespacePrefix="mymodelextension" namespaceUri="org.my.extension.mymodelextension"

                version="1"

                xsi:schemaLocation="http://org.teiid.modelExtension/2011 modelExtension.xsd"

                xmlns="http://org.teiid.modelExtension/2011">

    <p:description>This is my model extension</p:description>

    <p:extendedMetaclass name="com.metamatrix.metamodels.relational.impl.BaseTableImpl">

        <p:property advanced="false" index="true" masked="false" name="copyable" required="false" type="boolean">

            <p:description locale="en_US">Indicates if table can be copied</p:description>

            <p:display locale="en_US">Copyable</p:display>

        </p:property>

    </p:extendedMetaclass>

</modelExtension>

 

 

The MED Registry is where the MEDs used by Designer are stored.

 

Model Extension Definition Registry (MED Registry)

 

A MED registry keeps track of all the MEDs that are registered in a workspace. Only registered MEDs can be used to extend a model. There are 2 different types of MEDs stored in the registry:

 

  1. Built-In MED - these are registered during Designer installation. These MEDs cannot be updated or unregistered by the user.
  2. User-Defined MED - these are created by the user. These MEDs can be updated, registered, and unregistered by the user.

 

The MED Registry state is persisted and is restored each time a new session is started.

 

Model Extension Definition Editor (MED Editor)

 

The MED Editor is a multi-tabbed editor and is used to create and edit user-defined MEDs (*.mxd files) in the workspace. The MED Editor has 3 sub-editors (Overview, Properties, and Source) which share a common header section. Here are the MED sub-editor tabs:

 

 

 

OverviewEditor.png

 

 

  • Properties Sub-Editor - this editor is where the MED extension properties are managed. Each extension property must be associated with a model object type. The Properties sub-editor is divided into 2 sections (Extended Model Objects and Extension Properties) and looks like this:

 

 

PropertiesEditor.png

 

 

In order to add an extension property you must first identify the model object type (metaclass) associated with that new property. There are toobar actions in the top section, Extended Model Objects, that add, remove, and edit model object types. Once the model object type is selected in the top section, use the toobar in the bottom section, Extension Properties, to add, remove, or edit extension properties.

 

When creating or editing an extension property this dialog is used:

 

 

EditPropertyDialog.png

 

 

Warning: Deleting a model object type (metaclass) will also delete all extension properties associated with that model object type.

 

 

  • Source Sub-Editor - a readonly, text view of the MED file. This tab always shows the last saved version of the file.

 

 

The GUI components on the Overview and Properties sub-editors will be decorated with an error icon when the data in that GUI component has a validation error. Hovering over an error decoration displays a tooltip with the specific error message. Those error message relate to the error messages shown in the common header section. Here is an example of the error decoration:

 

 

ErrorDecoration.jpg

 

 

  • Shared Header Section - The MED sub-editors share a header section. The header is composed of the following:

 

    • Status Image - an image indicating the most severe validation message (error, warning, or info). If there are no validation messages the model extension image is shown.
    • Title - the title of the sub-editor being shown.
    • Menu - a drop-down menu containing actions for (1) adding to and updating the MED in the registry, and (2) for showing the Model Extension Registry View.
    • Validation Message - this area will display an OK message or an error summary message. When a summary message is shown, the tooltip for that message will enumerate all the messages.
    • Toolbar - contains the same actions as the drop-down menu.

 

Here is what the shared header section and its error message tooltip look like:

 

 

SharedHeader.jpg

 

 

When a MED Editor is saved, the MED file is validated using the MED schema (see attached file). Any validation errors from the schema are shown in the Problems View. A MED cannot be registered unless all errors in the Problems View are cleared. The errors in the Problems View relate to the validation messages in the shared header but will not be as user-friendly.

 

The MED Editor can be opened by double-clicking a MED file in the Model Explorer or by using the context menu (select the MED file and Right-click -> Open With -> Model Extension Definition Editor).

 

Warning: Any XML editor or even any text editor can be used used to create and edit MED files. If an external XML editor is used the MED schema should be used for validation. However, using an editor different than the MED Editor there is always the possibility that the MED will be saved in an incorrect format and won't be able to be read in later by the MED editor.

 

Model Extension Definition Registry View (MED Registry View)

 

The Model Extension Registry View shows the currently registered MEDs. Registered MEDs can be applied to models in the workspace (see MED-related Model Tasks). The Model Extension Registry View looks like this:

 

 

Registry.png

 

 

For each registered MED, the namespace prefix, namespace URI, extended model class, version, and description is shown. In addition, a flag indicating if the MED is built-in is shown. The Model Extension Registry View has toolbar actions that register a workspace MED file, unregister a user-defined MED, and copy a registered MED to the workspace. All these actions are also available via a context menu.

 

Note: When a workspace MED is registered it can be deleted from the workspace if desired. The registry keeps its own copy. And a registered MED can always be copied back to the workspace by using the appropriate toolbar or context menu action.

 

The Model Extension Registry View can be opened by either selecting Window -> Show View -> Other -> Teiid Designer -> Model Extension Registry or by selecting the MED Editor toolbar action in the right corner of shared sub-editor header section.

 

MED-related Modeling Tasks

 

 

MEDs must be applied to a model in order for their extension properties to be available to that model's model objects. When a MED is applied to a model, the MED is actually stored in the model. Models can have more than one MED applied to it. Here are the modeling tasks relating to MEDs:

 

  • Manage Model Extension Definitions Dialog - this dialog is how MEDs are added to and removed from a model. If a MED stored in the model is different than the same MED in the registry, a couple other actions are available: saving that MED from the model to the workspace, and updating the MED in the model to the version stored in the registry. The Manage Model Extension Definitions Dialog looks like this:

 

 

ManageMedsDialog.png

 

 

When adding MEDs to a model, only the applicable MEDs will be available. Here is the dialog that will be used when adding a MED:

 

 

AddMedDialog.png

 

 

The Manage Model Extension Definitions Dialog can be opened by selecting the model in the Model Explorer and Right-click -> Modeling -> Manage Model Extension Definitions.

 

  • Properties View - this view is used to edit extension properties. All extension properties show up under the "Extension" category and are prefixed with the MED's namespace prefix. If there is an initial value for an extension property it will be set to the default value using the property defintion found in the MED.

 

 

PropertiesView.png

 

 

  • MEDs and Workspaces - MEDs can be imported to and exported from a workspace using the standard file system importer and  exporter respectively. If a registered MED is not in the workspace it can be copied from the registry using the appropriate action in the Model Extension Registry View toolbar or context menu.