Page History

...

Usage Scenarios

Let's look at a sample simple scenario. The business function is to retrieve report all the orders accounts for a given customer. The data exchanged between the client and server side will be Customer (s) and Order(s)and AccountReport. Let's assume that the business objects are modeled using XML schema and the client side will talk to the server side over Web Service using Axis2. The client program decides to use SDO to represent the business data while the server side prefers to use JAXB.

Image Added

In this case, there are three data formats involved: SDO, JAXB and AXIOM (The AXIS2 XML Infoset) .

Data transformation between SCA components

• Data transformation can be performed on wire for mappable and remotable interfaces
• Data transformation can happen between interfaces defined using different IDLs such as Java or WSDL.

Image Removed

Data transformation for composite services

• <interface.xxx> defines the outbound service contract (SC2) which can be wired to a target component, reference or service (SC3).
• <binding.xxx> can optionally hint a service contract for the inbound data from the binding protocol layer. Image Removed

Data transformation for composite references

• <interface.xxx> defines the inbound service contract (SC2) which can be wired from a source component, reference or service (SC1).
• <binding.xxx> can optionally hint a service contract (SC3) for the outbound data to the binding protocol layer.

Image Removed

Data transformation for property values

• Property values are loaded from SCDLs as DOM documents
• The DOM Document can be transformed into a java object under a databinding, such as SDO, JAXB so that the component implementation code can work with the databinding directly instead of DOM.

Image Removed

What's a databinding?

A databinding represents a specific data format in the Tuscany runtime. Each databinding has a unique name which identifies the data format.

Typical databindings

• XML/Java databinding frameworks
  • SDO
  • JAXB
  • XMLBeans
  • Castor
  • AXIOM
  • FastInfoset
• XML Parsing Technologies
  • SAX (InputSource, ContentHandler)
  • DOM (Node)
  • StAX (XMLStreamReader/XMLStreamWriter/XMLEventReader/XMLEventWriter)
• I/O
  • InputStream/OutputStream
  • Reader/Writer
  • byte[] or String
• Other
  • JavaBeans
  • Simple Java Types
  • JSON

What's a transformer?

A transformer is the data conversation logic that transforms data from one format to another format. For example, a transformer can convert the DOM Node into a SDO dataobject. A transformer will be registered as an edge connecting the source databinding to the target databinding. The weight of a transformer represents the cost
of the transformation.

The following is an incomplete list of transformers that we ship in 1.0-incubating release.

and all of them come from the same model in the following XSD type definitions:

    <xsd:complexType name="Customer">
        <xsd:sequence>
            <xsd:element name="id" type="xsd:string"></xsd:element>
            <xsd:element name="firstName" type="xsd:string"></xsd:element>
            <xsd:element name="lastName" type="xsd:string"></xsd:element>
        </xsd:sequence>
    </xsd:complexType>

    <xsd:complexType name="AccountReport">
        <xsd:sequence>
            <xsd:element name="id" type="xsd:string"></xsd:element>
            <xsd:element name="type" type="xsd:string"></xsd:element>
            <xsd:element name="balance" type="xsd:double"></xsd:element>
        </xsd:sequence>
    </xsd:complexType>

Client java component:

SDO_AccountReport getAccountReport(SDO_Customer customer); // SDO_Customer and SDO_AccountReport are generated SDO interfaces

AXIS2 Web Service Stack:

OMElement getAccountReport(OMElement customer); // pseudo method, the operation is defined in WSDL

Service java component:

JAXB_AccountReport getAccountReport(JAXB_Customer customer); // JAXB_Customer and JAXB_AccountReport are generated JAXB classes

What's a databinding?

A databinding represents a specific data format in the Tuscany runtime. Each databinding has a unique name which identifies the data format.

Typical databindings

• XML/Java databinding frameworks
  • SDO
  • JAXB
  • XMLBeans
  • Castor
  • AXIOM
  • FastInfoset
• XML Parsing Technologies
  • SAX (InputSource, ContentHandler)
  • DOM (Node)
  • StAX (XMLStreamReader/XMLStreamWriter/XMLEventReader/XMLEventWriter)
• I/O
  • InputStream/OutputStream
  • Reader/Writer
  • byte[] or String
• Other
  • JavaBeans
  • Simple Java Types
  • JSON

What's a transformer?

A transformer is the data conversation logic that transforms data from one format to another format. For example, a transformer can convert the DOM Node into a SDO dataobject. A transformer will be registered as an edge connecting the source databinding to the target databinding. The weight of a transformer represents the cost
of the transformation.

The following is an incomplete list of transformers that we ship in 1.0-incubating release.

org.apache.tuscany.sca.databinding.sdo.DataObject2String;source=commonj.sdo.DataObject,target=java.lang.String,weight=40
org.apache.tuscany.sca.databinding.sdo.

org.apache.tuscany.sca.databinding.sdo.DataObject2String;source=commonj.sdo.DataObject,target=java.lang.String,weight=40
org.apache.tuscany.sca.databinding.sdo.DataObject2XMLStreamReader;source=commonj.sdo.DataObject,target=javax.xml.stream.XMLStreamReader,weight=10
org.apache.tuscany.sca.databinding.sdo.XMLDocument2String;source=commonj.sdo.helper.XMLDocument,target=java.lang.String,weight=40
org.apache.tuscany.sca.databinding.sdo.String2DataObject;source=java.lang.String,target=commonj.sdo.DataObject,weight=50
org.apache.tuscany.sca.databinding.sdo.XMLDocument2XMLStreamReader;source=commonj.sdo.helper.XMLDocument,target=javax.xml.stream.XMLStreamReader,weight=10
org.apache.tuscany.sca.databinding.sdo.XMLStreamReader2DataObject;source=javax.xml.stream.XMLStreamReader,target=commonj.sdo.DataObject,weight=15
org.apache.tuscany.sca.databinding.sdo.XMLStreamReader2XMLDocument;source=javax.xml.stream.XMLStreamReader,target=commonj.sdo.helper.XMLDocument,weight=15
org.apache.tuscany.sca.databinding.sdo.DataObject2Node;source=commonj.sdo.DataObject,target=org.w3c.dom.Node,weight=40
org.apache.tuscany.sca.databinding.sdo.Node2DataObject;source=org.w3c.dom.Node,target=commonj.sdo.DataObject,weight=40

org.apache.tuscany.sca.databinding.xml.InputSource2Node;source=org.xml.sax.InputSource,target=org.w3c.dom.Node,weight=40
org.apache.tuscany.sca.databinding.xml.InputStream2Node;source=java.io.InputStream,target=org.w3c.dom.Node,weight=40
org.apache.tuscany.sca.databinding.javabeans.DOMNode2JavaBeanTransformer;source=org.w3c.dom.Node,target=java.lang.Object,weight=10000
org.apache.tuscany.sca.databinding.xml.Node2String;source=org.w3c.dom.Node,target=java.lang.String,weight=40
org.apache.tuscany.sca.databinding.xml.Node2XMLStreamReader;source=org.w3c.dom.Node,target=javax.xml.stream.XMLStreamReader,weight=40
org.apache.tuscany.sca.databinding.javabeans.JavaBean2DOMNodeTransformer;source=java.lang.Object,target=org.w3c.dom.Node,weight=10000
org.apache.tuscany.sca.databinding.xml.Reader2Node;source=java.io.Reader,target=org.w3c.dom.Node,weight=40
org.apache.tuscany.sca.databinding.xml.SAX2DOMPipe;source=org.xml.sax.ContentHandler,target=org.w3c.dom.Node,weight=30
org.apache.tuscany.sca.databinding.xml.StreamDataPipe;source=java.io.OutputStream,target=java.io.InputStream,weight=50
org.apache.tuscany.sca.databinding.xml.String2Node;source=java.lang.String,target=org.w3c.dom.Node,weight=50
org.apache.tuscany.sca.databinding.xml.String2XMLStreamReader;source=java.lang.String,target=javax.xml.stream.XMLStreamReader,weight=50
org.apache.tuscany.sca.databinding.xml.Writer2ReaderDataPipe;source=java.io.Writer,target=java.io.Reader,weight=50
org.apache.tuscany.sca.databinding.xml.XMLStreamReader2Node;source=javax.xml.stream.XMLStreamReader,target=org.w3c.dom.Node,weight=40
org.apache.tuscany.sca.databinding.xml.XMLStreamReader2String;source=javax.xml.stream.XMLStreamReader,target=java.lang.String,weight=40
org.apache.tuscany.sca.databinding.xml.Node2SimpleJavaType;source=org.w3c.dom.Node,target=java:simpleType,weight=10000
org.apache.tuscany.sca.databinding.xml.SimpleJavaType2Node;source=java:simpleType,target=org.w3c.dom.Node,weight=10000

org.apache.tuscany.sca.databinding.axiom.Object2OMElement;source=java:simpleType,target=org.apache.axiom.om.OMElement,weight=10000
org.apache.tuscany.sca.databinding.axiom.OMElement2Object;source=org.apache.axiom.om.OMElement,target=java:simpleType,weight=10000
org.apache.tuscany.sca.databinding.axiom.OMElement2String;source=org.apache.axiom.om.OMElement,target=java.lang.String,weight=40
org.apache.tuscany.sca.databinding.axiom.OMElement2XMLStreamReader;source=org.apache.axiom.om.OMElement,target=javax.xml.stream.XMLStreamReader,weight=10
org.apache.tuscany.sca.databinding.axiom.String2OMElement;source=java.lang.String,target=org.apache.axiom.om.OMElement,weight=40
org.apache.tuscany.sca.databinding.axiom.XMLStreamReader2OMElement;source=javax.xml.stream.XMLStreamReader,target=org.apache.axiom.om.OMElement,weight=10

org.apache.tuscany.sca.databinding.jaxb.JAXB2Node;source=javax.xml.bind.JAXBElement,target=org.w3c.dom.Node,weight=30
org.apache.tuscany.sca.databinding.jaxb.Node2JAXB;source=org.w3c.dom.Node,target=javax.xml.bind.JAXBElement,weight=30
org.apache.tuscany.sca.databinding.jaxb.Reader2JAXB;source=java.io.Reader,target=javax.xml.bind.JAXBElement,weight=30
org.apache.tuscany.sca.databinding.jaxb.XMLStreamReader2JAXB;source=javax.xml.stream.XMLStreamReader,target=javax.xml.bind.JAXBElement,weight=10

org.apache.tuscany.sca.databinding.saxon.Node2NodeInfoTransformer;source=org.w3c.dom.Node,target=net.sf.saxon.om.NodeInfo,weight=10
org.apache.tuscany.sca.databinding.saxon.NodeInfo2NodeTransformer;source=net.sf.saxon.om.NodeInfo,target=org.w3c.dom.Node,weight=10
org.apache.tuscany.sca.databinding.saxon.Object2ValueTransformer;source=java.lang.Object,target=net.sf.saxon.value.Value,weight=10000
org.apache.tuscany.sca.databinding.saxon.Value2ObjectTransformer;source=net.sf.saxon.value.Value,target=java.lang.Object,weight=10000
org.apache.tuscany.sca.databinding.saxon.SimpleType2ValueTransformer;source=java:simpleType,target=net.sf.saxon.value.Value,weight=10000
org.apache.tuscany.sca.databinding.saxon.Value2SimpleTypeTransformer;source=net.sf.saxon.value.Value,target=java:simpleType,weight=10000
org.apache.tuscany.sca.databinding.saxon.NodeInfo2DataObjectTransformer;source=net.sf.saxon.om.NodeInfo,target=commonj.sdo.DataObject,weight=20
org.apache.tuscany.sca.databinding.saxon.DataObject2NodeInfoTransformer;source=commonj.sdo.DataObject,target=net.sf.saxon.om.NodeInfo,weight=10

org.apache.tuscany.sca.databinding.sdo2om.DataObject2OMElement;source=commonj.sdo.DataObject,target=org.apache.axiom.om.OMElement,weight=1000
org.apache.tuscany.sca.databinding.sdo2om.XMLDocument2OMElement;source=commonj.sdo.helper.XMLDocument,target=org.apache.axiom.om.OMElement,weight=1000

...

interfaces for services and references are the contracts for SCA assembly.

Data Transformations

How to transform data across databindings

• A databinding is a terminal for the data transformation
• Three types of databindings depending on how the data is represented by the databinding
  • Some databindings can feed the data for consumption
  • Some databindings serve a sink to receive data
  • Some databindings can bridge the sink so that data coming into the sink can be consumed by others
    Scenario 1: Source --> Source
    Scenario 2: Source --> Sink
    Scenario 3: Sink --> Source (Pipe)

How to use databindings?
Declare the data binding for the interfaces

• Data Binding requirement can be expressed as:
  • SCDL extension

@Remotable
public interface MyInterface {
    Node call(Node msg); 
    XMLStreamReader call1(XMLStreamReader msg); 
}

Fine-grained databinding control

Java annotations for a remotable interface

Data mediation on the wire

DataBindingRuntimeWireProcessor is responsible to insert a DataTransformationInteceptor into the invovcation chains if the data transformation is required between the source and target operations. Depending on the invocation patterns, it uses the effective interface contracts to determine if transformation should be applied.

Typically, there are three cases:

Introspection of java interfaces for data types

The DataBindingJavaInterfaceProcessor is responsible to introspect the java interfaces to figure out the databindings of the parameters and return types. It delegates to all of the databinding implementations which will set the databinding and logical type if such data type is recognized by the databinding. This introspection process can handle most of the cases as the java types usually have some patterns, for example, implementing a know interface.

Special databindings and transformers to deal with operation-level transformations

• Input2InputTransformer: Transform the input data from the source operation to the input data expected by the target operation
• Output2OutputTransformer: Transform the output data from the target operation to the output data expected by the source operation
• Exception2ExceptionTransformer: Transform the fault data from the target operation to the fault data expected by the source operaion

Deal with interfaces defined using different IDLs

• SCA allows the interfaces to be defined using various IDLs, for example, java interface or WSDL portType
• IDLs may have different ways to represent the input/output/fault data
• The databinding framework is designed to support the transformation across IDLs

• Some special databindings are internally used for this purpose:
  • idl:input The input data format for an operation
  • idl:output: The output data format for an operation
  • idl:fault: The fault data format for an operation

• SimpleTypeMapper: convert data between XSD simple types (by the databinding, for example, OMElement with an OMText child) and java objects

Operation-level transformations

The signature of an operation is modeled as follows:

• InputType: The data type for the input. The logical type is a list of data types that represent the list of parameters
• OutputType: The data type for the output. The logical type is the data type that represents the return value
• FaultTypes: The list of data types for all the faults

Image Removed

...

Introspection of java interfaces for data types

The DataBindingJavaInterfaceProcessor is responsible to introspect the java interfaces to figure out the databindings of the parameters and return types. It delegates to all of the databinding implementations which will set the databinding and logical type if such data type is recognized by the databinding. This introspection process can handle most of the cases as the java types usually have some patterns, for example, implementing a know interface.

Data mediation in the SCA assembly

DataBindingRuntimeWireProcessor is responsible to insert a DataTransformationInteceptor into the invovcation chains if the data transformation is required between the source and target operations. Depending on the invocation patterns, it uses the effective interface contracts to determine if transformation should be applied.

Typically, there are three cases:

Data transformation between SCA components

• Data transformation can be performed on wire for remotable interfaces
• Data transformation can handle interfaces defined using different IDLs such as Java or WSDL.

Image Added

Data transformation for service bindings

• <interface.xxx> defines the outbound service contract (SC2) which can be wired to a target component, reference or service (SC3).
• <binding.xxx> can optionally hint a service contract for the inbound data from the binding protocol layer. Image Added

Data transformation for reference bindings

• <interface.xxx> defines the inbound service contract (SC2) which can be wired from a source component, reference or service (SC1).
• <binding.xxx> can optionally hint a service contract (SC3) for the outbound data to the binding protocol layer.

Image Added

Data transformation for property values

• Property values are loaded from SCDLs as DOM documents
• The DOM Document can be transformed into a java object under a databinding, such as SDO, JAXB so that the component implementation code can work with the databinding directly instead of DOM.

Image Added

Special databindings and transformers to deal with operation-level transformations

• Input2InputTransformer: Transform the input data from the source operation to the input data expected by the target operation
• Output2OutputTransformer: Transform the output data from the target operation to the output data expected by the source operation
• Exception2ExceptionTransformer: Transform the fault data from the target operation to the fault data expected by the source operaion

Deal with interfaces defined using different IDLs

• SCA allows the interfaces to be defined using various IDLs, for example, java interface or WSDL portType
• IDLs may have different ways to represent the input/output/fault data
• The databinding framework is designed to support the transformation across IDLs

• Some special databindings are internally used for this purpose:
  • idl:input The input data format for an operation
  • idl:output: The output data format for an operation
  • idl:fault: The fault data format for an operation

• SimpleTypeMapper: convert data between XSD simple types (by the databinding, for example, OMElement with an OMText child) and java objects

Operation-level transformations

The signature of an operation is modeled as follows:

• InputType: The data type for the input. The logical type is a list of data types that represent the list of parameters
• OutputType: The data type for the output. The logical type is the data type that represents the return value
• FaultTypes: The list of data types for all the faults

Image Added

Wrapper style WSDL operation

<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions name="AccountService" targetNamespace="http://www.example.org/AccountService/"
    xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:tns="http://www.example.org/AccountService/"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <wsdl:types>
        <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
            targetNamespace="http://www.example.org/AccountService/">

            <xsd:complexType name="Customer">
                <xsd:sequence>
                    <xsd:element name="id" type="xsd:string"></xsd:element>
                    <xsd:element name="firstName" type="xsd:string"></xsd:element>
                    <xsd:element name="lastName" type="xsd:string"></xsd:element>
                </xsd:sequence>
            </xsd:complexType>

            <xsd:complexType name="AccountReport">
                <xsd:sequence>
                    <xsd:element name="id" type="xsd:string"></xsd:element>
                    <xsd:element name="type" type="xsd:string"></xsd:element>
                    <xsd:element name="balance" type="xsd:double"></xsd:element>
                </xsd:sequence>
            </xsd:complexType>

            <xsd:element name="getAccountReport">
                <xsd:complexType>
                    <xsd:sequence>
                        <xsd:element name="customer" type="tns:Customer"></xsd:element>
                    </xsd:sequence>
                </xsd:complexType>
            </xsd:element>

            <xsd:element name="getAccountReportResponse">
                <xsd:complexType>
                    <xsd:sequence>
                        <xsd:element name="report" type="tns:AccountReport"></xsd:element>
                    </xsd:sequence>
                </xsd:complexType>
            </xsd:element>
        </xsd:schema>
    </wsdl:types>
    <wsdl:message name="getAccountReportRequest">
        <wsdl:part name="parameters" element="tns:getAccountReport"></wsdl:part>
    </wsdl:message>
    <wsdl:message name="getAccountReportResponse">
        <wsdl:part name="return" element="tns:getAccountReportResponse"></wsdl:part>
    </wsdl:message>
    <wsdl:portType name="AccountService">
        <wsdl:operation name="getAccountReport">
            <wsdl:input message="tns:getAccountReportRequest"></wsdl:input>
            <wsdl:output message="tns:getAccountReportResponse"></wsdl:output>
        </wsdl:operation>
    </wsdl:portType>
</wsdl:definition

The WrapperHandler provides wrapper style WSDL wrapping/unwrapping support

...