Design

Normalized message header design

Refer Normalized Message Header design before continuing to read the BPEL SE specific design.

BPEL syntax design

WS-BPEL uses properties in two formats, extensions are added to these formats for supporting access to Normalized Message properties. Examples as per specification and using extension are illustrated side by side for better understanding.

WS-BPEL snippets showing usage of property defined in the WSDL

  <from variable="variable1" property="ns0:stringProp"/>

  getVariableProperty('variable1', 'ns0:stringProp')

property "stringProp" is defined in the WSDL document. It has two parts. A- property definition, B- one or more property alias definitions, more than one property alias is required when property is referring to more than one type (message/xsd)

    <vprop:property name="stringProp" type="xsd:string"/>
   
    <vprop:propertyAlias propertyName="tns:stringProp" messageType="tns:message" part="part1">
            <vprop:query>/ns0:person/name</vprop:query>
    </vprop:propertyAlias>

message's part1 is defined as "person" element in the following schema

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema 	targetNamespace="http://localhost/person"
                attributeFormDefault="unqualified"
                elementFormDefault="qualified"
	   	xmlns:xs="http://www.w3.org/2001/XMLSchema"
	   	xmlns:tns="http://localhost/person">
    <xs:element name="person">
        <xs:complexType>
            <xs:sequence>
                <xs:element name="name" type="xs:string"/>
                <xs:element ref="tns:birthdate"/>
            </xs:sequence>
        </xs:complexType>
    </xs:element>
    <xs:element name="birthdate">
        <xs:complexType>
            <xs:sequence>
                <xs:element name="month" type="xs:string" />
                <xs:element name="day" type="xs:int" />
                <xs:element name="year" type="xs:int" />
            </xs:sequence>
        </xs:complexType>
    </xs:element>
</xs:schema>

Both from & getVariableProperty evaluate person's name element in the document.

WS-BPEL extension to support access to headers.

First version adds extension to propertyAlias element in WSDL

    <vprop:propertyAlias propertyName="tns:stringProp"
                                     nmProperty="org.glassfish.openesb.jms.destination">
    </vprop:propertyAlias>

and second version adds extension to from/to elements and getVariableProperty in WS-BPEL also known as in-line

<from variable="xsdStringVariable" nmProperty="org.glassfish.openesb.jms.destination"/> 

 getVariableProperty('xsdStringVariable', 'org.glassfish.openesb.jms.destination')

When Normalized Message property value is MAP or document fragment, users needs to use propertyAlias's query element to access the node they are interested by defining xpath query. query is not supported in the in-line version of the syntax.

Accessing SOAP header Property name is "org.glassfish.openesb.headers.soap". Let us assume one of the SOAP header is a document as per Person schema.

        <vprop:propertyAlias propertyName="tns:propertyName1"
            nmProperty="org.glassfish.openesb.headers.soap"
            messageType="tns:simpleCorrelation1Message"> => optional message attribute, if provided will just be a hint for editor validation and optimization for runtime.
            <vprop:query xmlns:ns0="http://localhost/person">/ns0:person</vprop:query>               => optional query element is to identifying the header & to drill down to the node user is interested. If user is interested in name query would be /ns0:person/ns0:name
        </vprop:propertyAlias>

Accessing HTTP header Property name is "org.glassfish.openesb.headers.http"

        <vprop:propertyAlias propertyName="tns:propertyName1"
            nmProperty="org.glassfish.openesb.headers.http"
            messageType="tns:simpleCorrelation1Message"> => optional message attribute, if provided will just be a hint for editor validation and optimization for runtime.
            <vprop:query >/Content-Type</vprop:query>   => optional query element is to identifying the header & value is string so it is invalid do drill down. Runtime would return the value or throw standard fault based on the query reslt.
        </vprop:propertyAlias>

On the BPEL Editor side

• The editor needs to know all the different properties of all the different BCs. The way to solve this could be using BPEL editor plugin NBMs. All BCs which want their properties to be displayed in the editor will come up with a NBM plugin that the user will install. This should be taken care of the released version of product as well.
• The editor will ask the user to provide the xsd for the soap:header (or other header) properties to help the user construct the query, and type information can be stored as additional attributes on the propertyAlias. Further refining of the usability is needed. What if the user didn't want to import the XSD? but just for the query construction he provided the XSD location. When editor generates property and propertyAlias it needs to persist them to WSDL file, it would be similar to correlation wizard.

BPEL Editor support

Persistence

Check back in two weeks for this story

In the above propertyAlias is still from the "vprop" namespace defined by BPEL spec. 
\\Should we define a new one? Meaning a new propertyAlias XSD that recognizes "nmProperty" 
\\ or should we use the same "vprop" namespace for it?

    <vprop:propertyAlias propertyName="tns:propertyName1"
                        nmProperty="com.sun.jms.transport.properties::connectionUrl"
                        messageType="tns:simpleCorrelation1Message">              => optional message attribute                
    </vprop:propertyAlias>

This applies to the inlined variable From/To syntax.

If it is the same namespace it is less work for engine and editor. On the other hand If we 
\\have an XSD that defines this element, then other party tools can import our files and if 
\\they somehow get the XSD, their system can understand our WSDL files.

Although the second approach is architecturally preferred, I prefer first approach for 
\\simplicity and practicality. This is a highly custom field that won't work in their editors 
\\or engines. Their engine should be a JBI engine as well and they should also understand how 
\\to insert and read the properties on the NM. If these files are imported into some third 
\\party BPEL/WSDL editor they need to delete extended element entries anyway.

-Kiran.

> 1. Why we use full namespaces instead of prefixes in nmProperty attribute?

\\RESP: I was initially thinking of prefixes. I chose this approach because this will keep the BPEL-SE 
\\agnostic of any new BC identifying keys like com.sun.file.transport.properties, 
\\com.sun.jms.transport.properties, com.sun.jbi.headers.soap. A prefix needs a NS and lets say 
\\we come up with Namespaces for all the keys above, and engine will know this today. But when 
\\there is a new BC in the JBI system, engine code will not work without actually knowing how 
\\to map that prefix to the correct key. Which would require a change to BPEL-SE whenever a new 
\\BC plans to start supporting headers. Going this route that I suggested below instead of prefixes 
\\BPEL-SE can work without any changes.

> 2. There is no much help in defining messageType attribute for nmProperties, unless this is a 
\\REQUIRED attribute. If this attribute is optional, when editor shows a list of variable properties 
\\for given variable, the general rule "show only properties with matching message type" will not work.

\\RESP: Yes, this is correct. I decided not to make this MANDATORY because logically these properties are not 
\\really associated with the WSDL:Message. They are on the NM and these properties are logically more 
\\linked to the "operation, binding and binding component". The same property can be used by different 
\\BCs which send different messages. So when that is the use case, the user could just omit the "message" 
\\attribute and editor will show this property for all the variables. As I said, if the "message" attribute 
\\is there, it could be used as a hint for filtering in editor and maybe some optimization at runtime.

> 3. I pretty much like the idea of using inline property reference into From and To elements. The editor 
\\behavior will be much simplier and understandable when using this way of accessing nmProperties. 
\\The only reason I see for separate property definition is to use this property in correlation sets. 
\\Is this a valid usecase?

\\RESP: Yes, I just wanted to do this inline and do away with the property/propertyAlias approach until I 
\\came to know of this correlation use case. I had an email discussion with Ron and he said that was part 
\\of the idea of the propertyAliases in BPEL spec and NM headers in JBI. Also it seems this has been a use
\\ case that is wanted by JMS for quite some time.