Re: [wsbpel] Issue 103 - draft proposal

[Alex Yiu <alex.yiu@oracle.com>]

Hi all,

As promised in the conf call last week, here is the draft proposal for 
Issue 103.

Please note that is a draft version of the proposal, NOT the final 
version that will be used for voting yet. Especially, there are some 
options listed in the proposal for item (1B) and (2C) and (3B) (with 
some preferences expressed). 

Please voice your opinions so that we know that we are solving Issue 103 
in a right way.

Thanks!



Regards,
Alex Yiu

Title: Issue 103 Proposed Resolution

Issue 103 Proposed Resolution

Subject: Standardizing $varName syntax for XPath to refer to a BPEL variable

Draft Version #4 
    [V4: Kevin Liu has kindly reviewed WSDL part of the proposal. Factoring in some feedback from Kevin into V4.]

May 02, 2004  - 1am PDT

Goals:

To simplify the XPath syntax to access BPEL variable, including both
simple type, schema element of complex type, and WSDL Message type. 

Its advantages:

• simpler, less typing
  
• easier and better static analysis analysis in XPath: a variable reference can have a more specific type, instead of a generic getVariableData() which essentially returns xsd:any.
  
• E.g.: one can apply XPath directly to a variable. E.g.: "$var/some/xpath/here"
• providing the XML-Schema Element emulation for WSDL 1.1 message type
• This emulation can make WSDL 1.1 message available to any XML programming facilities and infrastructures which are not WSDL 1.1 aware
• This can potentially help migration of BPEL programs from WSDL 1.1 to WSDL 2.0 (e.g. a straight forward global search-and-replace may do). However, a completely effortless migration is a NON-GOAL, since WSDL 2.0 specification is still in progress and its related WS-I activities have not been bootstrapped yet and there are multiple paths to migrate a WSDL 1.1 to WSDL 2.0.
  

This proposed resolution consists of:
(1) Adding $var syntax and simplifying from-spec and to-spec
(2) Representing WSDL Message Types as if XML-Schema Element
(3) Removing bpws:getVariableData() and etc
(4) Terminology change in variable declaration

(1) Adding $var syntax and simplifying from-spec and to-spec

The additional $var syntax already got standardized in XPath 1.0 (also in XPath 
  2.0 and XQuery spec) for a while. Its semantics and syntax are very stable and 
  clear to existing XPath users and future XQuery users.

The value of a BPEL variable, which appears as Variable-Reference in
XPath 1.0, corresponds to a node-set of exactly one XML node in XPath
1.0 semantics. The XML node corresponds to the element node (not
document node) of related BPEL variable, when the variable is declared
with  "element"  attribute or  "messageElement"
attribute. ["messageElement" is an attribute introduced in in part (4)
below.]

References: 
http://www.w3.org/TR/xpath#NT-FunctionCall
http://www.w3.org/TR/xpath#NT-VariableReference

After introducing $var syntax [provided that we can represent WSDL
Message as XML Schema Element;  please see in (2) below], we can simplify assign by
eliminating some variation of from-spec and to-spec. 

Current from-specs:
<from variable="ncname" part="ncname"?/>
<from partnerLink="ncname" endpointReference="myRole|partnerRole"/>
<from variable="ncname" property="qname"/>
<from expression="general-expr"/>
<from> ... literal value ... </from>


Current to-specs: 

<to variable="ncname" part="ncname"?/>

<to partnerLink="ncname"/>

<to variable="ncname" property="qname"/>

(1A)
<from variable="ncname" part="ncname"? /> 
    will be eliminated and merged into:
         <from>
        <expression>general-expr</expression>
     </from>
            [Here we use the post-Issue-13 syntax.]

(1B) About from-spec: <from variable="ncname" property="qname"/>
(1B)(option-I) from-spec: <from variable="ncname" property="qname"/> remains unchanged, if we go for (3B)(I) below.
(1B)(option-II) from-spec: <from
variable="ncname" property="qname"/> will be merged into expression
variant of from-spec also, if we go for (3B)(II) below

For example:
    [EX-1]
    <from variable="myVar" />
        => <from> <expression>$myVar</expression </from>
    [EX-2]
    <from variable="myWSDLMsg" part="part1" />  
        => <from>
<expression>$myWSDLMsg/part1</expression>
</from>
   
            [For details,
please see (2) below on how to deal with WSDL message]

For executable BPEL, 
    [EX-3]
    <from variable="myVar" query="/some:elem/some:more_xpath" />
        => <from>
<expression>$myVar/some:more_xpath</expression>
</from>

[*** NOTE: the "some:elem" NameTest part of XPath is dropped, because $myVar is now pointing to an element, instead of a document. The XPath is now relative to the element, instead of the document. ***]

    [EX-4]
    <from variable="myWSDLMsg" part="part1" query="/some_query_path" />
        => 
        <from>
            <expression>$myWSDLMsg/part1/some_query_path</expression>
   
        </from>

For abstract BPEL, <from opaque="true" /> will remain the same. 

(1C) 
to-spec: <to variable="ncname" part="ncname"? /> : the part attributed will be dropped: 

For core part of BPEL spec:
<to variable="ncname" />

For executable part of BPEL spec: 
<to variable="ncname">
    <query>some_query_path</query>
</to> 
[Again, using post-issue-13 syntax here]

[EX-5]
<to variable="myWSDLVar" part="part01" /> 
will becomes: 
<to variable="myWSDLVar">
    <query>/part01</query>
</to> 


[*** NOTE: the root element
NameTest part of XPath will be also dropped in the xpath used in the
to-spec, compared with the situation before passing this proposal. ***]

The part semantics is moved into and encapsulated in the query path (e.g. XPath).
[For details, please see (2) below on how to deal with WSDL message]

(1D)
to-spec: <to variable="ncname" property="qname" /> can be merged
into query version of to-spec similar to (1C) above, if we go for
(3B)(II) below. If we don't go for (3B)(II), it will be kept unchanged. 

(1E)
That implies that we would still have two sub-language used in BPEL:
one is query language; one is expression language.  [For example,
expression language may be XQuery, while query may be XPath.]

(2) Representing WSDL Message Types into XML-Schema Element

Currently, WSDL-1.1-message based variables are available to XML-based
languages (e.g. XPath, XSLT, XQuery and etc) through
bpws:getVariableData(). However, this function approach make the static
type and path analysis very difficult and anti-intuitive, because all
different types of variables are available through the same function. 

Here, we suggest to use $var syntax to represent variables in XPath and
etc. In order to achieve that, we need to apply a logical mapping to
WSDL 1.1 message types to emulate XML Schema Elements. Given a WSDL 1.1
message type, there will be a XML Schema Element definition mapped out.

The definition serves as a logical structure for XML-based language
(e.g. XPath) to access different parts of WSDL 1.1 message. The
physical message format can vary a lot depending
on the related bindings, styles, deployment options, and platforms of
the web services. [Factored-in points from KL here] Please note that
the name used in wsdl:message is really like a place holder, its name
never appear in the wired message. So the logical message is only for
the purpose of accessibility via XPath, and actually it will never
match the wired message format. 

The mapping will be done by BPEL engine (static analysis and runtime)
automatically.  The mapping and XPath usage for existing BPEL
users is actually very
very obvious. Before going into details of mappings, here are some more
examples of from-spec and to-spec:  (additional to [EX-2] and
[EX-4] above)

<from variable="myMsg" part="part01" query="/some_x_path" />

is changed into: 
<from expression="$myMsg/part01/some_x_path" />

<to variable="myMsg" part="part01" query="/some_x_path" />

is changed into:
<to variable="myMsg" query=/part01/some_x_path" />


The mapping from typical users point of view is very straight forward. The
description of mapping is quite detailed, because we want to be
clear in the spec to minimize any ambiguity. (The situation is just similar XMLNS or XPath itself. The XPath or
XMLNS usage is easy, while the specs for XPath or XMLNS are still quite
lengthy.) 


Please note: the current spec is quite silent on how the
"/some_x_path" should look like regarding to differences between
wsdl:part@type and wsdl:part@element. After passing Issue 103, what the
"/some_x_path" should look like will be much more clear. 

For the following WSDL-1.1-message to XML-Schema  mapping, we have
already considered parts of WSDL 2.0 specification. For example, a WSDL
2.0 must be an XML Schema element. The mapping pattern and usage of XPath in proposal will help people
migrate their BPEL from WSDL 1.1 to WSDL 2.0 in future. It will
minimize the impact to BPEL program, especially if they are using WSDL 1.1 with
message parts.


Rules to do the mapping WSDL 1.1 type to XML Schema Element:

(The XSLT stylesheet fragments are intended for ILLUSTRATION ONLY on
how to map a WSDL 1.1 message type to an XML Schema Element in the
usage context of BPEL4WS 1.1. They are NEVER intended to be any
normative part of the BPEL4WS spec or other specifications or a part of
programming components.

Reference: 
WSDL 1.1 XML Schema: http://schemas.xmlsoap.org/wsdl/2003-02-11.xsd   
[Factored-in points from KL here] Using WS-I schema is in line with our
decision to be WS-I BP compatible. We shall need to check back later,
as WS-I BP may change further the schema to allow extension everywhere.
)


        
(2A) A "wsdl:message" element
is mapped to "xsd:element" element which shares the same "name"
attribute value. The "xsd:element" is defined based on an anonymous
complex type of which contains a sequence. The content of sequence will
be mapped from "wsdl:part" to a series of "xsd:element" based on the
rules (2B) and (2C) below. 

    <xsl:template match="wsdl:message">
        <xsd:element name="{@name}" > 
            <xsd:complexType>
                <xsd:sequence>
                    <xsl:apply-templates/>
                </xsd:sequence>
            </xsd:complexType>
        </xsd:element>
    </xsl:template>

(2B) A "wsdl:part" element
which has an "type" attribute is mapped to "xsd:element", which shares
the same "name" and "type" attribute values. The "xsd:element" has both
minOccurs and maxOccus set to 1. 


    <xsl:template match="wsdl:part[@type]">

        <xsd:element name="{@name}" type="{@type}" minOccurs="1" 
            maxOccurs="1" />

    </xsl:template>


(2C) There are two versions of mapping for a "wsdl:part" element which has an "element" attribute. 

(2C)(option-I) A "wsdl:part" element
which has an "element" attribute is mapped to an "xsd:element" which
has a "ref" attribute referring to the element in "wsdl:part". The
"xsd:element" has minOccurs=1 and maxOccurs="1". 



    <xsl:template match="wsdl:part[@element]">


        <xsd:element ref="{@element}" minOccurs="1" maxOccurs="1" />


    </xsl:template>

(2C)(option-II) A "wsdl:part" element
which has an "element" attribute is mapped to an "xsd:element" which
share the same "name" attribute value with "wsdl:part". The
"xsd:element" is based on an anonymous complex type, which has a
sequence of one "xsd:element. The "xsd:element" has a "ref" attribute
referring to the element in "wsdl:part" and has minOccurs=1 and
maxOccurs="1". 

    <xsl:template match="wsdl:part[@element]">
        <xsd:element name="{@name}">
            <xsd:complexType>
                <xsd:sequence>
   
           
    <xsd:element ref="{@element}" minOccurs="1" 
           
            maxOccurs="1"
/>
                </xsd:sequence>
            </xsd:complexType>
        </xsd:element>
    </xsl:template>


[Preference is given to (2C)(option-II).
Because we have more intuitive and more versatile XPath usage to access
a message part.]

Using (2A), (2B) and (2C)(II) rules above and changes in (4) below, the
XPath to access parts in WSDL 1.1 Message Element would be:

[*** NOTE:  For a variable declared similar to the following:
<variable name="myVar" messageElement="myWSDL:POMsgType" />

The XPath for a part (no matter it is declared with type or element attribute) would be: "$myVar/partName" 

The QNAME of "myWSDL:POMsgType" does not present in the XPath, because
the variable is refering to the element node, instead of document node.
***]

[EX-6]
For example, for the following WSDL 1.1 message definition:
<message name="GetLastTradePriceInput">
        <part name="body" element="foo:TradePriceRequest"/>
</message>

will be mapped to the following XML Schema Element:

<xsd:element xmlns:xsd="http://www.w3.org/2001/XMLSchema"  
    name="GetLastTradePriceInput">
    <xsd:complexType>
        <xsd:sequence>
            <xsd:element name="body">
                <xsd:complexType>
                   
<xsd:sequence>
                       
<xsd:element ref="foo:TradePriceRequest" minOccurs="0" maxOccurs="1"/>
                   
</xsd:sequence>
                </xsd:complexType>
            </xsd:element>
        </xsd:sequence>
    </xsd:complexType>
</xsd:element>

(3) Removing some bpws:getVariableData() and etc

(3A) About bpws:getVariableData():
After adding $var syntax and providing XML-Schema-Element emulation
over WSDL message variables, we do not need bpws:getVariableData()
function any more.

(3B) About bpws:getVariableProperty()
We prefer (3B)(I) over (3B)(II), because we may not want to introduce targetNamespace concept for message properties for this cycle of BPEL spec.   

(3B)(option-I) We suggest to keep bpws:getVariableProperty('variable_name','property_name') unchanged. 
(3B)(option-II) Alternatively, we can add virtual elements for applicable properties to a WSDL message,  provided
that we associate a formal concept of "targetNamespace" to properties
definition. (As of now, we don't have properties definition is NOT
associated with a targetNamespace.)

After associating targetNamespace, we can have the following syntax:

$variable_name/tns:property_name

(3C) About bpws:getLinkStatus('a_LinkName')

In "Section 9.1 Expression", the specification said, "This function MUST NOT be used anywhere except in a join condition." 

In "Section 12.5.1 Link Semantics", the specification said, "The expression for a join 
			condition for an activity MUST be constructed using only Boolean operators 
			and the bpws:getLinkStatus function (see 9.1. Expressions) 
			applied to incoming links at the activity."

With the current semantics of section 12.5.1 and section 9.1, we
could potentially replace bpws:getLinkStatus('a_LinkName') by boolean
link
variables: 

bpws:getLinkStatus('a_LinkName')
    => $a_LinkName

However, as we cannot be sure that restrictions in section 12.5.1 and
9.1 hold true in future, then we suggest to keep bpws:getLinkStatus(...).
Because this is just a pure syntax shortcut without much semantic
advantages.

(4) Terminology change in variable declaration

Currently, there are 3 attributes related to type declaration in <variable> element: "messageType", "type" and "element".

We suggest to have a minor change: from "messageType" to
"messageElement". The new attribute match better with semantics of
emulating / representing WSDL 1.1 message type as XML Schema Element.

END