Composer User's Guide
CHAPTER 5
Novell exteNd Composer relies heavily on the concept of organizing related groups of XML, XSL, DTD, and/or XSD files into named templates.
In order to simplify working with XML data at design time, Composer lets you defined XML Templates. The purpose of the XML Template is simply to organize related documents into a single functional grouping. For example, it's not unusual, when designing an XML integration application, to have one or more sample input documents that represent hypothetical "incoming data." These input documents might or might not conform to a particular schema (.xsd) or DTD. They might or might not be associated with XSL stylesheets. You may or may not also want to associate various kinds of fault documents with the service. In Composer, you would typically organize input documents into one XML Template and create a different XML Template (with any or all of the above-mentioned ancillary items) to hold sample output documents. The "XML Template" wrapper identifies a group of related documents: sample XML docs that go with particular stylesheets, schema docs, and/or DTD files, and/or fault docs that need to be used in association with each other.
At design time, the XML sample documents in your templates serve as exemplars, or "hints," to enable Composer to display proper document tree views in the various GUI pieces that need to show your service's inputs and outputs. In this way, it becomes possible for Composer to translate simple UI gestures (like drag-and-drop) into XPath and ECMAScript expressions that can be used to carry out mappings and transformations at runtime. (Composer does the "hard work" of generating XPath and DOM methods so that you don't have to.)
A sample XML document is nothing more than a representative model of the data your component or service will process: it contains the same elements, attributes, and structures. For example, if your application will process Company ABC's invoices, you might use a sample invoice when building the application. The sample (if it's truly representative) will have exactly the same XML structure as the invoices that will be processed.
One of the most important parts of planning and designing an XML integration application is determining all of the possible kinds of sample documents your components might need before you begin development.
The types of sample documents you may need are:
Sample input documents. These could include XML documents provided by a standards organization (e.g., cXML, OAG, and OFX) containing the elements and structure for the particular kind of data you want to process.
XSD (schema) or DTD documents. (These can be stored in a project as separate resources; they are merely referenced in XML Templates.)
An important concept to note is that sample documents used in designing a component are not used on the server at runtime. The samples in an XML Template are really only design-time hints. They cannot be used as sources of instance data. (For that, you'd probably want to use XML Resource documents. See "About XML Resources" in the chapter on Resources.)
NOTE: If you need to initialize any data elements with hard-coded values, you can do it programmatically in the action model, by mapping an ECMAScript string or number to XPath locations, as needed. You can also load an XML Resource and create mappings from it to (say) an input document using drag-and-drop gestures.
The sample document is a design aid that allows you to visualize the data manipulations that need to happen at runtime. At animation time (during testing or debugging) you can watch element data in the sample change locations or values, or show up in output, etc., in real time, in response to XML Map actions, ECMAScript operations, and so on. After watching the data change in real time during step-through/step-over debugging, it's easy to forget that the data values are just design-time valuesplaceholders, if you will. At runtime, Composer merely executes the map actions, XPath and ECMAScript operations, etc. that you specified in development.
Document Type Definition and XML Schema Definition files (DTDs and XSDs, respectively) can be used to define and validate XML documents. Schemas and DTDs define the grammatical rules of the document, such as which elements must be present and what the structural relationships are between the elements.
Recall that a schema differs from a DTD in several ways, including:
The XSD file is a true XML file which itself conforms to a schema defined by W3C. DTDs, by contrast, are not true XML files.
A schema can enforce data typing, so that if an element requires (for example) data that takes the form of a date in CCYY-DD-MM format, such a requirement can be specified (and strictly enforced).
A schema allows namespace declarations, so that elements can be uniquely identified as belonging to a given document vocabulary.
Schemas are designed to be granular, providing for maximum reusability.
Schemas are flexible in terms of allowing an author to specify strict enforcement of some grammar rules but lazy enforcement of other rules, within the same document.
Schemas are extensible in that they allow authors to define all-new custom data types.
For these and other reasons, schemas (XSD files) are gradually displacing DTD files for definition and validation of XML documents.
Schema and DTD validation are enforced by Composer only at design time. At runtime, no validations (other than a well-formedness check) are performed on incoming or outgoing data. Nevertheless, you can force runtime validation to occur by means of ECMAScript (used either in a Function action, or wherever ECMAScript is permitted in Composer). For example, suppose you want your service to validate the Input document. You would execute this expression:
result = Input.validate(); if (result == true) // do something else // throw fault
If a schema is associated with Input in the XML Template for Input, that schema will be used for validation when the above code executes. If no schema is referenced anywhere, the validate()
function simply performs a well-formedness check and returns a boolean result.
NOTE: The validate() function will not use DTDs.
As part of the set of files you use in a component, you can include an XSL stylesheet. An XSL stylesheet defines the display properties of an XML document. You create or obtain the stylesheet external to Composer. The stylesheet may be useful for a component of your application that is creating a page to be displayed in Web browser.
An XML Template is created in Composer. As explained earlier, it contains the sample documents, document definitions, and XML stylesheets that comprise a set of files that can be used in components. You'll create XML Templates early in the component design phase, then use them to specify the inputs and outputs of the components you build.
XML Templates exist primarily so that you can use and test many types of sample data. It is possible to have two XML documents with different structures that both have to be handled without error by the same component. For example, if you are using an industry standard purchase order document as input, but one of your customers uses a slightly different version of that document in his business (e.g., it has some optional elements missing), you can load your customer's document into a component for testing purposes. Your component must be able to handle the different document versions, and you can test several cases by collecting all your samples into a template that serves as an input for a component.
Instances of XML Templates are collected into Template Categories. The Template Categories have user-assignable names and appear as folders in the XML Template Category pane of Composer's navigation frame. The members of a given category appear in the Instance pane under the Category pane. See below.
Your application can have many input and output documents, so you will want to organize them within XML Template Categories. Within an XML Template Category, you can organize templates in a way that makes sense for your application. For example, you can create folders for:
Specific business processes (e.g., Accepting a Purchase Order, Sending an Invoice, Receiving an Invoice)
Here is an example of what your organizational scheme might look like.
The purpose of the folders is to store your XML Templates, which might contain sample XML documents, schema, and XSL stylesheets.
To create an XML Template Category:
An XML Template resides within an XML Template Category. XML Templates are simply groupings of related files; and the groupings are designed to be reusable. (One template can be used by more than one component.) For example, you can use a template as input for one component and as output for another component. Several XML files can be associated with your template and used for different purposes.
NOTE: XML output from one component is often used as input for the next component in a service.
Your template might, for example, contain four XML files: one to be used as Input, one as a Temp document (a sort of scratchpad to hold values that will change throughout the course of your component), one as Output, and one as a Fault document, which can hold values to be used in the case of an error condition occurring. For more information on Temp and Fault Documents, refer to "Using Temp and Fault Messages with a Component" on page 131.
Click the right-mouse button on the category, and select New. The Create a New XML Template Wizard appears.
From the pulldown menu under Category, select from among the existing XML Template Categories that you have already created. (See "To create an XML Template Category:" above.)
Under Description, enter a plain-text description of the intended usage of the template. (Optional.)
Click Next. The document-selection panel of the wizard appears.
Click the blue `+' icon; a file navigation dialog will appear. Use the dialog to specify an XML file on disk that you wish to add to this template. Repeat this step as necessary to add however many XML files you want. You can add files to be used as Temp and Fault documents at this time, in addition to Input and Output Parts. (Click the minus-sign icon to remove a given file from the list.)
NOTE: If you do not specify existing files to be used as your XML samples, an empty default file will be created. You will be able to give this file a name following the last step of the wizard.
Under Default Samples, below Input, use the pulldown menu to select the file you want to see as the default Input Message for any components that use this template. (The pulldown menu will be populated with the names of the files shown in the list you built in the preceding step.)
Below Output, use the pulldown menu to select the file you want to see as the default Output Message for any components that use this template. (The pulldown menu is populated with the names of the files shown in the list on the left.)
Click Next. The document validation panel of the wizard appears.
To indicate the type of document validation you want to impose on your template documents, click one of the three radio buttons: None, Enforce DTD, or Enforce Schema. The appearance of the dialog will change depending on which button is active. Note that Composer will attempt, based on inspection of the XML template document(s) you specified in the previous dialog, to set the correct radio button for you. You can override Composer's choice at any time. The radio buttons have the following consequences:
NoneChoose this option if your application does not require validation of XML documents or if you would like to override the DTD or XSD information specified in your template documents.
Enforce DTDDocuments will be validated against the DTD whose name and/or URI are specified in the text fields shown.
NOTE: If the DTD will be determined dynamically at runtime, you can supply the URI as an ECMAScript expression. If you plan to use a PUBLIC DTD/Schema after deploying the project, you must fill in the PUBLIC Name of DTD field.
Enforce SchemaDocuments will be validated against the XSD or WSDL file indicated. (See illustration below.)
NOTE: Composer will automatically search your sample documents to discover all of the namespaces (if any) declared inside them and the .xsd files to which they point. The namespaces and their associated schemas are displayed automatically in the above dialog; in most cases, you will not have to fill in the dialog yourself. If any namespaces are not displayed next to the correct Schema Resource, select the appropriate Schema Resource from the pulldown menu on the right. (That is, use the pulldown menu to associate the correct schema with the correct namespace.)
If the documents you are using contain namespace information, the namespaces and corresponding prefixes will be summarized in this dialog. If you need to add additional namespace declarations (perhaps for documents that do not reference schemas), use the plus sign (+) icon to do so.
Click Next. The stylesheet selection pane of the wizard appears.
(Optional) Specify an XSL StyleSheet to associate with any Service Output that is defined by this XML Template. An XSL Processing Instruction pointing to this stylesheet will be added to the Service Output. If you have previously created an XSL Resource (see "About XSL Resources" on page 326), select this option and select the stylesheet from the dropdown list. Use Other Associated Stylesheet to specify the URL for any XSL file that exist outside the project. (In this case, the file name should be closed in quotation marks, since it will be treated as an ECMAScript string.)
If you specified an XSL stylesheet, the following occurs:
When you create a new service or component, and the template is used for the Output Message, Composer will automatically add a Function action to the new component's Action Model. The Function action adds a processing instruction to the Output XML document, specifying the XSL stylesheet for the document.
The stylesheet referenced in the processing instruction is the one you specified in this XML Template.
NOTE: If you did not use the + sign to add pre-existing files to your template because you wished to create an empty one, at this point, the following dialog window will appear, allowing you to type in a name for your default sample:
When an external WSDL is downloaded into exteNd Composer, you generally need to have XML templates corresponding to message parts in the WSDL in order to create working components. XML samples must be created which can be validated against the WSDL. (These templates can then be used in components to create actions then used in the WS interchange.) Composer can help with this. If you have a WSDL Resource for a service, simply open the WSDL Resource: Composer's toolbar and menus will change as shown below, and you will be able to create XML stub documents (template docs) at the click of a button.
There are two ways to generate XML Template docs from an open WSDL Resource:
NOTE: The samples created will not contain element data. You may need to populate various elements with sample data for test purposes. Note also that when elements refer to ##any or ##other namespaces, the samples are incomplete and you have to manually complete them.
Template documents can be create in this fashion for document-style as well as RPC bindings.
To create XML Templates from WSDL:
From the main menu, click on Resources>Create XML Templates, or click on the button on the toolbar. A dialog will appear.
Select a Service/Port or Binding from the dropdown list as a source for creating the XML Template.
Select an Operation from the dropdown list as a source for creating the XML Template.
The bottom portion of the dialog box is divided into Input, Output and Fault Messages. Follow the same procedure for each Part:
If you've already created an XML Template for another project, you can import it into the current project.
In Composer's Category Pane, select the XML Template Category to which you want to associate the template instance.
Right-click and select Import from the context menu. A dialog appears.
NOTE: If the Import command is not highlighted, it's because you have chosen a Template Category that belongs to a subproject. This operation is not allowed. If you need to import template docs into a subproject, close the current project. Open the subproject on its own, add templates to it, save it, and close it; then return to the project you were working on originally.
Select the File Name location using Browse. You may also read in a file from a URL by explicitly preceding your filename with "http://," "https://" or "ftp."
It can be convenient to toggle the visibility of XML document views when working in Composer's main window.
To toggle XML document visibility:
From Composer's main menubar, choose: View>XML Documents>Show/Hide.
The Show/Hide dialog displays the names of the XML documents associated with the open template or component.
NOTE: In a component, the Input and Output XML documents default to the Show column. Message parts created as a result of a component action default to hidden.
In the Hide column, select any XML documents you want to be displayed and click the left arrow button. Conversely, in the Show column, select any XML documents you want to be hidden and click the right arrow button.
Select the XML document you want to display as the top document and click the up arrow button until the document is displayed as the uppermost document in the Show column. Conversely, use the down arrow to move the document down further in the list.
Continue to select XML documents in the Show column and use the up- and down-triangle buttons to move the XML documents into the desired order until they are displayed the way you like.
Click OK. The dialog closes and the Component editor's data panes are rearranged accordingly.
The XML Template Editor allows you to edit the template in Composer, rather than using an external editor.
The View option from the main menubar allows you to select the way you want the XML information displayed in the Component Editor. You can choose from tree, text or stylized. Each view has its own unique context menu accessed by the RMB.
The default view displays the message part as a tree, as shown below.
This view allows you to edit element and attribute values (that is, document data) but not the XML structure.
The Context menu commands accessible via the right mouse button are shown below.
In Text View, you can see and edit the complete XML file, including structural elements.
Text view offers a convenient way to inspect non-content-model portions of the Input, Temp or Output Parts, such as comments, processing instructions, DOCTYPE declarations, and so forth.
The Context menu options accessed by RMB as shown below.
When the Stylized view is selected pane, your view of the message part contents looks like this:
This view gives a "report" style overview of the XML contents so that you can see at a glance what the content is for all attributes and elements. This view uses the following algorithm to render XML.
If there is an associated stylesheet with this document component, evaluate the expression and use that one.
If this fails, use the default stylesheet: com/sssw/b2b/dt/default.xsl
To change to a stylized view, click the RMB to access the Context menu as shown below.
Each XML Template you create resides in an XML Template category. To view the name and creation date of the XML Template, select an XML Template category. All XML Templates for the category are listed in the Detail pane of Composer. Each template has a context menu, giving you ways to work with the template.
Each XML Template contains one or more sample documents. You can open a sample document in an XML editor (a separate application external to Composer).
To view a sample document in your XML editor:
Select Edit Sample and select the sample document you wish to edit. Whatever XML editor you identified during your Composer installation will open (by default, Internet Explorer is used).
You can modify the XML Template by adding and deleting sample documents, schema, and XSL stylesheets.
Doubleclick the XML Template instance to open it in the Content Editor. Once a sample file is open, right-click the mouse button to display a contextual menu which gives you several options (see "The XML Template Editor Context Menu" below) including Edit Data.
Single-click the XML Template in the Instance Pane, then click the right-mouse button and select Properties from the context menu.
NOTE: Changing the name of the template on the Properties page causes a Save As operation, preserving the original and creating a duplicate with a new name. To change just the name of an XML Template, use the Rename option on the context menu.
Once you have made changes to your XML using the methods described above, you will, of course, want to save them. There are four ways to save sample XML documents i n Composer.
Select File>Save As from the main menubar. This brings up a tabbed dialog window resembling the Properties screen shown above, allowing you to type over the current name of the document with a new name.
Select File>Save All to save changes to all the XML documents you currently have open in the Content Editor.
Within the Content Editor, right-click on an open document and select Save XML As from the context menu (see "The XML Template Editor Context Menu" below). This brings up the Save XML As Dialog window shown below:
To use the Save XML As dialog:
Select a "Part", or XML document name from the drop-down list.
If you want to save the open document as a sample, then choose Save as Template Sample.
If you want to save the open document as a file, then choose Save as File.
To print the XML document, Select File>Print from the main menubar. The document component is formatted according to the template.
When you open an XML sample file in the Content Editor and right-click on it, a menu appears allowing you to perform several functions.
These functions are explained in the table below:
Edit Data |
Allows you to edit element and attribute values (that is, document data) |
Create Schema |
Brings up a dialog allowing you to create a new schema resource |
Add Sample File |
Brings up a dialog with a file directory so you can select a pre-existing XML file to add to the template |
Create Sample File |
Brings up a dialog which allows you to type in a name for a new sample XML file. |
Add to Display |
Allows you to display additional XML files which are part of the current template but are not currently open in the editor pane |
View |
Change the view of the document (see "Viewing an XML Document" above) |
Launch Editor |
Opens the default XML editor you specified during installation |
Save XML As |
Opens the Save As dialog window, which allows you to specify a part name, save the file as a sample or save as a file |
Validate |
Runs a validation routine to check that your XML is sound |
Find |
Opens the Find dialog allowing you to search for strings in the XML data or structure |
Find Next |
Repeats previous search |
When you create an XML Template, Composer makes copies of the original XML, document definition and XSL files and places them into an "Imports" directory under the proper XML category. When you delete an XML Template, you are going to delete the copies, not the original files. To delete an XML Template, highlight it in the Detail Pane of the Navigator, right-mouse click it, and select Delete. The file must be closed in order to delete it.
To move an XML Template from one category to another:
In the Category pane of Composer, click on another XML category.
In the Details pane, click the right mouse button and select Paste.
NOTE: Be sure to rename a template using the above procedure. If you change the name of the template on its Properties page, it causes a Save As operation, preserving the original and creating a duplicate with a new name.
XML Templates are stored as part of a project. For information on where project files are stored, see Understanding Where Project Files are Stored.
NOTE: Copies of the samples, definitions and XML stylesheets used in the template are stored in a folder. The original documents are not modified.
Copyright © 2003 Novell, Inc. All rights reserved. Copyright © 1997, 1998, 1999, 2000, 2001, 2002, 2003 SilverStream Software, LLC. All rights reserved. more ...