Introduction
WebRatio 7.2 supports the XML Schema Definition to simplify the interaction with Web Services.
Download the Web Project attached to this article from the WebRatio Attachments section.
XSD Service Provider
The XSD Service Provider allows the interaction with XML Schema Definition resources. The aim of the XSD Service Provider is to enable the creation of model objects, starting from an XML Schema Definition file. This lightweight file can be easily exchanged among users and guarantees the interoperability between different machines.
To add an XSD Service Provider select the Project View of your Web Project and from the Outline View right click on the Service/Data Providers node and choose the option Add -> XSD Provider.
Each XSD Provider is characterized by its name; a meaningful label recalling the meaning of that Provider (e.g. Stock Quote XSD Provider).
XSD Resource
The XSD Provider is composed by one or more than one XSD Resource.
An XSD Resource is a reference to an XML Schema Definition, available locally or remotely.
XSD Resources can only be added to an XSD Provider node; right click on it and choose the option Add -> XSD Resource.
XSD Resource properties
Each XSD Resource has its own name to be identified.
The “Type” property defines the kind of resource. The possible values are “XML Schema” to identify a standalone XML Schema or “Embedded WSDL Schema” if the XML Schema is embedded within a WSDL document.
The resource must declare its availability, local or remote.
If the resource is declared locally, it is defined into a File. The “File” property allows choosing the file which contains the XML Schema Definition. This file must be placed inside the Web Content/WEB-INF folder of the Web Project.
If the resource is declared remotely, it is defined into a remote File. The “URI” property allows choosing the URI of the remote file.
Synchronization with the Domain Model
XSD Resources as well as XSD Providers can be synchronized in order to easily define Domain Model entities and relationships, starting from an XSD structure, using the Synchronize XSD…” option available in the right click menu.
Synchronizing directly the XSD Provider can be useful if it has more than one XSD Resource defined, since it synchronizes all of them at the same time.
Once you click on the “Synchronize XSD…” option the synchronization dialog appears with the list of elements that will be imported into the model.
The Entity Duration drop-down indicates the duration that will be set on the imported entities. You can choose one of these 4 alternatives: Application Volatile Database or Session Volatile Database, Application Java Beans or Session Java Beans (the entities are saved in Java Beans).
Once you choose the Entity Duration you can use the Import All Objects button (highlighted in red in the previous picture) and then press “Finish” to create the Domain Model.
At the end of the procedure the Domain Model contains as many Entities as defined in the XML Schema Definition file, grouped in packages.
The “Properties view” of Entities and Attributes generated through the “Synchronize XSD…” command has a new tab, called “XSD”, which lets you see the XSD reference.
In case of the entity, the XSD tab shows the XSD Provider and the XSD Type defined in the XML Schema and translated into the entity.
In case of an attribute (except the “oid”), the XSD tab shows the XSD Element declared in the XML Schema within the parent XSD Type.
Synchronization Rules
The synchronization process is based on some rules which define how the XSD is translated into Domain Model elements. The main ones are following explained:
- XSD complex type -> Entity
- XSD simple type -> Attribute with the type inferred from the XSD specifications
- The relationship between two Entities has the default 1 to 1 cardinality (direct and inverse)
- The 1 to N cardinality between two Entities is expressed with maxOccurs="unbounded" XSD attribute, defined on the XSD element that will be translated into an Entity that can have one or more instances.
Translation Examples
XML complex type -> Entity
 |
<xsd:complexType name="ItemType">
<xsd:sequence>
<xsd:element name="ItemDescription" type="xsd:string"/>
<xsd:element name="ItemCode" type="inv:ItemCodeType"/>
<xsd:element name="ItemQuantity" type="inv:ItemQuantityType"/>
<xsd:element name="ItemPrice" type="inv:ItemPriceType"/>
</xsd:sequence>
</xsd:complexType>
|
XML Simple Type -> Attribute
 |
<xsd:complexType name="ItemType">
<xsd:sequence>
<xsd:element name="ItemDescription" type="xsd:string"/>
<xsd:element name="ItemCode" type="inv:ItemCodeType"/>
<xsd:element name="ItemQuantity" type="inv:ItemQuantityType"/>
<xsd:element name="ItemPrice" type="inv:ItemPriceType"/>
</xsd:sequence>
</xsd:complexType>
<xsd:simpleType name="ItemQuantityType">
<xsd:restriction base="xsd:nonNegativeInteger">
<xsd:minExclusive value="0" />
<xsd:maxExclusive value="1000" />
</xsd:restriction>
</xsd:simpleType>
|
maxOccurs="unbounded" -> Relationship with 1:N cardinality
 |
<xsd:complexType name="ItemsType">
<xsd:sequence>
<xsd:element name="Item" type="inv:ItemType" minOccurs="1"
maxOccurs="unbounded"/>
</xsd:sequence>
</xsd:complexType>
|
| |
|
Entity based Forms
The Domain Model Entities which are created starting from an XSD can be easily managed with an entity-based Form Component or an entity-based Multiple Form Component.
In addition, the fields of the Form will be automatically validated according to the XSD Restrictions (for instance <xsd:minExclusive value='1'> means that the entered value should be greater than 1).
XML I/O Unit
Introduction
From WebRatio 7 it's available the XML I/O Operation. The XML I/O is an Operation used to import or export valid XML documents, in terms of well-formed XML documents which also conform to the rules of the XML Schema.
Properties
The main property for this Operation is the “Entity”, since you must declare the Domain Model Entity that you read to export data or that you write to import.
The working mode is set using the “Mode” property. It provides the choice between:
- “Import” (default): the Operation imports an XML document (consistent with an XSD) into the Domain Model. In particular, the XML document is read and the instances are created and associated with the Entity specified on the XML I/O Operation. It works only if the specified Entity is XSD based.
When the Operation works in “Import” mode you have another property available:
- “Delete All Before”: If checked, the Operation, before executing the “Import”, removes all the instances from the chosen Entity
- “Export”: the Operation exports Domain Model elements into an XML document. In particular, the Domain Model Entities (related to an XSD resource) are read and an XML document is created, always in accordance with the XSD.
When the Operation works in “Export” mode you have other two properties available:
- “Root Element”: The root XML element to export.
- “Validate Documents”: If checked, the Operation validates the generated XML documents.
Inputs and Outputs
The Input and the Output of the Unit are accessible respectively through the Parameters Coupling window of incoming and outgoing Links. They change accordingly with the unit mode.
Input
Import
- <Entity Name> XML Document: The XML document to import (e.g. “GetQuoteResponse XML Document”).
- <Entity Key(s) Attribute(s)>: The key(s) of the instance to update (e.g. “oid”).
- <Cardinality><Entity Name>.<Entity Key(s) Attribute(s)>(<Relationship Name>): for each entity having a relationship with the one specified on the XML I/O Operation there is a parameter which represents the oid of an instance. In this case, the XML document contains the data of an instance, that will be connected to one or more than one instances identified by the keys (e.g. “[1:1] Symbol.oid(GetQuoteResponseToSymbol)”).
Export
- <Entity Key(s) Attribute(s)>: The key(s) of the instance to extract (e.g. “oid”).
- <Entity name> Entity Objects: The Entity Objects used to generate the output XML document (e.g. “GetQuoteResponse Entity Objects”).
Output
Import
- <Entity Key(s) Attribute(s)>: The key(s) of the instance created (e.g. “oid”).
Export
- <Entity name> XML Document(s): The created XML document (e.g. “GetQuoteResponse XML Document”)
Common parameters
The XML I/O Operation returns two output values to better handle errors and exceptions: “Error Message” and “Exception”, available in both working modes.
Examples
This section shows the usage of the XML I/O Operation through examples.
All the examples share the same XSD Resource defined in this way:
<?xml version="1.0" encoding="UTF-8" ?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="Product" maxOccurs="unbounded">
<xs:complexType>
<xs:sequence>
<xs:element name="code" type="xs:string"/>
<xs:element name="name" type="xs:string"/>
<xs:element name="description" type="xs:string" minOccurs="0"/>
<xs:element name="quantity" type="xs:positiveInteger"/>
<xs:element name="price" type="xs:decimal"/>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>
This is the related Domain Model:
Example 1: Create an instance from an XML document
In this example, the XML I/O Operation in mode “Import” accepts as input an XML document representing a Product.
The XML I/O Operation creates an instance of its associated Entity ("Product"), mapped with an XSD, considering the data contained in the XML document.
IFML and Action Definition Model:
The IFML Model has the “Import” page with a Form Component having a blob field, used to load the “.xml” file at runtime.
Then the blob file is passed to the Action “Product XML Import” that parses the XML content of the blob file using a Get XML Operation, and passes it to the XML I/O Operation.
The XML I/O works in “Import” mode and imports the XML Document into the Product Entity.
Accordingly with the result of the Action execution, you will see the list of all Products stored or an error message.
Here’s an example of the uploaded XML document:
<?xml version="1.0" encoding="UTF-8"?>
<Product>
<code>K9-1234</code>
<name>Wilderness</name>
<description>Perfect for your living room</description>
<quantity>3</quantity>
<price>150</price>
</Product>
Here’s the generated web page.
Example 2: Update an instance from an XML document
In this example, the XML I/O Operation in mode “import” receives as input parameters both an XML Document representing a Product and the Key of an existing Product. The XML I/O Unit updates the instance identified with the Key, setting the data contained in the XML Document.
IFML and Action Definition Model:
The IFML Model has the “Product Catalogue” page with the List of all the products, clicking on the “Edit” flow a new page is shown with the details of the selected product and a Form Component having a blob field, used to load the “.xml” file at runtime.
Then the blob file is passed together with the Product Key to the Action “Product XML Import & Update” that then parses the XML content of the blob file using a Get XML Operation, passes it to the XML I/O Operation, forwarding also the Product Key.
The XML I/O works in “Import” mode and imports the XML Document into the Product Entity, replacing the content of the Product with the specified Key.
Accordingly with the result of the Action execution, you will see the list of all Products stored or an error message.
Example of uploaded XML document:
<?xml version="1.0" encoding="UTF-8"?>
<Product>
<code>K9-1235</code>
<name>Aladin</name>
<description>Perfect for your bed room</description>
<quantity>5</quantity>
<price>500</price>
</Product>
The XSD structure adopted is the same of Example 1.
Result pages:
Example 3: Create an instance from an XML document and connect the instance
In this example, the XML I/O Operation in mode “import” receives as input parameter both an XML document representing a Product and the Key of an existing Category instance in relatioship with the Product.
The XML I/O Operation creates an instance of the Product Entity and connects it to the Category identified by the provided Key.
The Domain Model requires a change since the Category Entity is missing at the moment.
IFML and Action Definition Model:
The “Import” page contains the “Product XML File” that using a Selection Field preloaded by a Selector, and a blob type Field allows to pick the XML File and the Category to which the Product belongs. Data is then passed to the “Product XML Import & Connect” Action that gets the XML contents of the file and sets the relationship between Category and Product using the Foreign Key target parameter exposed by the XML I/O Operation.
Accordingly with the result of the Action execution, you will see the hierarchy list of all Categories and Products stored or an error message.
Example of uploaded XML document:
<?xml version="1.0" encoding="UTF-8"?>
<Product>
<code>K9-1234</code>
<name>Wilderness</name>
<description>Perfect for your living room</description>
<quantity>3</quantity>
<price>150</price>
</Product>
Result pages:
Example 4: Export an instance into an XML document
In this example, the XML I/O Operation in mode “export” receives as input parameter the Product Key of the instance to export. The XML I/O Operation creates an XML Document, complied with an XSD, which contains the data of the exported instance.
IFML and Action Definition Model:
The “Export” page contains the “Products” List with the “Export” flow that passes the Product Key to Action instance where the XML I/O Operation extracts the contents of the Entities in terms of XML Document. Then a Script Component gets the XML Document and returns its content that is passed to a Message Component and shown inside the page.
The code run by the Script Component is the following:
#input Document product
return product.asXML();
Result page:
