JBoss.orgCommunity Documentation

Chapter 6. Creating and Editing Model Objects

6.1. Creating New Model Objects
6.1.1. New Child Action
6.1.2. New Sibling Action
6.1.3. New Association Action
6.2. New Model Object Wizards
6.2.1. Create Relational Table Wizard
6.2.2. Create Relational Procedure Wizard
6.2.3. Create Relational Index Wizard
6.2.4. Create View Model Objects Wizards
6.3. Model Object Editors
6.3.1. Transformation Editor
6.3.2. Input Set Editor (XML)
6.3.3. Choice Editor (XML)
6.3.4. Recursion Editor (XML)
6.3.5. Operation Editor
6.4. Managing Model Object Extensions
6.4.1. Create New MED
6.4.2. Edit MED
6.4.3. Extending Models With MEDs
6.4.4. Setting Extended Property Values

This section summarizes Teiid Designer features for creating and editing existing model objects contained in your models.

As discussed in the introduction, Section 1.1, “What is Teiid Designer?”, Teiid Designer provides a framework to model various types of metadata. Each metamodel type has a set of parent-child relationships that establish constraints on what can be created and where. You cannot, for example, create a column attribute in a stored procedure, nor can you create a mapping class column in a Web service operation's output message.

The Teiid Designer provides a common set of actions to create new children of these models as well as children of children.

  • To create new associations between model objects in the Section D.3.1.2, “Diagram Editor”:

    • Step 1 - Select two objects you wish to associate. For example, select columns in different base tables.

    • Step 2 - Right-click. From the pop-up menu, select New Association > Foreign Key Relationship..

    • Step 3 - The new relationship link is displayed in the diagram. The Column, Foreign Key, Primary Key reference properties are properly set on the selected columns, new primary key and new foreign key.

    OR

    • Step 1 - Select a column in table.

    • Step 2 - Drag the column to another table and drag over a column and drop onto this column. The target column should highlight in Yellow.

    • Step 3 - The new relationship link is displayed in the diagram. The Column, Foreign Key, Primary Key reference properties are properly set on the selected columns, new primary key and new foreign key.

  • To create new associations between model objects in the Section D.3.1.3, “Table Editor”:

    • Step 1 - Select two objects you wish to associate. For example, select columns in different base tables.

    • Step 2 - Right-click. From the pop-up menu, select New Association > Foreign Key Relationship..

    • Step 3 - New Foreign Key and Primary Key objects will be added to the contents of their respective tabs in the Table Editor. The Column, Foreign Key, Primary Key reference properties are properly set on the selected columns, new primary key and new foreign key.

In addition to the simple new object actions, Teiid Designer provides New Child and New Sibling wizards for children of view and source relational models. Namely tables, views, procedures and indexes. The menu now looks like:


The Create Relational Procedure Wizard, shown below, allows creating a complete relational Procedure including columns, unique keys, foreign keys definition and indexes. The relational procedure object can represent different types of procedures, including a standard procedure, source function (pushdown function) and native query procedures. When the New Child > Procedure... action is launched the first dialog gives you the option of selecting the procedure type. Note that user defined functions can be modeled in a view model.


The second dialog customizes the Create Relational Procedure dialog based on your selected type. The following dialog provides standard procedure data input.


Source functions are procedures that are already deployed and accessable on your database. By defining source functions in your relational model, you can call these functions from within your transformation SQL and the functions will be pushed down to your database for execution.


Native query procedures are procedures that are already deployed and accessable on your database. By defining source functions in your relational model, you can call these functions from within your transformation SQL and the functions will be pushed down to your database for execution.

The resulting Create Relational Native Query Procedure dialog defaults to the following procedure structure including 0 or more input parameters (defined by the user) and a result set with a single output column with object data type (user can edit/change the column name).


The primary actions for editing model objects are:

These actions are presented in Teiid Designer's main Edit menu and also in the right-click context menus for model objects selected in the Section D.2.1, “Model Explorer View”, Section D.3.1.2, “Diagram Editor” and Section D.3.1.3, “Table Editor”.

Modeling Sub-Menu

In addition to the New Child/Sibling/Association menus available for object creation Designer provides a Modeling > sub-menu which presents various object-specific actions which can be performed.

If you select a source table, for instance, the modeling menu below would be presented:


If a view table is selected, the menu would reflect the actions related to virtual operations:


Teiid Designer also provides specialized object editors to handle complex model objects and their unique properties. These editors include:

This section describes these editors in detail.

The Teiid Designer's Transformation Editor enables you to create the query transformations that describe how to derive your virtual metadata information from physical metadata sources or other virtual metadata and how to update the sources.

The Transformation Editor provides a robust set of tools you can use to create these SQL queries. You can use these tools, or you can simply type a SQL query into the Transformation Editor.

To edit a transformation you can:

If a Model Editor is not currently open for the selected object's model, a Model Editor will be opened.

After the corresponding transformation diagram is opened in the Diagram Editor, the Transformation Editor is displayed in the lower section of the Diagram Editor.


If this virtual class supports updates, the tabs on the bottom of the Transformation Editor allow you to enter SQL for each type of query this virtual class supports. If this virtual class does not support updates, only the SELECT tab is available.

You can enter separate SQL queries on each available tab to accommodate that type of query.

Within the Transformation Editor, you can:

  • Disable specific update transformation types on this virtual class.

  • Start your transformation with a provided SQL Template.

  • Build or edit a criteria clause to use in your transformation.

  • Build or edit an expression to use in your transformation.

  • Find and replace a string within your transformation.

  • Validate the transformation to ensure its content contains no errors.

  • Reconcile target attributes to ensure the symbols in your transformation match the attributes in your virtual metadata class.

You can also set preferences that impact the display of your Transformation Editor. For more information, see Section C.1.2.3, “Transformation Editor Preferences”

  • The Transformation Editor toolbar actions are summarized below.

    • Prevew Virtual Data - executes a simple preview query for the target table or procedure of the transformation being edited.

    • Search Transformations - provides a simple way select and edit another transformation based SQL text search criteria.

    • Edit Transformation - provides a simple way to change which transformation to edit without searching in a diagram or the Model Explorer. Simply click the action and select from a list of views, tables, procedures or operations from the currently edited model.

    • Cursor Position (line, column) - shows the current line and column position of the insertion cursor. For example, Cursor Position(1,4) indicates that the cursor is presently located at column 4 of line 1.

    • Supports Update - checkbox allows you to enable or disable updates for the current transformation target. If 'Supports Update' is checked, the editor shows four tabs at the bottom for the Select, Update, Insert and Delete transformations. If 'Supports Update' is unchecked, all updates are disabled and only the Select transformation is displayed.

    • Reconcile - allows you to resolve any discrepancies between the transformation symbols and the target attributes. Pressing this button will display the "Reconcile Virtual Target Attributes" dialog box in which you can resolve discrepancies. See Section 6.3.1.1, “Using the Reconciler” for more information about the Reconciler Dialog.

    • Save/Validate - saves edits to the current transformation and validates the transformation SQL. Any Warning or Error messages will be displayed at the bottom of the editor in the messages area. If the SQL validates without error, the message area is not displayed.

    • Criteria Builder - allows you to build a criteria clause in your transformation. The button will enable if the cursor position is within a query that allows a criteria. Pressing the button will launch the Criteria Builder dialog. If the Criteria Builder is launched inside an existing criteria, that criteria will be displayed for edit, otherwise the Criteria Builder will be initially empty. See Section 6.3.1.3, “Using the Criteria Builder” for further information.

    • Expression Builder - allows you to build an expression within your transformation. The button will enable if the cursor position is at a location that allows an expression. Pressing the button will launch the Expression Builder dialog. If the Expression Builder is launched inside an existing expression, that expression will be displayed for edit, otherwise the Expression Builder will be initially empty. See Section 6.3.1.4, “Using the Expression Builder” for further information.

    • Expand Select * - allows you to expand a "SELECT *" clause into a SELECT clause which contains all of the SELECT symbols. The button will enable only if the cursor is within a query that contains a SELECT * clause that can be expanded.

    • Increase Font Size - increases the font size of all editor text by 1.

    • Decrease Font Size - decreases the font size of all editor text by 1.

    • Show/Hide Messages - toggles the display of the message area at the bottom of the transformation editor.

    • Optimize SQL - when toggled 'ON', will use the short names of all SQL symbols that can be optimized. Some symbol names may remain fully qualified in the event of a duplicate name or if the optimizer is unable to optimize it. When the action is toggled 'OFF', all symbol names will be fully-qualified.

    • Import SQL Text - allows you to import a sql statement from a text file on your file system. Pressing this button will display an import dialog in which you can navigate to the file.

    • Export SQL Text - allows you to export the currently displayed SQL statement into a text file on your file system. Pressing this button will display an export dialog in which you can choose the location for export.

    • Close "X" - closes the transformation editor.

  • The Transformation Editor context menu can be displayed by Rt-Clicking within the editor's text area. The context menu is show below:


    Following is a summary of the context menu actions:

The Transformation Editor’s Reconciler offers you a quick, graphical means to reconcile the Target View attributes and the Transformation SQL. As you make changes, the overall status will appear at the top of the dialog to assist you in successfully completing your edits.

To launch the Reconciler, click on the Reconcile Transformation button in the Transformation Editor. The Reconciler Dialog is shown below:


To summarize the different sections of the dialog:

Once you are finished defining the bindings and resolving datatypes, click 'OK' to accept the changes. The transformation SQL will change to reflect your edits.

This dialog is accessible from the Reconciler dialog (See Section 6.3.1.1, “Using the Reconciler”) and offers you a quick way to resolve datatype conflicts between a target attribute and its SQL Symbol. The Datatype Resolver Dialog is shown below:


To summarize the different sections of the dialog:

  • Target Attribute - SQL Symbol Table: This table shows all target attribute - SQL Symbol bindings from the Reconciler Dialog which have a type conflict. Select on a table row to populate the lower Edit Panel

  • Edit Panel: The lower panel shows the Target Attribute and SQL Symbol datatype information for the selected binding. You can resolve the conflict in one of the following ways:

    • Virtual Target Attribute: Resolve the type conflict by changing the target attribute type to be compatible with the SQL Symbol type. The attribute's current runtime type is shown, along with a potential new datatype - and some button controls:

      • Apply Button: If the suggested datatype is acceptable, click 'Apply' to allow the attribute type to be changed.
      • Convert All Button: If you wish to change all of the attribute types in the table to be compatible with its corresponding SQL Symbol datatype, click the 'Convert All' button.
      • Change Button: If the suggested datatype is not acceptable, click 'Change' to choose your own datatype from a datatype dialog.
    • SQL Symbol: Resolve the type conflict by applying a CONVERT function to the SQL Symbol, so that its type is compatible with the target attribute type. The SQL Symbol's current type is shown, along with a suggested CONVERT function - and two button controls:

      • Apply Button: If the suggested CONVERT function is acceptable, click 'Apply' to apply the CONVERT function to the SQL Symbol.
      • Convert All Button: If you wish to apply a CONVERT function to all of the SQL Symbols in the table so that their datatype is compatible with the corresponding attribute datateyp, click the 'Convert All' button.

Once you are finished resolving datatypes, click 'OK' to accept the changes. You are directed back to the Reconciler Dialog, which will be updated to reflect your edits.

The Transformation Editor’s Criteria Builder offers you a quick, graphical means to build criteria clauses in your transformations based on meta objects in your diagram. If you launch the Criteria Builder with your cursor within an existing criteria in your transformation SQL, the builder will open in Edit mode. If your cursor is not in an existing criteria location, the builder will open in create mode and allow you to create it from scratch.

This procedure provides an example of building a criteria clause using the Criteria Builder. When building your own criteria, you can mix and match the values and constants with whatever logic you need to build powerful and complex criteria.

The criteria clause displays in the Criteria tree.

You can create complex criteria by joining other criteria with this one. To join criteria with this one, select the criteria in the Criteria tree and click:

  • Delete to remove the selected criterion.

  • AND to create a new criterion that must also be true.

  • OR to create a new criterion that can be true instead of the selected criterion.

  • NOT to establish negative criterion.

If you join a criterion to the one you just completed, you build the expression the same way, using the Expression Editors panel and the Predicate Editor panel. You can create complex, nested criteria by judicious use of the AND and OR buttons.

Once you have created the complete criteria you want, click OK to add it to your transformation.

The Transformation Editor’s Expression Builder offers you a quick, graphical means to build expressions in your transformations. This Expression Builder lets you create:

The Input Set represents a special class that contains attributes from a parent mapping class. When you create mapping classes for an XML Document model, Teiid Designer automatically adds an Input Set to all XML transformation diagrams for mapping classes beneath the highest node in the Document meta object.

The Input Set proves especially useful for information integration using the Teiid Server. Through the Input Set, you can access a row of data generated by any XML transformation in a mapping class higher in the XML document’s hierarchy. You can use Input Set attributes, which are individual columns from the rows of data, within the criteria of an XML transformation query of the child mapping class.

You cannot use the Input Set attributes within the SELECT portion of the XML transformation query.

To use an Input Set, you must use the Input Set Editor to bind attributes from parent classes.

Once you have created an Input Set, you can use the attributes within it as source material for the XML transformation diagram’s query.

The Input Set only serves to enable data flow between nested mapping classes. If you use the Teiid Server for data access, your applications cannot directly query an Input Set. Input Sets only display in the XML transformation diagram to which they belong. Input Sets do not display on the Section D.2.1, “Model Explorer View” view and you cannot use them as you would a normal class, such as for source classes in other transformations.

To open the Input Set Editor, either double-click the input set in the Mapping Transformation Diagram or click the edit button on the Input Set in the diagram. (see below)



The Input Parameters table contains a list of mapping attributes within the input set and the mapping attributes bound to input set mapping attributes. The tree on the right displays the parent mapping classes and the attributes available from each.

Using the Input Set Editor, you can:

  • Add a mapping attribute from a parent mapping class to the Input Set. In the tree on the right, select the symbol for which you want to create an attribute and click New. The item displays in the Input Parameters and Mapping Class Bindings table.

  • Delete a mapping attribute from the Input Set. Click the row in the Input Parameters and Mapping Class Bindings table that you want to delete and click Delete. The Teiid Designer removes this row from the table and this mapping attribute from your Input Set.

  • Bind and Unbind Input Parameters.

Once you have created the mapping attributes within the Input Set that you need, you can use the Input Set Parameters within a mapping class transformation to produce mapping attributes you can map to your XML document.

Within an XML Document model, a choice compositor defines all possible document data structures (sometimes called fragments) that can appear at that location in an XML instance document. When the Teiid Server populates an XML instance document at runtime based upon your virtual XML document, it will choose the first fragment that matches the criteria you specify within the Choice Editor.

To view the choice editor, right-click on the choice node in the mapping diagram's XML Document tree view and select Edit from the right-click pop up menu.



The table on this panel displays fragment options for the choice, each represented by the top node of the document fragment.

The Summary tab, shown below, displays a SQL-like version of the current choice criteria.


The XML Schema upon which you based the XML Document model determines the nature of the options available to the choice. A schema you share with other, external sources (such as business partners) might include information that you do not want to include within XML files.

For example, Sample Financial Services shares an XML schema with its partners Example Mutual Insurance, Illustrative Brokerage, and FinancialPartners.com. The partners created the schema broadly, to cover all possibilities for information they might need to interchange. As such, the customer information XML document might include a choice compositor based on a list of all products all companies offer.

However, Sample Financial does not offer a credit card; so it could exclude those elements from the XML documents its Teiid Designer Server creates since it will never have credit card information for an XML document.

The table on the Choice Editor contains the Include column. By default, all elements specified by the schema are included. You can click to remove the checkmark beside any element you do not want to include within your XML documents generated by this virtual XML document metadata model. By removing the checkmark, you are not removing the element from the XML Document model; you are merely telling the Teiid Server that it will never use this element as part of the choice.

You cannot edit criteria for excluded elements. However, if you exclude an option for which you have established a criteria, Teiid Designer will retain the criteria if you want to include the option in the future.

Some XML schemas define data structures that contain self-referencing elements or datatypes. When generating XML documents, such data structures can produce an endless repetition of nested tags. This self-nesting pattern is known as recursion.

When generating virtual documents from XML Schema, Teiid Designer detects recursive data structures in the XML Schema model and halts the recursive nesting pattern after two cycles. These two cycles serve different purposes when mapping the document:

You can recognize a mapping class located at the second, recursive document fragment by the looping arrow button in the top-left-hand corner of the diagram object as shown below.

When you model a virtual document based on an XML Schema model containing recursion, you can choose whether to treat the nested fragments as recursive. You should only use recursion when the data access pattern from your data source(s) is also recursive; in other words, when the same query transformation should be executed over and over to generate and map the nested document's data content.

By default, Teiid Designer does not mark the recursive fragments in document models to execute recursively in the Teiid Server. To take advantage of this behavior, you must open the Recursion Editor in the recursive mapping class Section D.3.1.2.5, “Mapping Transformation Diagram”, mark the transformation query as recursive, and specify the recursion limit properties.

The Recursion Editor lets you enable and limit recursion. The Recursion Editor button only displays on mapping classes, which have recursive patterns. For example, if you have an element named Employee which contains a element named Supervisor which itself contains an Employee element nested within it, you might need to limit the number of times the elements are nested within the document.

You can set the following conditions to limit the recursion:

To open the Recursion Editor, click on the Recursion Editor button on the displayed mapping class.



Note

The Teiid Server will evaluate this condition each time it recursively performs this query. If this criteria clause evaluates false, the Teiid Server performs the query recursively again unless it has reached the Count Limit. If the criteria evaluates true, the Teiid Server performs the mapping for the current level and ends its recursive loop.

When you have created the criteria, it displays in the Limit Condition box.

When the Teiid Server dynamically populates your XML documents at runtime, it will use the recursion specifications you entered here.

Editing of Web Service Operation transformations is simplified via the Operation Editor. When editing a Web Service model, an additional editor tab labeled "Operation Editor" is available. This editor, shown below is comprised of:


The Operations section contains all interfaces and operations currently defined in the model.

Selecting an operation will display the variables related to the input parameter's content in the Input Variables section and the body of its procedure (minus the CREATE VIRTUAL PROCEDURE BEGIN - END keywords and the input variable declarations and assignments) in the Procedure section.

When pasting in SQL, do not include the CREATE VIRTUAL PROCEDURE BEGIN - END keywords. Input variables will be automatically generated when the Content via Element property is set on an operation's input parameter. Input variables may be edited using the Edit link in the Input Variables section, and may only represent XPath values to single attributes and elements within the input contents; other variable declarations and assignments must be typed directly into the Procedure section. Clicking the Edit link will display the following dialog:


You can create new operations in the Operation Editor by right-clicking an interface or operation and selecting the Create Operation action. This will display a dialog for entering the definition for your new operation.



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: