Composer User's Guide
CHAPTER 6
In many ways, the Composer XML Map Component is the simplest yet most important of Composer's component types. You will use it to perform XML transformations of input documents to output documents. It is essential that you understand how XML Map Components (and related resources) work if you are to build useful Composer services.
This chapter introduces you to XML Map Components and describes how they work within an exteNd Composer service. After reading this chapter, you will understand what comprises an XML Map component, what it can do, and how to design, create, and use an XML Map component.
An XML Map component is an object that accepts one or more XML documents as inputs, uses a collection of actions to operate on these inputs and returns an XML document as output.
An XML Map component can perform simple data manipulation, such as mapping and transferring data from one XML document to another. It can also carry out sophisticated manipulations, such as transforming both the data and structure of a document. You can even create XML Map components that process XSL, send mail, and post and receive XML documents using the HTTP protocol.
The concept behind a component is to pass one or more XML documents in as inputs, process these inputs, and return one output XML document. The output XML document is then used as input for other components or returned as the final output of a service. In this way, you can create components that work together in a service to carry out complete business-to-business solutions.
The XML documents you use when building an XML Map component are samples of the actual documents that will be processed in a running application. Sample documents are added to Composer in XML template objects. You use samples of documents whose structure and data representation are identical to the documents that will be processed. The illustration below shows the difference between documents you use for building purposes and those that are actually processed by the component.
The samples used to build a component are not actually used, or even referred to by name, at runtime. They are simply templates that represent the structure and data to be manipulated. The samples are temporary aids that help you construct processing actions that perform the correct runtime manipulations. What exteNd actually uses at runtime to process XML data is an object representation of the XML document called a DOM.
In the XML Map component editor, a sample document is represented in a format recommended by the W3C known as the document object model (DOM). A DOM is an XML document constructed as an object in a software program's memory. It provides standard methods for manipulating the object. Using DOMs, Composer lets you build XML documents, navigate within their structure, and add, modify or delete elements and content. Anything found within an XML document can be manipulated using a DOM method. Composer supports all DOM methods recommended by the W3C ECMA to DOM Binding Specification (See http://www.w3.org/).
NOTE: In some dialogs, Composer refers to DOMs as Messages.
When the XML Map component editor is active, every sample document is converted to a DOM.
DOMs are used because:
A DOM uses a standard way of naming and organizing XML structural elements so that the elements can be selected easily and clearly
A DOM is the structure that is created and manipulated at runtime
A DOM is organized hierarchically, which means it forms a tree structure. To understand how a particular DOM is structured, it's often useful to be able to view the DOM from different perspectives. For example, sometimes it's helpful to see the raw text of the XML document underlying the DOM. Other times, you may be interested in seeing a summary view of the data (rather than the element and attribute names) in a document. Composer allows you to change views as necessary in order to switch between tree, text, and summary presentations.
To change views, simply right-click inside any DOM window, then select the view you want to see from the View submenu. The three available view types are shown below.
Elements in a DOM are defined by tags in an XML document. For instance, in the above example, there is an element tag in the XML document named <INVENTORYSTATUS>. The tag has an end tag (</INVENTORYSTATUS). All structural elements within <INVENTORYSTATUS> and </INVENTORYSTATUS>, such as <SKU>, are represented at a lower (or in DOM terminology, descendant) level in the DOM tree.
All element names are case-sensitive, meaning that <INVOICENO> is not the same as <InvoiceNo>.
An element in a DOM tree is referred to as a node. A collection of nodes is represented in a hierarchy and is referred to by the following naming conventions:
Each element type in a DOM has its own icon, as identified below.
It is through DOMs that components pass and return data to one another in a running application. At runtime, when a component is executed, it is passed a DOM. The passed DOM becomes the Input Part to be operated on. As each of the component's mapping actions executes, the Output Part is created, element by element.
The first time you open a component, the original samples are loaded into the Input and Ouput DOMs. When you begin animation, the Input Part remains and the Temp and Ouput DOMs are cleared from any data originally contained in them. At the end of execution, data appears in all DOMs.
When you create an XML Map component, you select input and output XML templates for it. However, within the Component Editor you can also:
Create an Output Part without using a template, as described in Creating an Output Document without Using a Template
Create a Temporary Message Part, as described in Creating a Temporary Message Part
Create a Fault Message Part, as described in "Creating a Fault Message Part" on page 119
Dynamically create a DOM from an external XML document using the XML Interchange action.
The first step in creating an XML Map component is to specify the XML templates for the component. For more information, see Creating an XML Template.
Once you've specified the XML templates, you can create your component, using the template's sample documents to represent the inputs and output processed by your component.
NOTE: Various other component types (such as the JDBC Component, JMS Component, etc.) are covered in detail in the appropriate Enterprise Connect product user guides. The same basic principles are used in the creation and editing of all components, however. Also, the various Basic Actions (see next chapter) available in the XML Map Component are also available in all other Composer component types.
To create an XML Map component:
From the Composer File menu, select New then xObject. Select the Component tab and then XML Map. The New xObject dialog box appears.
Specify the Input and Output templates (also called Messages).
Type in a name for the template under Part if you wish the name to appear in the Component Editor as something other than "Input" or "Output."
Select a Template Category if it is different than the default category.
Select a Template Name from the list of XML templates in the selected Template Category.
To add additional input XML templates, click Add and repeat steps 2 through 4.
To remove an input XML template, select an entry and click Delete.
Select an XML template as an output using the same methods described in the previous step.
NOTE: You can specify an output XML template that contains no structure by selecting {ANY} as the Output template. For more information, see Creating an Output Document without Using a Template.
Click Next to go the Temp an d Fault XML template dialog. If desired, specify a template to be used as a scratchpad under the "Temp Message" pane of the dialog window. This can be useful if you need a place to hold values that will only be used temporarily during the execution of your component or are for reference only. Under the "Fault Message" pane, select an XML template to be used to pass back to clients when a fault condition occurs.
As above, to add additional XML templates, click Add and choose a Part Name, a Template Category and Template Name for each. Repeat as many times as desired. To remove an input XML template, select an entry and click Delete. Temp and Fault Message Parts are discussed in more detail below, beginning on page 118.
Click Next. For several of the component types, the Connection Info panel will appear, allowing you to select a previously created Connection Resource.
Click Finish. The component is created and the XML Map Component Editor appears.
You should be aware that when a new XML Map Component is created whose Output template uses namespaces, a new Map action will automatically be placed into the action list, mapping the namespace URI to an attribute in the Output Part. It's important not only that you not delete this Map action, but that you avoid accidentally overwriting it. An overwrite can happen if you place a Component action downstream of the namespace-URI Map action, and the Component action returns its results to the Output Part. The solution in this case is to move (by Cut and Paste) the original Map action to a spot downstream of the Component action.
The XML Map Component Editor is where you specify the mapping, transformation, and transfer of all input and output structure and data.
The XML Map Component Editor provides a logical working environment for the inputs, output, and actions of your component. The XML Map component editor is composed of multiple Mapping panes and a single Action Model pane. The Mapping panes display the XML for your sample Input and Output message parts. The Action Model pane displays actions that operate on the Mapping panes.
The following illustration shows the XML Map Component Editor with its menu and toolbar, one input Part, one output Part, and several actions in the Action Model pane.
The main menu in Composer and it's sub-menus and toolbar options change according to the type of component you currently have open in the Component Editor. The following component-specific options occur on the main menubar when an XML Map Component is open.
|
XMLMap Component Menu |
Options |
|---|---|
|
File |
You can create, open and delete any type of component from the File menu, just as you can from the Composer File menu. Some menu choices have implications that are particularly significant for XML Map Components: Save saves the inputs, output and actions in the component Save As... saves the component under a new name and allows you to change the inputs, output, and actions. See Saving Your Component. Save All... saves all components currently open Save XML As . . . allows you to save the structure of the message Part into an XML document. See Saving a DOM as an XML Document. Load XML Sample . . . allows you to load other sample documents from a template into a message part for testing the component. See Loading a Sample Document. Properties lets you view the component's templates and other information. See Viewing Component Properties. Print lets you print your component |
|
Edit |
You can undo or redo an action, cut, copy, and paste text anywhere in the component editor. In addition, you can do the following: Find finds an element in a mapping pane or text in the Action Model. See Finding a Document Element. Find Next finds the next element in a mapping pane or text in the Action Model. See Finding the Next Document Element. Replace replaces selected text in the Action Model only. See Replacing Text in the Action Model. |
|
View |
Navigator Tabs toggles the visibility of the nav frame at the left of the Composer main window. Use this command to hide or unhide the whole nav frame. Output Tabs toggles the visibility of the Message frame at the bottom of the Composer main window. Use this command to hide or unhide the whole Message frame. Document Tabs toggles the visibility of the XML Document Tabs in the Component Editor. XML Documents brings up a submenu with the following choices:
Window Layout allows you to specify which DOMs to display and how to arrange the DOM and Action Model panes within the component window. See Using Window Layout and Show/Hide in the Component Editor. |
|
Component |
Execute—Runs the component from start to finish, for testing purposes. Reload XML Documents reloads the original samples from the Input and Output templates, clearing whatever is currently shown in the XML message panes. See Reloading an XML Document. Add Watch allows you to identify certain data items and examine their data values during the execution of a component as a debugging aid. |
|
Action |
New Action contains all actions that you can add to the Action Model. Edit allows you to edit a selected action Disable allows you to disable a selected action |
|
Animate |
This menu contains all processing animation tools that you can use to test the component. The Toolbar contains buttons that allow you to run animation tools. For more information, see Testing and Debugging. |
Many of the menu items are on the toolbar. Rest your mouse on a toolbar item for a brief description of it.
The panes of the component editor can be displayed, hidden, repositioned and resized, making it easier for you to work with their contents. Use the Window Layout option and the Show/Hide option from the View Menu.
To arrange the panes of the component editor:
Select Window Layout from the View menu. The Window Layout dialog appears and allows you to adjust the placement of the panels in the Window.
Select the orientation of the XML documents and Action Model as follows:
If you want the panes to be top-to-bottom, select either XML Document or Action Model from the upper-most pull-down menu. If you selected XML Document for the upper pane, select Action Model from the lower-most pull-down menu. If you selected Action Model for the upper pane, select XML Document for the lower.
If you want the panes to be left-to-right, select either XML Document or Action Model from the left-most pull-down menu. If you selected XML Document for the left pane, select Action Model from the right-most pull-down menu. If you selected Action Model for the left pane, select XML Document for the right.
If you're not satisfied with the result, select View then Window Layout, and then click the Reset button. The panes revert to the default setting.
To set the visibilities of XML documents:
Select View/XML Documents>Show/Hide . The Show/Hide dialog displays the visibility status of XML documents.
NOTE: The Input and Output XML documents default to the Show column. DOMs created as a result of a component action default to Hide.
Select any XML documents you want to be displayed from the Hide column and click the left-triangle button. Conversely, select any XML Documents that you don't want to display from the Show column and click the right-triangle button.
Select the XML document you want to display as the top document and click the up-triangle button until the document is displayed at the level you want in the Show column.
NOTE: If you selected a left-to-right orientation in the preceding procedure ("To arrange the panes of the component editor:", above), the order of your XML documents appears from left-to-right: Higher-precedence documents will appear on the left.
Continue to select XML documents in the Show column and use the up and down buttons as necessary until the XML documents are in the desired order.
Click OK. The Window Layout dialog closes and the Component editor is rearranged accordingly.
Individual XML document panels can be maximized, normalized or closed using icons located within the header area of the document panel:
Clicking the Maximize icon will cause the document to take over the entire XML Panel area, temporarily hiding any other open message Parts. Once a document has been maximized, the icon will change to the Normalize icon, so you can restore the document to its previous size.
Clicking the Close icon will hide the document from view. Closing all XML documents leaves the XML Panel open but empty. To re-open a document when the editor panel is in this state, click with the RMB. A context menu is displayed, from which you can select a document to open.
The default XML Map component editor has the following window pane configuration:
One or more Input Mapping panes (each displaying a representation of the XML for one of the samples in their respective XML Template), one Output Mapping pane
Temporary message part mapping panes, or XML returned as a result of executing another component via a component action
Note that there is a color coding aspect of the mapping pane. Red indicates the first direct mapping of an element, so that if you wanted to look at what elements in the output tree have been mapped, you can identify that by the color red. Green indicates the first occurrence of the element that has a repeat alias defined for it.
NOTE: You must use Window Layout discussed above to display a dynamically created message part, such as mapping panes created dynamically by the XML Interchange action.
The Input Mapping pane displays one sample document from the input XML template as a document object in the Component Editor. (If your component contains multiple templates, each input message is displayed in its own pane.) The panes can be sized by dragging borders up, down, left, or right.
If your component contains multiple input XML templates, they are displayed with the following names:
The template display order is determined by the order you specified when selecting XML templates at the time of the component creation. You can change this order using the up and down arrows using View>XML Documents>Show/Hide, as indicated above.
Each input pane consists of two areas: the DOM tree and the Data values. The following illustration shows an Input Part with several elements and data for those elements.
Notice that when you select an XML element, the element name appears in the status bar showing the fully qualified element name. Any data associated with the element (from the XML document) appears in the Data area. Although the data is not used when the component processes at runtime, the data is helpful for setting up and testing the component. You can leave the data in the DOM elements, or you can change the data. For more information on changing the data, see Editing a Value for a Document Element (Edit Data command).
The Input Mapping pane has a context menu you can access to perform tasks on the Input Parts. To access the context menu, click the right-mouse button anywhere in the pane. The context menu is shown below.
You can create a Repeat for Element, Declare Alias, or Declare Group action on an element that repeats in the Input Part. See The Declare Alias Action.
You can also create a group of DOM elements which aids in transforming DOM elements into a structure that is different from their original positions in the sample document. When you create a group, you can perform aggregate operations against a group. For instance, you can arrange DOM elements into a group by U.S. state (e.g., Alabama, Arizona) then sum the total sales by each state.
Groups always work in conjunction with a Repeat for Group action. For more information about creating and using groups, see The Repeat for Group Action.
You can select an element in an Input Part and set the value for it. This is helpful when you run the animation tools to test the component.
NOTE: The value is temporary for the editing session.
To edit a value for a Document element:
Notice that the document element you selected appears in the dialog box. Type in the value you wish to set for the element.
Click OK. The value appears in the Data area, next to the element you selected.
Use this context menu option to add additional XML documents to the display area of the XML Panel. When you select Add to Display from the menu, a list appears containing the currently unopened documents associated with the component, as well as the PROJECT variable and _SystemFault. Select from this list to open any of these items.
You can view individual XML Message Parts as a Tree, as Text, or in stylized form (using an XSL stylesheet).
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 structure of the XML.
In Text View, you can see and edit the complete XML file, including structural elements.
Display the Message Part as text by clicking on the right mouse button (anywhere in the XML panel) and selecting View, then As Text. The XML then appears in plain-text form, as shown here.
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.
NOTE: The Text view, like the Tree view, is updated dynamically during animation so you can see the results of individual Map actions as they are executed.
When the Stylized view is selected (by clicking with the RMB and selecting View>As Stylized), you get a view of the XML message contents that 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.
NOTE: The default XSL stylesheet that Composer relies on for creation of this view can be found inside the xcd-all.jar file in your \bin directory; its name is default.xsl. You can edit or replace this file by extracting (unzipping) it from the jar file and reinserting an editing version in the same place in the jar.
Another View function is Show Comments which allows you to toggle the visibility of comments in the source XML file. Comments, signified by markers <!-- and --> wrapping a section of content, constitute DOM nodes, but you may not always want to view them, particularly if you have a lengthy document.
You can display all elements in a document tree by clicking the right-mouse button and selecting View>Expand Tree.
Another way to expand the tree is by clicking on the plus icon just to the left of the Part name (e.g., the word Input) at the top left-hand corner of the pane .
You can hide all elements in a document tree by clicking the right-mouse button and selecting View>Collapse Tree.
Another way to collapse the tree is by clicking on the minus icon just to the left of Part name (e.g., the word Input) at the top left-hand corner of the pane.
You can reset a specific XML Message by bringing up the context menu and selecting View>Reload Tree. This allows you to reload an individual document tree within the XML Map component. You may wish to reload a tree if during testing, you halted animation, leaving the document in an unfinished state.
Selecting Launch Editor from the context menu opens your document in the default XML editor you specified during installation.
The Load XML Sample function available in the context menu allows you to load other sample documents from a template into a message part for testing the component. See Loading a Sample Document.
Selecting Save XML As from the context menu allows you to save the structure of the currently open Message Part into an XML document. See Saving a DOM as an XML Document.
You can search for element names and element data using the Find command (which appears in the XML Panel context menu). The Find dialog allows you to enter a value and search the document tree. You can search for partial words or whole words only, and you can ignore the text case when searching. The Find Text dialog box is shown below.
You can search for the next occurrence of a word or string you searched for previously. There is no dialog box when you select Find Next or press the F3 key. Instead, Composer locates the next occurrence of the last find. If no match is found, nothing happens.
You can validate the DOM against its DTD or schema definition file by picking Validate from the context menu. Validating is useful during the construction and testing of your component.
The Output Mapping pane displays the Output Part. The Output Mapping pane also has a context menu, as shown.
The options on the Output Mapping pane context menu are similar to the ones on the input mapping pane context menu, but with the differences described below.
You can use the Map action by selecting it from the right-mouse context menu.
The Edit Data option on the Output Part allows you to inspect the value of a node but not change it.
All components have a single Action Model. The Action Model represents the mappings, transformations, and other actions that will be performed on XML documents during runtime processing. The Action Model Pane is also resizable within the XML Map Component Editor window. Most of your activity that takes place in the Action Model pane involves adding and editing actions.
If you right-click in the Action Model, you see the menu shown below.
From this menu, you can select actions and perform other tasks.
You can replace a word or string using the Replace option on the right mouse menu or on the component editor Edit menu.
Right click in the Action Model and select Replace (or select an action and select Replace from the Edit menu).
Composer finds the first occurrence and asks you to confirm the replacement. You can then replace the next or all occurrences.
Once you have specified the Input and Output templates, the XML Map Editor opens, and you are ready to start adding actions. Actions are the processing steps that take place within the component. You will read more about actions in later topics.
Within components, you add actions to map DOM elements, read and write data from files, send e-mails, and other common tasks. A collection of actions is referred to as an Action Model.
An action in the Action Model is displayed as a line and contains an icon for the action type along with an abbreviated definition of the action. Some actions are subordinate to other actions. For instance, you can create a Repeat action that controls loop processing, then add actions inside the loop. The actions inside the loop are subordinate to the Repeat action and appear indented beneath it. They process as long as the Repeat action is true.
To add actions to the Action Model:
Position the cursor in the Action Model pane above where you want the next action inserted.
Add an action using any of following methods. The new action is inserted below the line you highlighted.
Drag and drop. You can add Map actions by dragging and dropping elements from an Input Part to the output or temp DOMs. Simply click on an element in the Input Part and drag it on top of the output or temp DOM.
Copy and Paste. You can copy an action in the Action Model pane and paste it somewhere else in the pane, or into an Action Model pane of another component.
The Action menu. Highlight a line in the Action Model pane and select an action from the Action menu. The new action is placed directly under the highlighted line.
The Action Model pane context menu. Click the right-mouse button anywhere in the Action Model pane and its context menu appears.
The input and output mapping pane context menus. You can add actions to the Action Model pane by selecting DOM tree elements and then selecting actions from their respective context menus.
NOTE: You can reorder actions in the Action Model by dragging them to a new position.
Once you've created the Action Model, and before you process the component with live data, you should test the component. Perform testing by using Composer's Animation tools. With the Animation tools, you can set breakpoints, start a animation, step into and over actions, and pause the animation.
You can specify an output XML template that contains no structure by selecting {SYSTEM}{ANY} as the Output template when you create the component. You can then build the Output Message Part dynamically by mapping input Part elements to output Part elements that do not yet exist.
For example, the following illustration shows a component with an input Part containing elements, and an output Part that has no elements.
Notice there is nothing in the output document. To dynamically build an output document, you can map input Part elements to a structure in the output Part that does not exist. In the next illustration, the Seller in the input Part is mapped to a line item called Buyer in the output Part.
The next illustration shows the resulting XML Document Panels.
You can create any output document structure by mapping an input document element to an output XPath. Make sure you map to a fully-qualified document name.
NOTE: In reality, Output and Temp Message Parts are always built dynamically. The presence of a sample document is merely a productivity aid to help you define actions.
If the Output Part you created can be used for building other components, you may want to save it as an XML document and use it as a sample inside an XML Template. See Saving a DOM as an XML Document for more information.
In addition to creating Input and Output Message Parts, you can also create Temporary and Fault Message Parts. Temp Parts are used as work areas for performing complex manipulations of between Input and Output Parts. Within a Temp document pane, you can add elements from any of the Input Parts by using any of the five mapping methods. See About the Action Model Pane.
Fault Documents allow you to pass information back to clients when a fault condition occurs in a component or service. In Composer, a Fault is, essentially, an in-memory XML document or Message Part, defined along with a component, just like Input, Output and Temp Parts. Fault Message Parts are used to store information received when a Fault or Error occurs in your service or component. It is a good programming practice to anticipate places in your program where errors may occur and surround them with Try/On Fault and Throw Fault actions. (See "The Throw Fault Action" on page 169 for an example demonstrating the use Fault documents in fault-related actions.)
The Temp Part differs from the Input and Output Parts in the directionality of actions allowed. The Temp Part can be both a source and a target of mapping actions, whereas the Input Parts are only sources and the Output Part is only a target. You can add more than one temporary Part (you are only limited by memory), and you can delete them whenever you wish. Also, you can assign your own name to temporary Parts by typing over the Temp label. Temporary Message Parts can either be defined during the creation of a component (see "To create an XML Map component:" on page 103), or they can be added to an existing component.
To add a temporary Message Part to an existing component:
From the File menu, choose Properties. The Properties dialog appears.
Click the Add button at the far right. Selections for Part, Template Category and Template Name become available.
Enter an Part (your own label) for the temporary message part.
Select an XML Category from the Template Category dropdown menu.
Select an XML Template from the Template Name dropdown menu.
Open the component. By default, the Component Editor will probably only show the Input and Output parts. To make the Temp document visible, go to the View menu and select Show/Hide to add the Temp Part you just created.
NOTE: Alternatively, you can click with the RMB in the Component Editor and select Add to Display, then pick the Temp document from the list.
The XML Map Component Editor displays a Temp message pane, as shown in the next illustration.
NOTE: You can also create a document object dynamically without using a template, as described in Creating an Output Document without Using a Template.
You can define the XML yourself for your Fault document, using your favorite editor, or you can use the default one provided by Composer, which is called _SystemFault. The XML information contained in _SystemFault also gets written to a global object called ERROR. The structure of the _SystemFault document is shown below:
Beneath the FaultInfo root are the following elements:
DateTime which contains the Date and Time the fault occurred.
ComponentName which contains the name of the Component which threw the fault.
Message which contains the error message you specifically define when you set up a Throw Fault action (p.169). If you do not specify an error message in your Throw Fault action, you will see "A user defined Fault occurred!". If the error occurred within a Try/On Fault action, and you did not specify a Fault, this element will be populated with an Exception message.
NOTE: By default, the Fault document will not be visible in the Component Editor. To View it, click with your RMB, select Add to Display and choose _SystemFault.
The procedure for adding Fault Message Parts to your component is very similar to the procedure for adding Input, Output and Temp Parts. You begin by using your favorite editor to create an XML document that will be used to hold fault information. You can create as many Fault Message Parts as you need (you are limited only by memory) and Fault documents can have any structure that makes sense to your application.
You might want to use a custom Fault Part along with the _SystemFault document. For example, you could use the DateTime, Component and Message elements from _SystemFault to populate your own Fault document which woul also contain information about the service itself, a log message indicating the last action that was sucessfully executed and some information from the Input document that might have been missed due to the application halting before completion. Below is an example depicting a custom Fault message.
Once you've decided what Faults you need to capture and created the XML structures to support them, the Parts can either be defined during the creation of a component, or added to an existing component.
To add a Fault Part to an existing component:
From the File menu, choose Properties. The Properties dialog appears.
Click the Add button at the far right. Selections for Part, Template Category and Template Name become available.
NOTE: If you do not specify a Fault Part, error information will go into the basic fault document, called _SystemFault.
Select an XML Category from the Template Category dropdown menu.
Select an XML Template from the Template Name dropdown menu.
Open the component. By default, the Component Editor will probably only show the Input and Output parts. To make the Fault Part visible, go to the View menu and select Show/Hide to add the Fault Part you just created.
NOTE: Alternatively, you can click with the RMB in the Component Editor and select Add to Display, then pick the Fault document from the list.
If you have made changes to the document structures through mapping, and wish to return the Message Parts to their original state, you can reload the XML documents. When you reload the XML documents, all Parts, including Temp and Fault (if these were created) are returned to the state defined by the input and output XML documents. Keep in mind, however, the Map actions in the Action Model pane remain.Thus, if you were to execute the component, all Map actions will run.
The illustration below shows a component that contains several Map actions that are reflected in the Input, Output, and Temp Parts.
Notice the detail in the XML and the Map actions in the Action Model pane. The next illustration shows the same screen after the XML documents have been reloaded.
The documents are back to their original state but the Action Model pane remains the same. Reloading XML documents is accomplished by selecting Reload XML Documents from the Component menu.
You can load different sample documents into any of the DOMs and use the new DOM structures for mapping elements or testing the Action Model. Loading a different sample document from your template allows you to test if your Action Model can handle all cases of XML documents your component might receive at runtime.
When you load an XML sample, the DOM changes, but the Action Model remains unchanged. When you are finished testing with the sample XML document, you can reload the original XML document(s) by repeating the Load XML Sample procedure.
From the File menu, select Load XML Sample. Alternatively, click with the RMB in the XML Editor Panel and select Load XML Sample from the context menu. The Load XML File dialog appears.
Select appropriate message Part from the Part dropdown box where you want the new sample document loaded.
If you want to load a sample document that is not included in the original XML template, click File Name and type the name of the file. Alternatively, you can click Browse and find the file on your computer or network. You may also read in a file from a URL by explicitly preceding your filename with "http://," "https://" or "ftp."
If you want to load an XML file that is included in the original XML template, click Sample and select the XML document.
Check Default if you want to make the selected sample the default XML document for the selected Part in this component only. (This does not apply to the file name option).
During the execution of your component, it can be very useful to examine the value of certain variables as a debugging aid. For this purpose, Composer offers a Watch List, and the ability to create Watch variables to add to the list.
You can identify the following objects as Watch variables:
To add an item to the Watch Variable List
The Add Watch Dialog displays, giving you access to all the Variables, ECMAScript Functions and Methods and Operators associated with your project.
Doubleclick on the item you wish to add to the Watch list and click OK.
During the execution of your component, click on the Watch tab in the Output pane to view the status of the items in your Watch List.
The use of a Watch List, including examples of how this could be used as a debugging aid, are discussed in greater detail in Chapter 12.
Save your component often to make sure your work is not lost due to hardware or software failures. You can also save the component with a different name, making a backup copy. When you save it with another name, you can also change the XML properties, including the input and output XML templates.
To save the component with a new name:
NOTE: If you have more than one component open at a time, clicking on File>Save All (or pressing Ctrl-Shift-A) will save all the open components at once. Similarly, File>Close All (Ctrl-Shift-F4) will save all components at once.
You can also save any DOM as an XML document. This creates (or overwrites) an XML document that contains the structure and data of the DOM. The following illustration shows an Output Part and the resulting XML document.
To save an in-memory DOM to an XML file:
From the File menu, select Save XML As. The Save XML As dialog box appears.
Use the pulldown menu under Part to select the source DOM that you want to save to disk. In the above example, Output is selected.
Type a path and name for the XML document, or click Browse and select a path.
NOTE: If you select an existing XML document, it will be overwritten with the source DOM's structure and data.
Any DOM that's visible in the component editor can be saved as an XML Template directly (rather than first saving the DOM to a file, then importing it into a template). The target Template does not have to exist already; you can create one on-the-fly.
To save a DOM to an XML Template:
From the File menu, select Save XML As. The Save XML As dialog box appears (as shown above).
Use the pulldown menu under XML Document to select the source DOM that you want to save as a template.
If you are creating a template on-the-fly, enter a name for the Category (or else pick an existing category from the pulldown menu provided).
If you are creating a template on-the-fly, enter a name under Template Name (or else pick an existing XML Template name from the pulldown menu).
Enter a Sample Name for this XML document. (This will be the name of the file on disk. The file will be saved under \xmlcategories\[CategoryName]\imports in your project directory.)
Click OK. You will see the new XML Template appear in the Instance Pane of Composer's nav frame.
During on-the-fly creation of an XML Template using the above technique, you will not be prompted for any additional information (such as schema name or XSL stylesheet) to associate with the new template. If you want to inspect or edit the validation, stylesheet, or other properties of the new template, follow the procedure outlined below.
At any after an XML Template has been created, you can inspect or change its properties. See"Editing an XML Template" on page 94.
When you are working with large DOMs, it is advised that at design time, to avoid memory errors, you add the following line to the xconfig.xml file. See the sample xconfig file excerpt below.
Line to add (or edit): <VM_PARAMS>-Xms64m-Xmx128m</VM_PARAMS>
To adjust available memory for deployed services (in the runtime environment), you will have to alter the VM command-line options for the app server's VM. Consult your app server documentation for information on how to do this.
You can avoid many out-of-memory problems (at runtime as well as design time) by appropriate use of Performance Filters as described in the next section.
The Define Performance Filter command (under the Component menu on Composer's main menubar) offers the potential for greatly improved performance when processing large incoming documents. It also offers significant benefits in terms of memory conservation, since a filtered document can require much less memory at runtime than an unfiltered document.
Performance filters work by stripping superfluous document elements (and attributes) from incoming XML documents. You specify which elements to ignore; Composer does the rest. In essence, the input document is "rewritten" on the fly in much-streamlined form, eliminating parts of the XML that are not necessary for your service. This results in a smaller in-memory DOM.
Document filtering is useful because it is very common for a service to operate on only a few XPath locations in a given type of document. For example, one service might operate on the "Customer Info" nodes in an order form; a different service might operate on the "Product Request Detail" nodes of the same order form; and so on. It makes sense for each service to see and use only the portions of the document that apply to that service.
To create a Performance Filter
Open a Service xObject, if one is not already open.
NOTE: Performance filters cannot be defined on Components. They can be defined on Service xObjects only.
Under the Component menu on Composer's main menubar, select Define Performance Filter. A dialog appears.
Note that the document shown in tree-view form in this dialog is the Input document for the service. (It is not possible to view other documents in this dialog.)
Check the checkbox(es) next to the nodes you want to keep in the document. Unchecked nodes will be stripped off (discarded) so that the parsed DOM does not contain the elements in question. (See additional discussion below.)
In the preceding illustration, the incoming document, with root node DoctorResp, will have a /physician node with a /patients node under it at runtime, and the /patients element, in turn, will have a PatientData element under it. Likewise, the latter will have child nodes LastName and FirstName. But since Physician is not checked, the incoming document will not have anything under the XPath:
DoctorResp/physician/patients/PatientData/Physician
NOTE: At design time, you will initially, upon opening a service, see the complete (non-filtered) Input document, with all its nodes present in tree view, even if you have defined a Performance Filter. But when you begin stepping through the action model in animation mode, the document tree view will update to show the reduced (filtered) runtime structure of the document.
You can inspect (and in some cases edit) various properties of a component at any time.
To view or change component properties:
Select Properties from Composer's File menu. The Properties Dialog will appear. Note that the dialog has three tabs:
Header Info—This is the descriptive commentary you entered (or didn't enter) when you first created the component.
Messages—This is equivalent to the second dialog in the New XML Map Component wizard: It shows the templates and template categories used in this component.
Connections—This tab will be present only in components that are associated with a particular Connection Resource. (For example, a JDBC Component would have such a tab in its Properties.) The plain XML Map Component does not have this information, and this tab does not appear.
To view or edit descriptive commentary for this component, click the Headers tab and enter the desired information.
To view or change XML template choices, click the Messages tab. You can add or remove template documents and/or template categories as need be.
If your component uses special Connection Resources, click the Connections tab to view Connection Resource info for this component. (Not applicable to ordinary XML Map components.)
You can print the contents of a component. The printout contains:
The following table shows how sample documents are used when designing, testing, and running a component.
Copyright © 2004 Novell, Inc. All rights reserved. Copyright © 1997, 1998, 1999, 2000, 2001, 2002, 2003 SilverStream Software, LLC. All rights reserved. more ...
