General Interface is an open source project hosted by the Dojo Foundation

Common Exchange Format (CXF)

Common Interface Format (CIF) Chapter 3 General Interface Framework Basics

Common Exchange Format (CXF)

The Common Exchange Format (CXF) is an interface definition schema that describes how to interact with XML data within General Interface. By using CXF, General Interface is able to connect to disparate systems and services without being tied to a specific exchange format. At runtime, CXF is used by the jsx3.net.Service class to perform the actual interactions.

In much the same way that WSDL (an XML document format) defines SOAP transactions, General Interface employs a tree-like definition language of its own referred to as the Common Exchange Format (CXF). Using a common format for defining transactions allows General Interface to communicate with a myriad of systems without being tied to a particular interface definition. CXF documents are created at design time by the XML Mapping Utility using any number of formats as a starting point for creating the definition. Supported formats include WSDL, schema, XML, and XHTML. CXF documents are referred to as mapping rules files or rules files throughout the documentation.

Once parsed by the XML Mapping Utility, XML documents are persisted in CXF format. A CXF rules document can then be mapped to application objects, such as CDF documents, text boxes, and nodes in the Local Data Cache palette.

Regardless of whether WSDL, Schema, or XML is used, all input formats result in the same transactional format. In practice, this means that the interactions with a SOAP service can be defined by using WSDL or a sample SOAP message, such as an Envelope, as a starting point. Ultimately, the source type (WSDL, Schema, or XML) used to create a CXF rules document is irrelevant once the CXF document has been created, as all formats are persisted using CXF.

Another way to think about CXF is to think of it as an interpretive language that is able to interface between the XML document formats used by a given web service and the native CDF and JavaScript formats used by General Interface. Just as it is important to be versed in CDF in order to know how data is used within General Interface, an understanding of CXF provides insight into how data is shared between General Interface and data services. While CDF provides the format for data while it is within the control of General Interface, CXF provides the bridge to convert this information to the format required by the given web service.

CXF Document Example

The following CXF document was created by the XML Mapping Utility. The input document is Google's WSDL located at http://api.google.com/GoogleSearch.wsdl. After the XML Mapping Utility converts Google's WSDL to CXF, a few operations are removed for readability. What remains is a shortened description of the doGoogleSearch operation, with a sampling of the major CXF entities and attributes. If you're familiar with WSDL and Google's in particular, you should see similarities and differences between CXF and WSDL. CXF is more transactional and is designed to read more literally with less indirection. Therefore, it contains only a subset of the data contained in the original WSDL. 

<data jsxid="jsxroot" jsxnamespace="jsx3.xml.Mapper"
  jsxversion="1.0">
 <record jsxid="13" jsxtext="WSDL (/GoogleSearch.wsdl)"
   src="http://api.google.com/GoogleSearch.wsdl" type="W"
   path="">
  <record jsxid="12" jsxtext="Service" path="/" type="S"
    soapstyle="rpc">
   <record jsxid="74321" jsxtext="doGoogleSearch"
     opname="doGoogleSearch" endpoint="beta2" type="P" path="/">
    <headers jsxid="7">
     <record jsxid="3" name="SOAPAction"
       value="urn:GoogleSearchAction"/>
     <record jsxid="4" name="Content-Type" value="text/xml"/>
    </headers>
    <record jsxid="5" jsxtext="Input (request)" type="I"
      stubsrc="soap.xml" stubpath="/" onbeforesend="some code"
      soapuse="encoded" soaprpcns="urn:GoogleSearch"
      soapencstyle="http://schemas.xmlsoap.org/soap/encoding/">
     <record jsxtext="doGoogleSearch" jsxid="41037" type="C"
       tns="urn:GoogleSearch" path="/">
      <record jsxtext="key" jsxid="1" type="E"
        datatype="xsd:string" simple="1" path="/" repeat="false">
       <mappings jsxid="11">
        <record jsxid="10" name="Script" value="setValue(true);"/>
       </mappings>
      </record>
     </record>
    </record>
    <record jsxid="9" jsxtext="Output (response)" type="O"
      soapuse="encoded" soaprpcns="urn:GoogleSearch"
      soapencstyle="http://schemas.xmlsoap.org/soap/encoding/"
      stubsrc="/" onafterreceive="some code">
     <record jsxtext="doGoogleSearchResponse" jsxid="20020"
       type="C" tns="urn:GoogleSearch" path="/message[5]">
      <record jsxid="8" jsxtext="return" type="C" path="/"
        datatype="typens:GoogleSearchResult">
       <record jsxid="5" jsxtext="documentFiltering" type="E"
        path="/" datatype="xsd:boolean" simple="1"
        jsxselected="1">
        <restrictions jsxid="16">
         <record jsxid="14" name="enumeration" value="true"/>
         <record jsxid="15" name="enumeration" value="false"/>
        </restrictions>
       </record>
      </record>
     </record>
    </record>
   </record>

  </record>
 </record>
</data>

CXF Attribute Definitions

CXF is an extension of CDF, meaning it adheres to the CDF format, while adding additional attributes and entities of its own. For more information on CDF, see Common Data Format (CDF).

The following table provides attribute definitions. Each of these attributes exists in one or more rule types, which are described in CXF Rule Types.

Attribute Description
datatype Data type for the node. For example, xsd:string. This is relevant to RPC Encoded WSDL inputs. When the final message is generated and sent to the remote service, this value is used to specify the encoding for a node in the message.
endpoint URL for the remote service to contact. Although WSDL binds the endpoint to the service (which can encapsulate one or more operations), CXF binds the endpoint to each individual operation.
groupref If equal to 1, the node is flagged as structural, which means that it isn't part of the generated message. The node appears in the rules tree as an organizing element but isn't generated and sent with the request, essentially removing the abstract node and appending its descendant structures to the structural node's immediate parent.
jsxid System ID for the record. This is assigned by the system and is unique for each node in the CXF document. This attribute is only relevant at design time.
jsxtext System text for the record. More importantly, this is the node name (for attributes and entities) in the message.
method The HTTP transport method: GET, POST, PUT, DELETE.
name Applies to records in the CXF that define mappings, HTTP headers, and restrictions. In the case of mappings, this is the map type (i.e., DOM, Script, CDF Document, and so on). For HTTP headers, this is the header name. For restrictions, this is the type of the restriction (enumeration, nillable, pattern, and so on).
onafterreceive JavaScript code to execute immediately after receiving the response message.
onbeforesend JavaScript code to execute immediately before sending the request message.
opname The name of the operation. This value is unique among all other operation nodes in the CXF document. In the case of a CXF that was created without a WSDL, there is only one operation for the CXF named jsxtransaction.
path The node path to find this item in the original source Schema used to create the CXF. This attribute is only used by WSDL and Schema input types and is only relevant at design time.
ref If equal to 1, this node will be flagged by the XML Mapping Utility as a referential node, pointing to a group or attributeGroupelement in the source WSDL/Schema. This attribute is only relevant at design time and is used to convert the indirection used by Schema to the concrete structures used by CXF.
repeat If this attribute exists, its value will be evaluated as JavaScript within the context of the jsx3.net.Service instance that is processing the given CXF. If the result evaluates to true, the given branch in the CXF will be processed again. This only applies to XML documents generated on the client. This value is ignored when processing a service response.
simple If equal to 1, the data type for this node is one of the simple types defined by Schema (http://www.w3.org/2001/XMLSchema-instance).
soapencstyle If equal to http://schemas.xmlsoap.org/soap/encoding/, the operation is designated as encoded, meaning each node will be tagged with its data type. This applies only to WSDL input types that use RPC encoding.
soaprpcns If an RPC Encoded message, the namespace for the remote procedure (the message).
soapstyle The SOAP style — document or rpc.
soapuse The SOAP use — encoded or literal.
src URL for the source document that is serving as the pattern master for generating the CXF. The pattern master is the input document that was used by the XML Mapping Utility to create the CXF (typically a WSDL). This attribute is only relevant at design time.
stubsrc URL for the base shell document. Also used for inbound messages (response nodes) when running in static mode.
stubpath The XSL Query for the node in the base shell document (stubsrc) to which the generated document will be appended.
tns If this value exists on a Rule node contained by an Input node, the Rule will be qualified and the value of the tnswill be appended to the root node in the response document. If it exists on a rule contained by the output or fault nodes, it defines a qualified namespace, meaning that it isn't enough for the node names to match for the rule to be applied; rather, the node's namespace must also match.
ttns Represents the target namespace for the data type and applies to rpc-encoded messages. For example, if the target namespace tns is abc.com and ttns is def.com, you would see something similar to the following in a message: 
<jsx1:myNode xsi:type="jsx2:myType" xmlns:jsx1="abc"
  xmlns:jsx2="def"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" />
type The type of rule. For example, A, C, E, and so on. The most common type is E, which represents a mapping rule to an Entity node type in the CXF.
value Applies to records in the CXF that define mappings, HTTP headers, and restrictions. In the case of mappings, this is the map path/value. For HTTP headers, this is the header value. For restrictions, this is the value of the restriction.

CXF Rule Types

Each node in the CXF document is known as a rule, each of which describes a specific step in the transaction. For example, an operation rule defines the location of the Service, while a Mapping rule defines what values will be sent to the Service. The following table describes each rule and the CXF attributes it implements.

CXF Rule Type Attribute Description
WSDL //record[@type='W'] jsxid, jsxtext, type, src, type This is the top-level node in a CXF document that resulted from a WSDL input. The most relevant attribute is src, which describes the location of the original WSDL in case the CXF document is in-edit and still needs a back-reference to the original WSDL.
Service //record[@type='S'] jsxid, jsxtext, type, path, soapstyle This is a second-level node in a CXF document that resulted from a WSDL input. It is an immediate child of the WSDL-type node. It describes a service to which one or more operations belong. Although the service does define an endpoint in the original WSDL, this information is saved to the Operation nodes for improved flexibility.
Operation //record[@type='O'] jsxid, jsxtext, type, endpoint, method, opname, path This is a third-level node in a CXF document that resulted from a WSDL input. It is an immediate child of the Service node. The operation describes the type of messages involved, including input, output, and fault.
Transaction //record[@type='T'] jsxid, jsxtext, type, endpoint, method, opname This is the top-level node in a CXF that resulted from a non-WSDL input. It is equivalent to the third-level Operation node that results from a WSDL input, except that it does not define a path. Instead, its child input and output rules define the path to their respective source documents.
Input //record[@type='I'] jsxid, jsxtext, type, onbeforesend, path, soapencstyle, soaprpcns, soapuse, src, stubpath, stubsrc This node is the child of either an Operation or Transaction node. It contains the rules necessary to create the input (the document that will be sent as part of the request). When the immediate parent is a Transaction node, the input will define a src attribute, if relevant.
Output //record[@type='O'] jsxid, jsxtext, type, onafterreceive, path, soapencstyle, soaprpcns, soapuse, src, stubsrc This node is the child of either an Operation or Transaction node. It contains the rules necessary to create the output (the response that will be processed). When the immediate parent is a Transaction node, the output will define a src attribute, if relevant.
Fault //record[@type='F'] jsxid, jsxtext, type, path, soapencstyle, soaprpcns, soapuse This node is a child of an Operation node. It defines an alternative ruleset for processing a fault document returned from the Service. It is executed only when the service responds with a non-202, 200, or -0 HTTP status code. It does not support the extra attributes that the Output node supports.
Rule //record[@type='A' or @type='C' or @type='D' or @type='E'] jsxid, jsxtext, type, datatype, groupref, path, ref, repeat, simple,tns,ttns Rule nodes define the mappings and restrictions and are used to either generate a node in the input message or process a node in the output. Note the following definitions: A: attribute node E: entity node D: CDATA node C: complex node (contains E, C, D, or A nodes)
Mapping //mappings/record jsxid, name, value Mapping nodes are bound to an entity called mappings, which, in turn, is bound to a given Rule node. There can be zero or more mappings for a given rule.
Restriction //restrictions/record jsxid, name, value Restriction nodes are bound to an entity called restrictions, which, in turn, is bound to a given Rule node. There can be zero or more restrictions for a given rule. The restrictions can be used to validate mapped input.
Header //headers/record jsxid, name, value Header nodes are bound to an entity called headers, which, in turn, is bound to a given Operation or Transaction node. There can be zero or more HTTP headers for a given operation.

Common Interface Format (CIF) Chapter 3 General Interface Framework Basics

Contents

Searching General Interface Docs

Expand all   Collapse all
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.