[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Subject: RE: BTP messaging issues list
Attached is an updated version of the messaging section of the spec. It has been updated to 0.6 and cleaned up in general. It also contains a slightly updated list of issues than the list below. Alex -----Original Message----- From: James Tauber [mailto:jtauber@bowstreet.com] Sent: Wednesday, September 05, 2001 4:55 PM To: 'business-transaction@lists.oasis-open.org' Subject: BTP messaging issues list Here's an outline of the remaining issues to discuss. Are then any others that need to be added? It would be great to get through as many of these as possible on the call tomorrow. 1. asynchronous messaging only 2. are any of the interactions are out of scope? not sure if concrete messages for Initiator to Factory, Cohesion to Coordinator, etc. are in scope. 3. is timelimit absolute or relative? 4. mime issue proposed solution: provide a soap + attachments binding in addition to the soap binding 5. can BTP messages exist without the btp:messages wrapper element? 6. do btp faults get wrapped in soap faults or live in separate layers (came up in DSML) 7. have we decided to do relationships by containment? James ---------------------------------------------------------------- To subscribe or unsubscribe from this elist use the subscription manager: <http://lists.oasis-open.org/ob/adm.pl>Title: BTP Messaging
This sub-specification builds on the BTP abstract messages by providing concrete representations of these messages in XML. Each abstract message has a corresponding XML message that is independent of any other messages or binding.
A binding from these concrete XML messages to SOAP 1.1 is included.
This document contains the following
This section describes the syntax for BTP messages in XML. These XML messages represent a midpoint between the abstract messages and what actually gets sent on the wire. Also, not all of these XML messages will always be necessary; for example, if a Factory actor exposes a Java API, then a Java based Initiator could use that API directly instead of sending XML messages.
The notion of bindings is introduced to act as the glue between the BTP XML messages and an underlying transport. The SOAP binding describes how BTP messages will be carried using SOAP. This document specifies two bindings: a SOAP binding and a SOAP + Attachments binding. Although these are the only two bindings contained in this version of the BTP specification, that doesn't proclude the possibility of other bindings being created in the future, either by the Oasis BTP technical committee or by a third party. For example, in the future a binding might exist to put a BTP message directly on top of HTTP without the use of SOAP.
All BTP related URIs have been created using Oasis URI conventions as specified in RFC 3121
BTP XML Namespace: urn:oasis:names:tc:BTP:xml
@@@ is it possible to get a date inside our URIs?
@@@ Karl: 1. can get lowercase btp instead of BTP? 2. are our URIs created in spirit of the Oasis URI spec?
In addition to an XML schema, this specification uses an informal syntax to describe the structure of the BTP messages. The syntax appears an an XML instance, but the values contain data types instead of values. Occasionally the following symbols will be appended to XML constructs: ? (zero or one), * (zero or more), + (one or more.) The absense of one of these symbols corresponds to "one and only one."
Examples:
<btp:some-address> <btp:binding>...carrier binding URI...</btp:binding> <btp:binding-address>...carrier specific URI...</btp:binding-address> <btp:additional-information>...optional additional addressing information...</btp:additional-information> ? </btp:some-address>
Here is an example of an address that would be used when using SOAP + HTTP:
<target-address> <binding>urn:oasis:names:tc:BTP:binding:soap-http</btp:binding> <binding-address>http://www.example.com/Servlet/BTP/dispatch?coordinator=12345</binding-address> </target-address>
In the above address, the URI in carrier-address is sufficient to route the message.
Address bindings:
@@@ alastair mentioned that the BTP version should be included in the binding URI, does this mechanism suffice?
A "published" address can be a set of <some-address>, which are alternatives which can be chosen by the peer (sender.) Multiple addresses are used in two cases: different bindings to same endpoint, or backup endpoints. In the former, the receiver of the message has the choice of which address to use (depending on which binding is preferable.) In the case where multiple addresses are used for redundancy, a priority attribute can be specified to help the receiver choose among the addresses. The priority is used as a hint and doesn't enforce any behaviour in the receiver of the message. Default priority is a value of 1.
@@@ does the group agree with this previous paragraph? if so, then we need to alllow for multiple addresses in the schema. That's going to get a little confusing when multiple addresses are already allowed by the abstract message set.
Qualifier type is element name in a namespace.
Example:
<auth:username xmlns:auth="http://www.example.com/ns/auth" xmlns:btp="http://www.oasis-open.org/2001/BTP" btp:must-be-understood="yes" btp:to-be-propagated="yes">jtauber</auth:username>
Attributes must-be-understood and to-be-propogated are optional
Unspecified length strings made of up hexadecimal digits (0->9, A->F). Note: lower case a->f are not valid.
Examples: "01", "FAB224234CCCC2"
<btp:context id?>
<btp:target-address>
...address...
</btp:target-address>
<btp:superior-address> +
...address...
</btp:superior-address>
<btp:superior-identifier>...hexstring...</btp:superior-identifier>
<btp:time-limit>...XML schema duration...</btp:time-limit>
<superior-type>...superior-type URI...</superior-type>
<btp:qualifiers> ?
<foo:some-qualifier ...>...</foo:some-qualifier>
<bar:another-qualifier ...>...</bar:another-qualifier>
</btp:qualifiers>
</btp:context>
Using the W3C XML Schema duration datatype for time-limit
@@@ Didn't we decide to make times relative? The CONTEXT section of the spec (although more clear with BEGIN) doesn't expressly say 'absolute' or 'relative', and kind of leans towards the absolute case: "timelimit an Inferior that has not sent PREPARED or received PREPARE by this time should initiate cancellation."
Taken from the W3C XML Schema Part 2: Datatypes specification: "The lexical representation for duration is the ISO 8601 extended format PnYn MnDTnH nMnS, where nY represents the number of years, nM the number of months, nD the number of days, 'T' is the date/time separator, nH the number of hours, nM the number of minutes and nS the number of seconds. The number of seconds can include decimal digits to arbitrary precision."
For example, to indicate 1 hour and 30 minutes, one would write "PT1H30M". Where 'P' is always present and 'T', the date/time seperator, is present if the duration denotes hours, minutes or seconds.
@@@ is it overkill to make superior-type a URI? hardcode the two element values? make it an attribute?
Superior Type URIs:
<btp:begin id?>
<btp:target-address>
...address...
</btp:target-address>
<btp:reply-address>
...address...
</btp:reply-address>
<superior-type>...superior-type URI...</superior-type>
<btp:time-limit>...XML schema duration...</btp:time-limit>
<btp:qualifiers> ?
<foo:some-qualifier ...>...</foo:some-qualifier>
<bar:another-qualifier ...>...</bar:another-qualifier>
</btp:qualifiers>
</btp:begin>
See CONTEXT message for allowed superior type URIs and for description of time-limit.
<btp:begun id?> <btp:target-address> ...address... </btp:target-address> <btp:inferior-address> + ...address... </btp:inferior-address> <btp:qualifiers> ? <foo:some-qualifier ...>...</foo:some-qualifier> <bar:another-qualifier ...>...</bar:another-qualifier> </btp:qualifiers> </btp:begun>
<btp:enrol reply-requested="true|false" id?> <btp:target-address> ...address... </btp:target-address> <btp:superior-identifier>...hexstring...</btp:superior-identifier> <btp:reply-address> ...address... </btp:reply-address> <btp:inferior-address> + ...address... </btp:inferior-address> <btp:inferior-identifier>...hexstring...</btp:inferior-identifier> <btp:qualifiers> ? <foo:some-qualifier ...>...</foo:some-qualifier> <bar:another-qualifier ...>...</bar:another-qualifier> </btp:qualifiers> </btp:enrol>
<btp:enrolled id?> <btp:target-address> ...address... </btp:target-address> <btp:inferior-identifier>...hexstring...</btp:inferior-identifier> <btp:qualifiers> ? <foo:some-qualifier ...>...</foo:some-qualifier> <bar:another-qualifier ...>...</bar:another-qualifier> </btp:qualifiers> </btp:enrolled>
<btp:resign response-requested="true|false" id?> <btp:target-address> ...address... </btp:target-address> <btp:superior-identifier>...hexstring...</btp:superior-identifier> <btp:inferior-address> + ...address... </btp:inferior-address> <btp:inferior-identifier>...hexstring...</btp:inferior-identifier> <btp:qualifiers> ? <foo:some-qualifier ...>...</foo:some-qualifier> <bar:another-qualifier ...>...</bar:another-qualifier> </btp:qualifiers> </btp:resign>
<btp:resigned id?> <btp:target-address> ...address... </btp:target-address> <btp:inferior-identifier>...hexstring...</btp:inferior-identifier> <btp:qualifiers> ? <foo:some-qualifier ...>...</foo:some-qualifier> <bar:another-qualifier ...>...</bar:another-qualifier> </btp:qualifiers> </btp:resigned>
<btp:prepare id?> <btp:target-address> ...address... </btp:target-address> <btp:inferior-identifier>...hexstring...</btp:inferior-identifier> <btp:qualifiers> ? <foo:some-qualifier ...>...</foo:some-qualifier> <bar:another-qualifier ...>...</bar:another-qualifier> </btp:qualifiers> </btp:prepare>
<btp:prepared default-is-cancel="false|true" id?> <btp:target-address> ...address... </btp:target-address> <btp:superior-identifier>...hexstring...</btp:superior-identifier> <btp:inferior-address> ...address... </btp:inferior-address> <btp:inferior-identifier>...hexstring...</btp:inferior-identifier> <btp:qualifiers> ? <foo:some-qualifier ...>...</foo:some-qualifier> <bar:another-qualifier ...>...</bar:another-qualifier> </btp:qualifiers> </btp:prepared>
<btp:confirm id?> <btp:target-address> ...address... </btp:target-address> <btp:inferior-identifier>...hexstring...</btp:inferior-identifier> <btp:qualifiers> ? <foo:some-qualifier ...>...</foo:some-qualifier> <bar:another-qualifier ...>...</bar:another-qualifier> </btp:qualifiers> </btp:confirm>
<btp:confirmed confirmed-received="true|false" id?> <btp:target-address> ...address... </btp:target-address> <btp:superior-identifier>...hexstring...</btp:superior-identifier> <btp:inferior-address> ...address... </btp:inferior-address> <btp:inferior-identifier>...hexstring...</btp:inferior-identifier> <btp:qualifiers> ? <foo:some-qualifier ...>...</foo:some-qualifier> <bar:another-qualifier ...>...</bar:another-qualifier> </btp:qualifiers> </btp:confirmed>
<btp:cancel id?> <btp:target-address> ...address... </btp:target-address> <btp:inferior-identifier>...hexstring...</btp:inferior-identifier> <btp:qualifiers> ? <foo:some-qualifier ...>...</foo:some-qualifier> <bar:another-qualifier ...>...</bar:another-qualifier> </btp:qualifiers> </btp:cancel>
<btp:cancelled id?> <btp:target-address> ...address... </btp:target-address> <btp:superior-identifier>...hexstring...</btp:superior-identifier> <btp:inferior-address> ...address... </btp:inferior-address> <btp:inferior-identifier>...hexstring...</btp:inferior-identifier> <btp:qualifiers> ? <foo:some-qualifier ...>...</foo:some-qualifier> <bar:another-qualifier ...>...</bar:another-qualifier> </btp:qualifiers> </btp:cancelled>
<btp:mixed id?> <btp:target-address> ...address... </btp:target-address> <btp:superior-identifier>...hexstring...</btp:superior-identifier> <btp:inferior-address> ...address... </btp:inferior-address> <btp:inferior-identifier>...hexstring...</btp:inferior-identifier> <btp:qualifiers> ? <foo:some-qualifier ...>...</foo:some-qualifier> <bar:another-qualifier ...>...</bar:another-qualifier> </btp:qualifiers> </btp:mixed>
<btp:contradiction id?> <btp:target-address> ...address... </btp:target-address> <btp:inferior-identifier>...hexstring...</btp:inferior-identifier> <btp:qualifiers> ? <foo:some-qualifier ...>...</foo:some-qualifier> <bar:another-qualifier ...>...</bar:another-qualifier> </btp:qualifiers> </btp:contradiction>
<btp:superior-state reply-requested="true|false" id?> <btp:target-address> ...address... </btp:target-address> <btp:inferior-identifier>...hexstring...</btp:inferior-identifier> <btp:status>...status URI...</btp:status> <btp:qualifiers> ? <foo:some-qualifier ...>...</foo:some-qualifier> <bar:another-qualifier ...>...</bar:another-qualifier> </btp:qualifiers> </btp:superior-state>
See abstract message set for list of valid status states and consult the Status URI section below for the URIs.
<btp:inferior-state reply-requested="true|false" id?> <btp:target-address> ...address... </btp:target-address> <btp:superior-identifier>...hexstring...</btp:superior-identifier> <btp:inferior-address> ...address... </btp:inferior-address> <btp:inferior-identifier>...hexstring...</btp:inferior-identifier> <btp:status>...status URI...</btp:status> <btp:qualifiers> ? <foo:some-qualifier ...>...</foo:some-qualifier> <bar:another-qualifier ...>...</bar:another-qualifier> </btp:qualifiers> </btp:inferior-state>
See abstract message set for list of valid status states and consult the Status URI section below for the URIs.
<btp:request-confirm id?> <btp:target-address> ...address... </btp:target-address> <btp:reply-address> ...address... </btp:reply-address> <btp:atom-identifier>...hexstring...</btp:atom-identifier> <btp:qualifiers> ? <foo:some-qualifier ...>...</foo:some-qualifier> <bar:another-qualifier ...>...</bar:another-qualifier> </btp:qualifiers> </btp:request-confirm>
<btp:request-status id?> <btp:target-address> ...address... </btp:target-address> <btp:reply-address> ...address... </btp:reply-address> <btp:inferior-identifier>...hexstring...</btp:inferior-identifier> <btp:qualifiers> ? <foo:some-qualifier ...>...</foo:some-qualifier> <bar:another-qualifier ...>...</bar:another-qualifier> </btp:qualifiers> </btp:request-status>
<btp:status id?> <btp:target-address> ...address... </btp:target-address> <btp:inferior-address> ...address... </btp:inferior-address> <btp:inferior-identifier>...hexstring...</btp:inferior-identifier> <btp:current-status>...status URI...</btp:current-status> <btp:qualifiers> ? <foo:some-qualifier ...>...</foo:some-qualifier> <bar:another-qualifier ...>...</bar:another-qualifier> </btp:qualifiers> </btp:status>
Status URIs:
@@@ Is 'readyreceived' a separate status? it is mentioned in superior-state
<btp:redirect id?> <btp:target-address> ...address... </btp:target-address> <btp:superior-identifier>...hexstring...</btp:superior-identifier> <btp:inferior-identifier>...hexstring...</btp:inferior-identifier> <btp:old-address> + ...address... </btp:old-address> <btp:new-address> + ...address... </btp:new-address> <btp:qualifiers> ? <foo:some-qualifier ...>...</foo:some-qualifier> <bar:another-qualifier ...>...</bar:another-qualifier> </btp:qualifiers> </btp:redirect>
<btp:fault id?> <btp:target-address> ...address... </btp:target-address> <btp:superior-identifier>...hexstring...</btp:superior-identifier> <btp:inferior-identifier>...hexstring...</btp:inferior-identifier> <btp:fault-type>...fault type URI...</btp:fault-type> <btp:fault-data>...fault data...</btp:fault-data> <btp:qualifiers> ? <foo:some-qualifier ...>...</foo:some-qualifier> <bar:another-qualifier ...>...</bar:another-qualifier> </btp:qualifiers> </btp:fault>
Fault Type URIs:
Fault data can take on various forms:
<btp:fault-data>...string data...</btp:fault-data>
<btp:fault-data>...hexstring...</btp:fault-data>
<btp:fault-data>
<btp:inferior-address>
...address...
</btp:inferior-address>
<btp:inferior-identifier>...hexstring...</btp:inferior-identifier>
</btp:fault-data>
Each BTP message has an optional id attribute to give it a unique identifier. An application can make use of those identifiers, but no processing is enforced.
The BTP boxcaring mechanism describes an XML packaging syntax that has two uses:
The "btp:messages" element is introduced to bundle various messages together. For example:
<btp:messages>
<btp:enrol>...</btp:enrol>
<btp:prepared>...</btp:prepared>
</btp:messages>
Relating BTP messages to one another is achived through containment. For example:
<btp:begun>
<btp:context>...<btp:context>
</btp:begun>
@@@ did we have a final decision about doing relationships by containment?
<btp:messages> can be used within a SOAP Body, inside application data or independently of either.
This binding maps BTP messages to the SOAP 1.1 specification.
When a BTP protocol actor-in-role is transmitting to a BTP protocol actor-in-role, BTP messages are contained inside the SOAP:Body (ex: an Enroller sending an ENROL message to a Coordinator.) However, when BTP messages are related to an application message, then the application message will be contained in the SOAP:Body, and the BTP message will travel in the SOAP:Header (ex: Initator sending a application request with a CONTEXT to a service.) BTP messages contained in either the SOAP:Header or SOAP:Body are wrapped in a <btp:messages> element. This wrapping occurs even if only one BTP message is to be transmitted. This wrapping is used to assist SOAP processors to pass on BTP related messages to a BTP processor.
The SOAP BTP binding does not make use of SOAPAction HTTP header, actor attribute or mustUnderstand attribute. The SOAPAction HTTP header is left to be application specific, as an already existing web service that is being upgraded to use BTP might have already made use of SOAPAction. At the time of writing, most SOAP implementations haven't implemented actor or mustUnderstand. More importantly, mustUnderstand might cause confusion for a server about whether to process a SOAP message in a BTP transactional manner. Take the following example, a client sends an application request in a SOAP:Body with a BTP CONTEXT in the SOAP:Header. There would be a problem if the client were to add a mustUnderstand=true to the BTP message, but the server didn't want to process in a transactional manner.
BTP messages conform to the rules of the Section 5 (of the SOAP 1.1 specification) SOAP Encoding as specified by the following URI: "http://schemas.xmlsoap.org/soap/encoding/".
@@@ can anybody prove that we don't conform to the soap encoding rules? I'm a little concerned about the addresses not mapping to SOAP arrays.
@@@ faults: relationship between soap faults and btp faults
The client application running on client.example.com implements the following roles: initiator, terminator, factory, and coordinator.
The service running on services.example.com implements the following roles: service, enroller, and participant. At this point, assume that the initiator has sent a BEGIN to a Factory, a Coordinator has been created and a CONTEXT returned to the Initiator.
The example below shows an application request with CONTEXT message sent from client.example.com (Intiator) to services.example.com (Service)
<soap:Envelope
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
soap-env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<soap:Header>
<btp:messages xmlns:btp="urn:oasis:names:tc:BTP:xml">
<btp:context type="atomic">
<btp:target-address>
<btp:binding>urn:oasis:names:tc:BTP:binding:soap-http</btp:binding>
<btp:binding-address>http://services.example.com/soaphandler</btp:binding-address>
</btp:target-address>
<btp:superior-address>
<btp:binding>urn:oasis:names:tc:BTP:binding:soap-http</btp:binding>
<btp:binding-address>http://client.example.com/soaphandler</btp:binding-address>
</btp:superior-address>
<btp:superior-identifier>1001</btp:superior-identifier>
<superior-type>urn:oasis:names:tc:BTP:superior-type:atom</superior-type>
<btp:time-limit>PT30M</btp:time-limit>
</btp:context>
</btp:messages>
</soap:Header>
<soap:Body>
<ns1:orderGoods xmlns:ns1="http://example.com/2001/Services/xyzgoods">
<custID>ABC8329045</custID>
<itemID>224352</itemID>
<quantity>5</quantity>
</ns1:orderGoods>
</soap:Body>
</soap:Envelope>
The example below shows an ENROL message sent from services.example.com (Enroller) to client.example.com (Coordinator)
<soap:Envelope
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
soap-env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<soap:Header>
</soap:Header>
<soap:Body>
<btp:messages xmlns:btp="urn:oasis:names:tc:BTP:xml">
<btp:enrol reply-requested="true">
<btp:target-address>
<btp:binding>urn:oasis:names:tc:BTP:binding:soap-http</btp:binding>
<btp:binding-address>http://client.example.com/soaphandler</btp:binding-address>
</btp:target-address>
<btp:superior-identifier>1001</btp:superior-identifier>
<btp:reply-address>
<btp:binding>urn:oasis:names:tc:BTP:binding:soap-http</btp:binding>
<btp:binding-address>http://services.example.com/soaphandler</btp:binding-address>
</btp:reply-address>
<btp:inferior-address>
<btp:binding>urn:oasis:names:tc:BTP:binding:soap-http</btp:binding>
<btp:binding-address>http://services.example.com/soaphandler</btp:binding-address>
</btp:inferior-address>
<btp:inferior-identifier>AAAB</btp:inferior-identifier>
</btp:enrol>
</btp:messages>
</soap:Body>
</soap:Envelope>
@@@ show an example that uses containment
@@@ show an example of an application message that contains a btp message
This binding maps BTP messages to the SOAP Messages with Attachments specification.
This binding is a superset of the SOAP Binding. In addition to the SOAP Envelope, MIME packaging is introduce to optionally carry BTP messages or application specific data. Using the href attribute for linking, any entity sending a message can decide how to split up a message among the MIME multipart/related parts.
MIME-Version: 1.0
Content-Type: Multipart/Related; boundary=MIME_boundary; type=text/xml;
start="someID"
--MIME_boundary
Content-Type: text/xml; charset=UTF-8
Content-ID: someID
<?xml version='1.0' ?>
<soap:Envelope
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
soap-env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<soap:Header>
<btp:messages xmlns:btp="urn:oasis:names:tc:BTP:xml">
<btp:context type="atomic">
<btp:target-address>
<btp:binding>urn:oasis:names:tc:BTP:binding:soap-http</btp:binding>
<btp:binding-address>http://services.example.com/soaphandler</btp:binding-address>
</btp:target-address>
<btp:superior-address>
<btp:binding>urn:oasis:names:tc:BTP:binding:soap-http</btp:binding>
<btp:binding-address>http://client.example.com/soaphandler</btp:binding-address>
</btp:superior-address>
<btp:superior-identifier>1001</btp:superior-identifier>
<superior-type>urn:oasis:names:tc:BTP:superior-type:atom</superior-type>
<btp:time-limit>PT30M</btp:time-limit>
</btp:context>
</btp:messages>
</soap:Header>
<soap:Body>
<orderGoods href="cid:anotherID"/>
</soap:Body>
</soap:Envelope>
--MIME_boundary
Content-Type: text/xml
Content-ID: anotherID
<ns1:orderGoods xmlns:ns1="http://example.com/2001/Services/xyzgoods">
<custID>ABC8329045</custID>
<itemID>224352</itemID>
<quantity>5</quantity>
</ns1:orderGoods>
--MIME_boundary--
@@@ concern raised by Mark Hale: "We need to more carefully consider the way the compounding (one-wire, batching, etc.) is done. BTP is intended to be carried along with application data; conveivably data with each BTP message. If we use the structure as above, we cannot sort out the application messages (within the SOAP body or as a MIME part) that go with the corresponding BTP messages. To get around this, we would impose requirements on the way application data is assembled into the messsages."
@@@ add btp:messages element
@@@ reflect the message containment hierarchy in the schema
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Powered by eList eXpress LLC