business-transaction message

Subject: [Fwd: BTP Messaging spec draft]

From: Alastair Green <alastair.green@choreology.com>
To: OASIS BT TC <business-transaction@lists.oasis-open.org>
Date: Mon, 23 Jul 2001 16:08:31 +0100

Won't get this incorporated at the rate I'm going, at least before
tomorrow, so here it is as a freestanding piece. Thanks Alex.

Alastair

From: Alex Ceponkus <aceponkus@bowstreet.com>
To: "Alastair Green (E-mail)" <alastair.green@choreology.com>
Date: Fri, 20 Jul 2001 13:23:34 -0400

Alastair,

Here is the latest btp messaging draft.  It is split up into two separate
documents, however the goal is to merge them together in the near future.
Also, some sections are just placeholders at this time (like boxcaring and
soap binding), which will be filled in for next week.

Alex

Title: BTP Messaging

@@@ ed: which section numbers should we apply to this doc?

@@@ ed: need stylesheet .. especially for indentation

BTP Messaging

Working draft - July 19, 2001

Editors:

James Tauber
Alex Ceponkus

@@@ Introductory paragraph.

@@@ A note about bindings.

This document contains the following

BTP Messages
Message References
Boxcaring
SOAP Binding
Appendix: BTP Messages Schema

BTP Messages

@@@ introductory paragraph

Addressing

corresponds to section 4.1 of Abstract message set specification

Examples:

	<some-address>
		<binding>btp:btp-soapbinding-v1</binding>
	    <binding-address>carrier specific URI</binding-address>
	    <additional-information>...optional additional addressing
	information...</additional-information>
	</some-address>

	<some-address>
	
	<binding-address>http://www.example.com/Servlet/BTP/dispatch?coordinator=123
	45</binding-address>
	</some-address>

In the above address, the URI in carrier-address is sufficient to route the message.

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.

Qualifiers

corresponds to section 4.3 of Abstract message set specification

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

Identifiers

@@@ explain hexstring

Messages

CONTEXT

corresponds to section 4.4.1 of Abstract message set specification


	- target address
		address
	- superior address
		address
	- superior identifier
		identifier
	- time limit
		time (XML schema dateTime)
	- qualifiers
		list of qualifiers
	
	<btp:context type="cohesive|atomic">
	  <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 dateTime...</btp:time-limit>
	  <btp:qualifiers>
	    <foo:some-qualifier ...>...</foo:some-qualifier>
	    <bar:another-qualifier ...>...</bar:another-qualifier>
	  </btp:qualifiers>
	</btp:context>
	
	dateTime:
	
	http://www.w3.org/TR/xmlschema-2/#dateTime
	"For example, to indicate 1:20 pm on May the 31st, 1999 for Eastern Standard
	Time which is 5 hours behind Coordinated Universal Time (UTC), one would
	write: 1999-05-31T13:20:00-05:00"
	
	-->  time is to be expressed as relative

BEGIN

corresponds to section 4.4.2 of Abstract message set specification

	- target address
		address
	- reply address
		address
	- time limit
		time (XML schema dateTime)
	- qualifiers
		list of qualifiers
	
	
	<btp:begin>
	  <btp:target-address>
	    ...address...
	  </btp:target-address>
	  <btp:reply-address>
	    ...address...
	  </btp:reply-address>
	  <btp:time-limit>...XML schema dateTime...</btp:time-limit>
	  <btp:qualifiers>
	    <foo:some-qualifier ...>...</foo:some-qualifier>
	    <bar:another-qualifier ...>...</bar:another-qualifier>
	  </btp:qualifiers>
	</btp:begin>

BEGUN

corresponds to section 4.4.3 of Abstract message set specification

	
	
	- target address
		address
	- coordinator-access address
		address
	- superior address
		address
	- superior identifier
		identifier
	- time limit
		time (XML schema dateTime)
	- qualifiers
		list of qualifiers
		
	
	<btp:begun>
	  <btp:target-address>
	    ...address...
	  </btp:target-address>
	  <btp:coordinator-access-address>
	    ...address...
	  </btp:coordinator-access-address>
	  <btp:superior-address>
	    ...address...
	  </btp:superior-address>
	  <btp:superior-identifier>...hexstring...</btp:superior-identifier>
	  <btp:time-limit>...XML schema dateTime...</btp:time-limit>
	  <btp:qualifiers>
	    <foo:some-qualifier ...>...</foo:some-qualifier>
	    <bar:another-qualifier ...>...</bar:another-qualifier>
	  </btp:qualifiers>
	</btp:begun>

GET_CONTEXT

corresponds to section 4.4.4 of Abstract message set specification


	- target address
		address
	- reply address
		address
	- superior identifier
		identifier
	- qualifiers
		list of qualifiers
	
	
	<btp:get-context>
	  <btp:target-address>
	    ...address...
	  </btp:target-address>
	  <btp:reply-address>
	    ...address...
	  </btp:reply-address>
	  <btp:superior-identifier>...hexstring...</btp:superior-identifier>
	  <btp:qualifiers>
	    <foo:some-qualifier ...>...</foo:some-qualifier>
	    <bar:another-qualifier ...>...</bar:another-qualifier>
	  </btp:qualifiers>
	</btp:get-context>

ENROLL

corresponds to section 4.4.5 of Abstract message set specification


	- target address
		address
	- superior identifier
		identifier
	- reply address
		address
	- inferior address
		address
	- inferior identifier
		identifier
	- qualifiers
		list of qualifiers
	
	<btp:enroll>
	  <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:enroll>

ENROLLED

corresponds to section 4.4.6 of Abstract message set specification

	
	- target address
		address
	- inferior identifier
		identifier
	- qualifiers
		list of qualifiers
	
	<btp:enrolled>
	  <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>

RESIGN

corresponds to section 4.4.7 of Abstract message set specification


	- target address
		address
	- superior identifier
		identifier
	- inferior address
		address
	- inferior identifier
		identifier
	- response requested 
		true or false
	- qualifiers
		list of qualifiers
	
	
	<btp:resign response-requested="true|false">
	  <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>

RESIGNED

corresponds to section 4.4.8 of Abstract message set specification


	- target address
		address
	- inferior identifier
		identifier
	- qualifiers
		list of qualifiers
	
	
	<btp:resigned>
	  <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>

PREPARE

corresponds to section 4.4.9 of Abstract message set specification

	- target address
		address
	- inferior identifier
		identifier
	- qualifiers
		list of qualifiers
	
	
	<btp:prepare>
	  <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>

READY

corresponds to section 4.4.10 of Abstract message set specification


	- target address
		address
	- superior identifier
		identifier
	- inferior address
		address
	- inferior identifier
		identifier
	- ready
		false (default) or true
	- qualifiers
		list of qualifiers
	
	<btp:ready value="false|true">
	  <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:ready>

CONFIRM

corresponds to section 4.4.11 of Abstract message set specification


	- target address
		address
	- inferior identifier
		identifier
	- qualifiers
		list of qualifiers
	
	
	<btp:confirm>
	  <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>

CONFIRMED

corresponds to section 4.4.12 of Abstract message set specification


	- target address
		address
	- superior identifier
		identifier
	- inferior address
		address
	- inferior identifier
		identifier
	- confirmed received
		boolean (true/false)
	- qualifiers
		list of qualifiers
	
	
	<btp:confirmed confirmed-received="true|false">
	  <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>

CANCEL

corresponds to section 4.4.13 of Abstract message set specification

	

	- target address
		address
	- inferior identifier
		identifier
	- qualifiers
		list of qualifiers
		
	<btp:cancel>
	  <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>

CANCELLED

corresponds to section 4.4.14 of Abstract message set specification

	
	- target address
		address
	- superior identifier
		identifier
	- inferior address
		address
	- inferior identifier
		identifier
	- qualifiers
		list of qualifiers
	
	
	<btp:cancelled>
	  <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>

CONTRADICTION

corresponds to section 4.4.15 of Abstract message set specification


	- target address
		address
	- inferior identifier
		identifier
	- qualifiers
		list of qualifiers
	
	<btp:contradiction>
	  <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>

SUPERIOR_STATUS

corresponds to section 4.4.16 of Abstract message set specification


	- target address
		address
	- inferior identifier
		identifier
	- status
		status URI  (ex: http://oasis-open.org/2001/BTP/status/Active)
		Valid status: active, preparing, youareready, unknown, inaccessible (see: Status URIs section)
	- reply
		true or false
	- qualifiers
		list of qualifiers
	
	
	<btp:superior-status reply="true|false">
	  <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-status>

INFERIOR_STATUS

corresponds to section 4.4.17 of Abstract message set specification

	- target address
		address
	- superior identifier
		identifier
	- inferior address
		address
	- inferior identifier
		identifier
	- status
		status URI  (ex: http://oasis-open.org/2001/BTP/status/Active)
		Valid status: active, unknown, inaccessible (see: Status URIs section)
	- reply
		true or false
	- qualifiers
		list of qualifiers
	
	<btp:inferior-status reply="true|false">
	  <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-status>

REDIRECT

corresponds to section 4.4.18 of Abstract message set specification

	- target address
		address
	- superior identifier
		identifier
	- inferior identifier
		identifier
	- old address
		address
	- new address
		address
	- qualifiers
		list of qualifiers
	
	
	<btp:redirect>
	  <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>

FAULT

corresponds to section 4.4.19 of Abstract message set specification

	- target address
		address
	- superior identifier
		identifier
	- inferior identifier
		identifier
	- fault type
		fault type URI  (ex: http://oasis-open.org/2001/BTP/faults/General)
	- fault data
		string data
	- qualifiers
		list of qualifiers
	

	<btp:fault>
	  <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>...string data...</btp:fault-data>
	  <btp:qualifiers>
	    <foo:some-qualifier ...>...</foo:some-qualifier>
	    <bar:another-qualifier ...>...</bar:another-qualifier>
	  </btp:qualifiers>
	</btp:fault>

REQUEST-STATUS

	- target address
		address
	- inferior identifier
		identifier
	- reply address
		address
	- qualifiers
		list of qualifiers
	

	<btp:request-status>
	  <btp:target-address>
	    ...address...
	  </btp:target-address>
	  <btp:inferior-identifier>...hexstring...</btp:inferior-identifier>
	  <btp:reply-address>
	    ...address...
	  </btp:reply-address>
	  <btp:qualifiers>
	    <foo:some-qualifier ...>...</foo:some-qualifier>
	    <bar:another-qualifier ...>...</bar:another-qualifier>
	  </btp:qualifiers>
	</btp:request-status>

STATUS

	- target address
		address
	- inferior address
		address
	- inferior identifier
		identifier
	- current status
		- status URI
	- qualifiers
		list of qualifiers
	

	<btp:status>
	  <btp:target-address>
	    ...address...
	  </btp:target-address>
	  <btp:inferior-address>
	    ...address...
	  </btp:inferior-address>
	  <btp:inferior-identifier>...hexstring...</btp:inferior-identifier>
	  <btp:current-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:

Active: "http://oasis-open.org/2001/BTP/Status/Activ"e
Cancel-contradiction: "http://oasis-open.org/2001/BTP/Status/Cancel-contradiction"
Cancelled: "http://oasis-open.org/2001/BTP/Status/Cancelled"
Cancelling: "http://oasis-open.org/2001/BTP/Status/Cancelling"
Confirm-contradiction: "http://oasis-open.org/2001/BTP/Status/Confirm-contradiction"
Confirmed: "http://oasis-open.org/2001/BTP/Status/Confirmed"
Confirming: "http://oasis-open.org/2001/BTP/Status/Confirming"
Enrolling: "http://oasis-open.org/2001/BTP/Status/Enrolling"
Inaccessible: "http://oasis-open.org/2001/BTP/Status/Inaccessible"
Preparing: "http://oasis-open.org/2001/BTP/Status/Preparing"
Ready: "http://oasis-open.org/2001/BTP/Status/Ready"
Resigning: "http://oasis-open.org/2001/BTP/Status/Resigning"
Unknown: "http://oasis-open.org/2001/BTP/Status/Unknown"
Youareready: "http://oasis-open.org/2001/BTP/Status/Youareready"

MIXED

	
	- target address
		address
	- superior identifier
		identifier
	- inferior address
		address
	- inferior identifier
		identifier
	- qualifiers
		list of qualifiers
	
	
	<btp:mixed>
	  <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>

REQUEST-CONFIRM

	
	- target address
		address
	- inferior identifier
		identifier
	- reply address
		address
	- qualifiers
		list of qualifiers
	
	
	<btp:request-confirm>
	  <btp:target-address>
	    ...address...
	  </btp:target-address>
	  <btp:inferior-identifier>...hexstring...</btp:inferior-identifier>
	  <btp:reply-address>
	    ...address...
	  </btp:reply-address>
	  <btp:qualifiers>
	    <foo:some-qualifier ...>...</foo:some-qualifier>
	    <bar:another-qualifier ...>...</bar:another-qualifier>
	  </btp:qualifiers>
	</btp:request-confirm>

Message References

Each BTP message can have an id attribute to give it a unique identifier. An application can make use of those identifiers, but no processing is enforced.

BTP Boxcaring

The BTP boxcaring mechanism is a XML packaging syntax that has two uses:

bundling several BTP messages together
used as an XML transport in the absense of another XML transport (such as SOAP)

@@@ describe <btp:bundle> and <btp:relationship> @@@ think of better name than bundle (package?, payload?)

@@@ bundles destined for different hops on messages path

@@@ show how bundles work independently of xml transport

@@@ application data can have bundles and vice versa

Nested bundles

@@@ not done

SOAP Binding

@@@ btp:bundles go into the soap:Header

Appendix: BTP Messages Schema

@@@ add boxcaring elements

schema_html.zip