This chapter discusses various features targeted at defining and managing metamodel-specific objects.
To improve ability to utilize database functions within View transformations, a new New Child > Source Function action and wizard was added to assist in building a source procedure that conforms to a function structure, including input and output parameters. Prior to Teiid Designer 7.5, these functions were required to be modeled as User Defined functions.
Running the action will display the Create New Source Function dialog. Enter your database function name, define input parameters including datatype and length, specify output parameter info, set options and click OK.
The resulting source function will be added to your model
and will be represented by the 
icon.
When finished, the new source function will be displayed in your model's package diagram.
After saving your model, your new source function will be available for use in your transformations. If you open the Expression builder, your source functions will be selectable in the Function drop-down selector for a Category named for the model as shown in the example below.
In Teiid Designer 7.6 a new action, New Child > Base Table..., was added to aid in creating tables, complete with all of it's child entities. This action replaces the original New Child > Base Table, which only created the empty table.
Running the action will display the Create Relational Table wizard. The wizard page contains 5 tabbed panels representing the various properties and components that make up the possible definition of a relational table. Enter your table name, define columns, keys, constraints and other options, then click OK.
This wizard is designed to provide feedback as to the completeness of the relational table information as well as the validation state of the table and it's components.
Note
Although errors may be displayed during editing, the wizard is designed to allow finishing with the construction of an incomplete table containing errors.
The first tab labeled Properties contains the input for the simple table properties including name, name in source, cardinality, supports update and is system table properties.
The Columns tab allows creation and editing of basic relational columns. This includes adding, deleting or moving columns as well as changing the name, datatype and length properties.
The Primary Key tab allows editing of the name, name in source and column definitions. Note that un-checking the box will clear the data. The Unique Constraint tab contains the identical information.
The Foreign Keys tab allows creating, editing and deleting multiple foreign keys.
To create a new Foreign Key, select the Add button and enter/select the properties, key references in the tables shown below.
Note
The Select Primary Key or Unique Constraint table will display any PK/UC existing in the selected relational model. If no tables in that model contain a PK or UC, then the table will be empty.
This section contains descriptions of various features related to creating and managing relational view model objects.
For any relational view table you can enable it's materialized view option by setting the Materialized property to TRUE and setting the Materialized Table reference, as shown in the figure below.
Note
You are required to have already created your relational tables.
Designer includes a feature to assist in quickly creating materialized relational tables based on your existing view tables.
To create materialized views:
- Step 1 -
Right-click on one or more view tables in the
Section D.2.1, “Model Explorer View” and select the
Modeling > Create Materialized
Views action.
Step 2 - In the Create Materialized View Model dialog specify or select a target relational model for your generated relational tables.
Step 2a - Selecting the browse '...' button displays the Relational Model Selector dialog where you select an existing relational model or specify a unique name for a new model.
Step 3 - Click OK to create relational tables corresponding to your selected view tables and automatically set the Materialized property to TRUE and the Materialized Table reference value to your newly generated table.
When finished your view tables will be configured with their new materialized properties and the corresponding relational tables will be shown in their package diagram.
In Teiid Designer 7.7 a new action, New Child > Base Table..., was added to aid in creating relational view tables, complete with its target columns and SQL transformation. This action replaces the original New Child > Base Table action, which only created the empty table.
Running the action will display the Create Relational View Table wizard. The wizard page contains 3 tabbed panels representing the various properties and components that make up the possible definition of a relational view table. Enter your table name, define the desired columns and specify the SQL transformation, then click OK.
This wizard is designed to provide feedback as to the completeness of the relational view table information, as well as the validation state of the table and it's components.
Note
Although errors or warnings may be displayed during editing, the wizard is designed to allow finishing even if the table definition is incomplete.
The first tab labeled Properties contains the input for the simple table properties including name and supports update.
The Columns tab allows creation and editing of basic relational columns. This includes adding, deleting or moving columns as well as changing the name, datatype and length properties.
The SQL tab allows editing of the SQL Transformation for the relational view. The desired SQL can be entered directly into the text area or a SQL Template may be selected by clicking the Templates... button.
If the Templates... button is selected on the SQL tab, the Choose a SQL Template dialog will display, as shown below.
A number of common SQL templates may be chosen using the dialog. Depending on usage context, the PROCEDURES tab may also be available in addition to the SELECT queries tab. The SQL Template dialog can also be accessed in the Transformation Editor, from the rt-click context menu.
You can create XML View Documents by selecting an element in the Model Explorer and selecting the Modeling > Create XML View Documents action.
The action will query you for a target XML Document model. You can either select an existing XML Document model from your workspace, or enter a unique model name and the wizard will create a new model for you.
After selecting or creating your new XML Document model, the XML Document builder page will be displayed. This page is explained in greater detail in Section 4.3.2, “Build XML Documents From XML Schema ” section.
This method is recommended for experienced users for consistent and rapid deployment of Web services designed to query relational sources. It provides detailed control of all Web service interfaces, operations and required transformations from XML Views
To create a Web service model from relational models or objects:
Step 1 - Select any combination of relational models, tables and/or procedures in the Section D.2.1, “Model Explorer View” tree.
Note
It is recommended that the user selects single source models, which enables auto-naming of input/output schema and Web service models in \ Step 3.
Step 2 - Right-click select Modeling > Create Web Service action
.Step 3 - In the Create Web Service dialog, specify file names for the generated Input Schema file, Output Schema file and Web service model. Change options as desired. Click Finish when done.
Step 4 - When model generation is complete, a confirmation dialog should appear. Click OK.
Teiid Designer allows you to expose your VDBs via a SOAP or REST interface. JBossWS-CXF or RESTEasy wars can be generated based on models within your VDBs. This section describes these wizards in detail.
The Teiid Designer provides web service generation capabilities in the form of a JBossWS-CXF war. Once you have added your Web Service Models as described in Section 4.5, “Creating Web Service View Model” to your VDB, deployed the VDB to a running Teiid instance and created your VDB's data source, you are ready to expose the web service using the generated war.
To generate a new JBossWS-CXF war using the VDB:
Step 1 - Right-click on the VDB containing your web service model(s) and select the Modeling > Generate JBossWS-CXF War action.
Step 2 - Fill in missing properties in Web Service War Generation Wizard shown below.
Table 7.1. Field Descriptions
Field Name Description Name The name of the generated war file. Host The server host name (or IP). Port The server port. VDB JNDI Name The JNDI connection name to the deployed Teiid source VDB. Security options
None - no username/password required to connect to the VDB through the generated web service.
HTTP Basic - the specified security realm and role will be used. The default realm value is the realm that comes out-of-the-box with Teiid ( teiid-security). The role needs to be defined in the appropriate security mechanism. In the case of Teiid, use the teiid-security-roles.properties file. When using HTTPBasic, a local Teiid connection using the PassthroughAuthentication property is required. See the Teiid user's manual for details on PassthroughAuthentication.
WS-Security - a password callback class will be generated for you which will validate that the username/password values you specified in the war generator dialog are passed in. This is meant to be a testing mechanism for your WS-Security enabled web service and your own security mechanism should be implemented in this class. All source code is included in the generated war along with the compiled class files.
Target namespace This is the target namespace that will be used in the generated WSDL and subsequent generated web service classes. MTOM (Message Transmission Optimization Mechanism) If selected, MTOM will be enabled for the web service endpoint(s). You will also need to update your output schema accordingly by adding the xmlns:xmime="http://www.w3.org/2005/05/xmlmim" schema and adding type="xs:base64Binary" xmime:expectedContentTypes="application/octet-stream" to the output element you wish to optimize. War File Save Location The folder where the generated WAR file should be saved.
Step 3 - Click OK to generate the web service war. When war generation is complete, a confirmation dialog should appear. Click OK.
In Teiid Designer, it is also possible to expose your VDBs over REST using a generated RESTEasy war. Also, if your target virtual model has update, insert and delete SQL defined, you can easily provide CRUD capabilities via REST. Accepted inputs into the generated REST operations are URI path parameters and/or XML/JSON. JSON is exposed over a URI that includes "json". For example, "http://{host}:{port}/{war_context}/{model_name}/resource" will accept URI path parameters and/or XML while "http://{host}:{port}/{war_context}/{model_name}/json/resource" will accept URI path parameters and/or JSON.
Step 1 - In a virtual model, add a procedure(s) that returns an XMLLiteral object. The target of your procedure can be any models in your VDB. Here is an example procedure that selects from a virtual table (VirtualBooks) and returns the results as an XMLLiteral:
Notice the syntax used to convert the relation table result of the select from VirtualBooks, to an XMLLiteral. All XML functions are documented in the Scalar Functions chapter of the Teiid Reference Guide.
Here is an example of an update procedure that will insert a row and return an XMLLiteral object:
The input format for the REST procedure could be URI parameters, an XML/JSON document, or some combination of both. When using an XML document your root node should be <input> and the XML nodes should correspond to order of the procedure's input parameters. For example, here is the input for the above insert procedure:
When using a JSON document, your values should match the order of your procedure input parameters as well. Here is the input for the above insert procedure:
Step 2 - Now we need to identify our procedure as REST eligible. To do this we add enable REST properties for the procedure(s) via the Modeling->Enable context menu option.
This will enable two new properties in the property tab for all procedures defined in the model. The two required properties are defined in the table below:
Table 7.2. Required Extended Properties for RESTful Procedures
Property Name Description Rest Method The HTTP method that will determine the REST mapping of this procedure. Supported methods are: GET, PUT, POST and DELETE URI The resource path to the procedure. For example, if you use “books/{isbn}” as your URI value for a procedure, http://{host}:{port}/{war_context}/{model_name}/books/123 would execute this procedure and pass 123 in as a parameter.
Here's what the above example would look like in the Property tab:
Note
The generated URI will have the model name included as part of the path, so full URL would look like this: http://{host}:{port}/{war_context}/{model_name}/books/123. If you wanted a REST service to return all books, you would write your procedure just as it is above, but remove the input parameter. The URI property would then just be 'books' (or whatever you want) and the URL would be http://{host}:{port}/{war_context}/{model_name}/books.
Once you have added all of your procedures along with the required extended properties, be sure and add the model to your VDB or synchronize if it's already included in the VDB. You will then need to re-deploy the VDB.
Important
If you redeploy your VDB during development, you may receive an "Invalid Session Exception"due to a stale connection obtained for the pool. This can be corrected by flushing the data source or, alternatively, you could add a test query to your VDB connection's -ds.xml file. This will insure you get a valid connection after redeploying your VDB. The syntax for the test query is as follows: <check-valid-connection-sql>some arbitrary sql</check-valid-connection-sql>"
Step 3 - 3. If you have not already done so, you will need to create a data source for your VDB. This can be done in the Teiid View of Designer. Right-click on your deployed VDB and select Create Data Source. The Generate REST WAR dialog will ask you for the JNDI name for your created source so that it can connect to your VDB.
Step 4 - Right-click on the VDB containing your virtual model(s) with REST eligible procedures and select the Modeling > Generate RESTEasy War action. If there are no procedures that are REST eligible, the "Generate RESTEasy War" option will not be enabled.
Step 5 - Fill in missing properties in the REST War Generation Wizard shown below.
Table 7.3. Field Descriptions
Field Name Description Name The name of the generated war file. Connection JNDI Name The JNDI connection name to the deployed Teiid source VDB. War File Save Location The folder where the generated WAR file should be saved. Include RESTEasy Jars in lib Folder of WAR If selected, the RESTEasy jars and there dependent jars will be included in the lib foled of the generated WAR. If not selected, the jars will not be included. This should be de-selected in environments where RESTEasy is installed in the classpath of the server installation to avoid conflicts.
Step 6 - Click OK to generate the REST war. When war generation is complete, a confirmation dialog should appear. Click OK.
Once you have generated your war file, you will need to deploy it to your JBoss AS instance. There are a few ways to accomplish this.
From JBDS or JBoss Tools
1. Insure target JBossAS is configured and running.
2. Select your WAR file in the Model Explorer view. If you didn't generate your war to that location, you can copy and paste it there.
3. Right-click on the WAR file and select 'Mark as Deployable'. This will cause you WAR file to be automatically deployed the JBoss AS instance you have defined.
Using the JBoss AS Administration Console
Using the administration console that comes with JBoss AS, you can deploy WAR files. The administration console is available at http://{host:port}/admin-console. Once logged on, simply use the "Add a New Resource" button of the "Web Application (WAR)" resource folder.
Manual Deployment to JBossAS
It is possible to deploy the generated WAR by manually copying the file to the "deploy" folder of the target JBoss AS. If the server is running, the WAR will deploy automaticall via "hot" deploy. Otherwise, the WAR will deploy at the next start of the server.
Once you have deployed your war file, you are ready to test it out. There are a few ways to accomplish this.
SOAP WAR Testing
Determining Your WSDL URL
You can get your WSDL URL at http://{server:port}/jbossws/services. This is where all the deployed web services for the target JBossAS server will be listed. Find your service and click the Endpoint Address link. This will retrieve your web service's WSDL and the WSDL URL address will appear in the browser's address bar.
Now that you have your WSDL URL, you can use any SOAP testing tool such as the Web Service Tester that comes with JBDS and JBoss Tools or an external tool like soapUI.
Using the JBoss AS Administration Console
Using the administration console that comes with JBoss AS, you can deploy WAR files. The administration console is available at http://{host:port}/admin-console. Once logged on, s simply use the "Add a New Resource" button of the "Web Application (WAR)" resource folder.
REST WAR Testing
What is my URI?
When you modeled your REST procedures, you assigned a URI for each HTTP Operation you defined along with the corresponding operation (GET, PUT, POST or DELETE). The full path of each URI is defined as /{war_context}/{model_name}/{resource} for XML input/output and /{war_context}/{model_name}/json/{resource} for JSON input/output.
Using your REST URL, you can use any testing tool with REST support such as the Web Service Tester included with JBDS and JBoss Tools or an external tool like soapUI or cURL.