|
|
W3C schemas are rapidly becoming the normal way to describe the structure of XML documents.
The tool provides functionality to create a Plex XML import file based on a W3C schema.
After the creating the Plex import file, it can be imported into Plex to create the necessary definitions.
Run the SchemaImportGUI.exe file to import a W3C schema file. This launches the panel:
Specify the location of the file containing the W3C schema in the input field "XML schema file".
You can specify either a file location or a URL specifying the location of the file on a web server.
Specify the location of the file where you want to save the generated Plex import document. Note that Plex expects this file to have the extension .xml.
If you leave the "Create Limits All triples" checkbox checked, each field created by the schema import will have a FLD limits all triple.
No limits triples are be assigned to the field if the checkbox is unchecked.
When you press the "Generate" button, the tool reads and validates the schema and generates the Plex import file.
Errors before import
If you have not specified a value for the location of either the schema file or the Plex import file an error is shown.
An error will also occur if the specified schema file does not contain a valid W3C schema. You can get additional information about the error by pressing "Details" on the panel.
More than one potential top element
A W3C schema can contain more than one potential top element - in other words, it can describe several potential XML documents.
To create the simplest possible XML model in Plex, we have chosen to create one document at the time.
If there are several possible top elements described by the schema, the tool shows a list of these top elements.
Select the top element you want to import by double clicking on the name of the top element in the grid. This starts the creation of the import file.
Potential top elements are the globally defined elements.
These are the <element> tags scoped directly under the <schema> tag.
One top element
The import starts immediately if the schema only specifies one potential top element.
No top elements
It is possible to create a schema that does not contain any potential top elements.
If you specify a schema without any potential top elements, the tool shows the following message:
"No top element was selected - the import file has not been finalized".
This dialog message is shown:
In some cases, the import tool has some information about the import that the user should be aware of, even though the import has been successful. If this is the case, the tool launches the following panel that contains all the informational messages.
In version 2.02 and later, you can save the informational messages to a file by pressing the "Save to file button. When pressing the button, a dialog box is shown, describing where the file has been saved.
The most common cases for the information message are:
Renaming of an element/attribute
In some cases, the import tool has had to rename a field or entity. When this is the case, a LongName source code contains the "real" name. The names selected by the import tool will all be of the format WSY_LongNamen (n=integer).
TransacXML handles this automatically so you do not need to change anything. However, you might want to change the name of the entity/field in the Plex model to a more understandable name. To do so, perform the import into the Plex model, and then use the Plex editors to change the name.
An element is defined as a child of a parent element more than once
In some cases, the same element has been declared more than once as a child of a parent element. In these cases, the import tool only creates the first parent ENT includes ENT or parent ENT has FLD triple.
You might have to change the order of the "has" triples for the parent element after performing the Plex import to model the schema correctly.
Recursive structures
W3C XML Schemas can describe recursive structures. When such structures occur, the tool only creates the top element, as Plex can't handle the recursive structures (an entity includes itself).
SOAP-encoded arrays
When the schema import has been launched as part of the WSDL import, the definitions might contain declarations of SOAP-encoded arrays. As these arrays are not part of the standard W3C schema definitions, the tool only creates the array element itself and a default encoded element field as a child of the array.
Information about special cases in the import.
If an error has occurred, the tool shows error in a dialog message. By pressing "Details" on the panel showing the error message, you can obtain detailed information about the error.
The import tool translates a number of structures, described in the W3C schema, to Plex objects.
You might want to create your own abstract objects for one or more of these structures.
Pressing the "Settings" button opens a grid showing the Plex objects for which you can specify a different inheritance.
The objects you specify must be available in the Plex local model that you import the definitions into - either as locally defined objects or as objects belonging to a library model of the local model.
You specify an alternative Plex object by specifying the group model and the scoped object name of the Plex object in the grid.
If the object belongs to the local model, you are going to import the schema into; the group model field must be blank.
Pressing the "Restore Default" button restores the original system settings from the Plex objects.
Pressing the "Save Settings" button saves the current content of the grid to a file. When the schema import tool is launched, it uses this file to define the abstract objects to use.
This is useful in cases where you always want to specify your own inheritance for the Plex objects.
Please note that if you have saved the content of the settings grid using the "Save Settings" button, the saved settings will be used to generate the Plex import file even if you have not opened the Inheritance grid.
Use the Plex import tool to import the definitions into Plex.
The Plex version must support XML import (Plex 5.1 and later).
The Plex local model must have WSYXML and WSYDOM as library models.
For version 2.00 and later of the import tool, you must use Websydian version 6.1 or later as some of the abstract objects (EncodedElement, EncodedField, and ComplexValue) was not available in earlier versions of Websydian.
Open the Plex local model that you want to import the definitions into.
Run the import from the menu item Tools→Import→XML Import.
You can read more about using the Plex import in the Plex help.
The top element of the generated XML document will be created as an unscoped entity having the name of the top element specified in the schema. All other objects created in the model will be scoped under this entity.
Depending on the choices made for the Plex import, existing objects might be overwritten. If you already have an entity having the name of the top element in the schema, you should move or rename this entity so that it will not be changed during the import.
From version 2.02, you can specify that all the Plex definitions should be scoped under an entity when the definitions are imported in the Plex model.
This can be done by specifying the name of the entity in an element named "scopingentity" in the settings.xml file.
Note that this only supports one level (you can't scoped your imported XMLElement entities under a scoped entity) and that the import of the definitions into the Plex model will fail if the specified entity doesn't exist.
This section explains the most common warning and error messages that can occur when performing the import.
Warning: Referenced object '...' not found in XML but exists in model
This is not an error. You can disregard it.
Error: Reference to object '...' found but object was not imported
This error means that the import file specifies that an object should refer to another object. This object is not specified in the import file - and it does not already exist in the model you are importing into.
There can be two different reasons for this error:
1. The local model that you are importing into does not have the WSYXML group model as a library model.
2. You have specified an object in the inheritance grid that does not exist in the local model you are importing into.
Error: Triple '..' was not imported because '...' was not imported
This error is related to the previous one, it simply states that a triple could not be created as the parent object was not imported.
The Plex object names have certain limitations that do not correspond to the naming allowed by the XML standard. The two most common cases are:
Plex objects that according to the schema should have a name that is not a valid Plex name will inherit from WSYXML/LongName.
The literal value of the scoped LongName source code contains the name that will be used on the XML documents.
The tool auto generates a Plex name for the object (WSY_LongName followed by a number).
If the top element has an invalid Plex name, it will get the name WSY_LongName1. If this is the case, you should rename the top element at once as any other schema having an invalid Plex name will also have this name assigned.
In version 2.02, two new ways of assigning long names to the plex objects has been introduced.
These can be activated by entering a special element named longnamethod in the settings.xml file (in your installation folder).
<longnamemethod>hash</longnamemethod>
Insert this line to make the import tool assign a name that is calculated as a hash of the original name
<longnamemethod>hashkey</longnamemethod>
Insert this line to make the import tool assign a name that is calculated as a hash of the original name, object type, and namespace.
The idea with both of these are that you should be able to reimport new versions of the schema. If the longname is assigned as the next integer, you can't be certain that the name of a field will be the same on imports of changed schemas. By creating a hash of the name (or type, name, namespace), it is certain that if the name is unchanged, the name in the Plex model will be the same.
The downside of doing this is that all longname fields get to be very long (WSY_LongName followed by a 20 character hash) - this is not very userfriendly - so this naming scheme probably should not be used unless you have a way to convert the names in the Plex model to something more useable (e.g. using the Plex model APIs).
If the longnamethod value is neither hash or hashkey or if the element isn't present, the number based names will be assigned.
To make sure that the inheritance of namespaces performed by TransacXML are resolved correctly, all XMLElement entities and all ElementFields inherit from NamespaceAware. Only the elements actually belonging to a namespace will have a literal specified for the namespace source code.
This will typically occur when there is a <choice> construct in the schema where the same child element occurs in more than one of the optional groups.
For instance:
In this case, the element "top" has two different sequences as possible children, in this case either the A followed by ID or B followed by ID.
This will lead to the creation of the following fields and triples:
Top.Fields.A, Top.Fields.B, Top.Fields.ID.
Top ENT has FLD Top.Fields.A
Top.ENT has FLD Top.Fields.ID
Top.ENT has FLD Top.Fields.B
However, in this case this means that the InsertRow function will inset the ID field before the B field, if you select to insert values for B and ID. This is not correct according to schema. To model the schema correctly, you will have to change the sequence of the triples manually to:
Top ENT has FLD Top.Fields.A
Top.ENT has FLD Top.Fields.B
Top.ENT has FLD Top.Fields.ID
In general, you will have to look into the sequence of the "has" triples specifying the sequence of the child elements in the cases where the tool reports that a child element occurs more than once.
The tool uses .Net's SOM (Schema Object Model) implementation to access the W3C schema data.
It seems that this implementation demands a very strict adherence to the W3C schema standard. This means that event though other tools (e.g. XMLSpy) accept certain schemas; the .Net framework might return an error.
This also means that only schemas belonging to the namespace http://www.w3.org/2001/XMLSchema are accepted.
The W3C standard allows recursive structures in the described XML documents.
TransacXML can't fully model TransacXML recursive structures.
Where the tool is able to identify that it is a recursive structure, it only creates the first level of the recursive structure.
There might be some cases where a recursive structure is not identified correctly by the tool. To ensure that the tool does not end in an endless loop, the tool will stop processing if the next element to create is scoped under more than 50 layers of elements.
All fields are just defined as character strings. The tool imports no field types, values etc.
Online documentation - Websydian v6.5