Creating Mapping Rules Files

Mapping rules files are XML files authored in Common Exchange Format (CXF). CXF defines how data is exchanged between objects, as well as how data is converted from one XML format to another. CXF can be viewed as a visual form of XSLT with additional support for HTTP-based communication to transport the XML. In fact, a rules file can be compiled into XSLT for faster performance. For information about CXF, see Common Exchange Format (CXF).

Mapping rules are individual rules within the mapping rules file. There are many types of mapping rules, each of which defines a particular aspect of the mapping process. For example, rules that descend from the output rule define how to process (read) a document in the local cache or returned from a remote service, while mapping rules that descend from an input rule define how to create (write) a node in an XML document.

Rules files created in an earlier version of General Interface are automatically updated to the latest CXF version when opened in the XML Mapping Utility.

The first step in mapping GUI components or CDF documents to a mapping rule is to create a mapping rules file.

The XML Mapping Utility accepts many types of source document formats to begin defining the mapping rules file, including WSDL, XML, XSD, XHTML, JSON, and well-formed HTML. Data in any of these formats can be parsed and used as a starting point for defining mappings. When the mapping rule will be used to not only read and write XML, but also communicate with a remote service, the HTTP methods, PUT, GET, POST, and DELETE are supported.

This section uses the General Interface WSDL Mapping 2 sample located in workspace/JSXAPPS/samples/WSDL_Mapping_2. By default, this sample runs in Static Mode, rendering the results of a sample message on screen. To run against the Xignite web service in Live Mode, register for a license key at http://www.xignite.com/xhistorical.asmx?op=xRegister. Then set the project to Live Mode on the Deployment panel of the Project Settings dialog (Project > Project Settings > Deployment) and reload your browser.

Choosing the File for the Rules File Starting Point

The files you can use as the starting point for generating the mapping rules file in the XML Mapping Utility are WSDL Files; XML, XHTML, and Schema Files; and JSON Files.

WSDL Files

Select WSDL if your source document is a WSDL that defines a Doc Literal or RPC Encoded SOAP service. Specify the location of the WSDL file in the URL field. See Specifying Paths in the XML Mapping Utility.

XML, XHTML, and Schema Files

Select XML/XHTML/Schema if your source document is a data format other than WSDL or JSON.

Specify the location of source document(s) in the URL fields. See Specifying Paths in the XML Mapping Utility.

JSON Files

Select JSON if your source document is in JavaScript Object Notation data interchange format. Specify the location of the source document in the URL field. See Specifying Paths in the XML Mapping Utility.

Specifying Paths in the XML Mapping Utility

The XML Mapping Utility resolves paths to files relative to the project. It's recommended that you copy WSDLs and other source document(s) for rules files to a directory in your project. For example, create a wsdl folder in your project and copy the WSDL into the wsdl folder. Then enter wsdl/ wsdl_file.xml in the URL field of the XML Mapping Utility.

If you need to resolve a path to a source document outside of your project, use an absolute resolver, such as jsxuser:/// and jsxapp:///.

• jsxuser:///... Resolves relative to the parent of the JSXAPPS directory, which is the workspace. When General Interface Builder is running, this URI resolves relative to the workspace directory.

• jsxapp://app/... If the Server instance corresponding to the host portion of the URI is loaded into memory, the URI is resolved relative to the application base directory (jsxappbase).

Creating a Rules File

To create a new rules file:

1. Copy the file(s) to be used as the starting point for the mapping rules file to your project---a WSDL file, XML/HTML/Schema files, or a JSON file. This example uses Historicals.wsdl in workspace/JSXAPPS/samples/WSDL_Mapping_2/wsdl.
2. Open the XML Mapping Utility using one of these methods:
   
   • Select File > New > Mapping Rule.
     
   • Choose Tools > XML Mapping Utility.
3. Select the file type you are using as the starting point for the mapping rules file: WSDL, XML/XHTML/Schema, or JSON. See Choosing the File for the Rules File Starting Point.
4. Enter a URL and parse the document:
   
   1. Type the URL for a source document(s) to be used as the starting point for the rules file or click the Browse button to locate the file. See Specifying Paths in the XML Mapping Utility.
      For example, if the Historicals.wsdl is saved in a wsdl folder in your current project, type wsdl/Historicals.wsdl as the starting point for the rules file.
      
      
      
   2. Click the Parse Document button to generate the mapping rules file.
      After you click Parse Document, a new rules file is created. The XML Mapping Utility looks similar to the following:
      
      
5. Modify the mapping rules file as desired. For example, remove any extraneous rules as follows:
   
   1. Select a rule or rules in the rules tree. Use Shift+click or Ctrl+click to select multiple rules.
      
   2. Choose Delete > Delete Selected Rules to delete the rules you've selected. Or choose Delete > Unselected Sibling Rules to delete the unselected rules.
      For example, select GetHistoricalQuotes (not the singular GetHistoricalQuote) in the Rules Tree panel and choose Delete > Unselected Sibling Rules from the Rules Tree panel menu to remove the other operation rules that were defined by the source WSDL. This helps to reduce the size of your mapping rules file so that it only defines those operations that will be run.
      For more information, see Modifying Mapping Rules Files.
      
6. Save the rules file with the .xml extension.