Choreography Tutorial
In this tutorial we will walk through an illustrative use of the choreography engine using a basic example. If you havn't got a local WSMX instance, get started now.
Open the web console and navigate to the component view of RadexChoreography. Optionally you may ssh into your WSMX instance and type 'll' (LogListen) to remotely view the log4j logs. While this not necessary to complete this tutorial, it is recommended for didactic purposes as it shows the workings of the machinery that is inside WSMX.
In the webconsole find the operation with the signature
updateState(String, String)
It is used to inject instances into the state of the running ASM. which is the model representation of message exchange. The first parameter is either '<' or '>' and identifies the direction of the message flow.
Try invoking the operation with one of the directions and note that the engine skips two machine updates. One for the provider choreography and one for the requester choreography, because we don't have any registered. In this tutorial we will only register one choreography, the engine will skip the one we do not register during the update.
Our domain is transportation and we'd like to request information about train schedules. The services description could look like this (simplified):
<html>
<div style="background:black; color:white">
<font color="#00ff00"><b>wsmlVariant</b></font> <font color="#8080ff"><b>_"http://www.wsmo.org/wsml/wsml-syntax/wsml-rule"</b></font>
<font color="#00ff00"><b>namespace</b></font> <font color="#ffff00"><b>{</b></font> <font color="#8080ff"><b>_"http://deri.org/iswc2005tutorial/services/GetTimetable#"</b></font>,
t1 <font color="#8080ff"><b>_"http://deri.org/iswc2005tutorial/services/GetTimetable/travel1#"</b></font>,
dc <font color="#8080ff"><b>_"http://purl.org/dc/elements/1.1#"</b></font>,
wsml <font color="#8080ff"><b>_"http://www.wsmo.org/wsml/wsml-syntax#"</b></font> <font color="#ffff00"><b>}</b></font>
<font color="#00ff00"><b>ontology</b></font> travel1
<font color="#00ff00"><b>concept</b></font> <font color="#8080ff"><b>t1#traintimeReq</b></font>
<font color="#8080ff"><b>t1#type</b></font> <font color="#ffff00"><b>ofType</b></font><font color="#ff6060"><b> _string</b></font>
<font color="#00ff00"><b>concept</b></font> <font color="#8080ff"><b>t1#traintimeResp</b></font>
<font color="#8080ff"><b>t1#type</b></font> <font color="#ffff00"><b>ofType</b></font><font color="#ff6060"><b> _string</b></font>
<font color="#00ff00"><b>concept</b></font> <font color="#8080ff"><b>t1#detailedTraintimeResp</b></font>
<font color="#8080ff"><b>t1#type</b></font> <font color="#ffff00"><b>ofType</b></font><font color="#ff6060"><b> _string</b></font>
<font color="#00ff00"><b>webService</b></font> GetTimetable
<font color="#00ff00"><b>nonFunctionalProperties</b></font>
<font color="#8080ff"><b>dc#type</b></font> <font color="#ffff00"><b>hasValue</b></font> <font color="#8080ff"><b>_"http://www.wsmo.org/TR/d2/v1.2/#services"</b></font>
<font color="#8080ff"><b>dc#title</b></font> <font color="#ffff00"><b>hasValue</b></font> <font color="#ff40ff"><b>"get a train timetable"</b></font>
<font color="#8080ff"><b>wsml#version</b></font> <font color="#ffff00"><b>hasValue</b></font> <font color="#ff40ff"><b>"$Revision: 1.9 $"</b></font>
<font color="#00ff00"><b>endNonFunctionalProperties</b></font>
<font color="#00ff00"><b>importsOntology</b></font>
<font color="#8080ff"><b>_"http://deri.org/iswc2005tutorial/ontologies/travel1"</b></font>
<font color="#00ff00"><b>capability</b></font> timetableCapability
<font color="#00ff00"><b>precondition</b></font>
<font color="#00ff00"><b>nonFunctionalProperties</b></font>
<font color="#8080ff"><b>dc#description</b></font> <font color="#ffff00"><b>hasValue</b></font> <font color="#ff40ff"><b>"The input has to be the departure city, ^M</b></font>
<font color="#ff40ff"><b> the arrival city and the date on whcih the customer wishes to travel."</b></font>
<font color="#00ff00"><b>endNonFunctionalProperties</b></font>
<font color="#00ff00"><b>definedBy</b></font>
<font color="#8080ff"><b>?timeTable</b></font> <font color="#ffff00"><b>memberOf</b></font> <font color="#8080ff"><b>t1#trainTimeTable</b></font>
<font color="#ffff00"><b>and</b></font> <font color="#8080ff"><b>?timeTable</b></font><font color="#ffff00"><b>[</b></font>departure_city <font color="#ffff00"><b>hasValue</b></font> <font color="#8080ff"><b>_#</b></font><font color="#ffff00"><b>]</b></font>
<font color="#ffff00"><b>and</b></font> <font color="#8080ff"><b>?timeTable</b></font><font color="#ffff00"><b>[</b></font>arrival_city <font color="#ffff00"><b>hasValue</b></font> <font color="#8080ff"><b>_#</b></font><font color="#ffff00"><b>]</b></font>
<font color="#ffff00"><b>and</b></font> <font color="#8080ff"><b>?timeTable</b></font><font color="#ffff00"><b>[</b></font>travel_date <font color="#ffff00"><b>hasValue</b></font> <font color="#8080ff"><b>_#</b></font><font color="#ffff00"><b>]</b></font>.
<font color="#00ff00"><b>postcondition</b></font>
<font color="#00ff00"><b>definedBy</b></font>
<font color="#8080ff"><b>?timetable</b></font> <font color="#ffff00"><b>memberOf</b></font> trainTimeTable
<font color="#ffff00"><b>and</b></font> <font color="#8080ff"><b>?timeTable</b></font><font color="#ffff00"><b>[</b></font>train_number <font color="#ffff00"><b>hasValue</b></font> <font color="#8080ff"><b>_#</b></font><font color="#ffff00"><b>]</b></font>
<font color="#ffff00"><b>and</b></font> <font color="#8080ff"><b>?timeTable</b></font><font color="#ffff00"><b>[</b></font>departure_time <font color="#ffff00"><b>hasValue</b></font> <font color="#8080ff"><b>_#</b></font><font color="#ffff00"><b>]</b></font>.
<font color="#00ff00"><b>interface</b></font> timetableInterface
<font color="#00ff00"><b>choreography</b></font> chor
<font color="#00ff00"><b>stateSignature</b></font> sig
<font color="#00ff00"><b>importsOntology</b></font> <font color="#ffff00"><b>{</b></font>
<font color="#8080ff"><b>_"http://deri.org/iswc2005tutorial/services/GetTimetable#travel1"</b></font>
<font color="#ffff00"><b>}</b></font>
<font color="#00ff00"><b>in</b></font>
<font color="#8080ff"><b>t1#traintimeReq</b></font> <font color="#00ff00"><b>withGrounding</b></font> <font color="#8080ff"><b>_"http://webservices.deri.org/traintime/In)"</b></font>
<font color="#00ff00"><b>out</b></font>
<font color="#8080ff"><b>t1#traintimeResp</b></font> <font color="#00ff00"><b>withGrounding</b></font> <font color="#8080ff"><b>_"http://webservices.deri.org/traintime/Out)"</b></font>
<font color="#00ff00"><b>transitionRules</b></font> rules
<font color="#ffff00"><b>forall</b></font> <font color="#ffff00"><b>{</b></font><font color="#8080ff"><b>?request</b></font><font color="#ffff00"><b>}</b></font> <font color="#00ff00"><b>with</b></font>
<font color="#ffff00"><b>(</b></font><font color="#8080ff"><b>?request</b></font><font color="#ffff00"><b>[</b></font>
<font color="#8080ff"><b>t1#type</b></font> <font color="#ffff00"><b>hasValue</b></font> <font color="#ff40ff"><b>"detailed"</b></font>
<font color="#ffff00"><b>]</b></font> <font color="#ffff00"><b>memberOf</b></font> <font color="#8080ff"><b>t1#traintimeReq</b></font>
<font color="#ffff00"><b>)</b></font> <font color="#00ff00"><b>do</b></font>
add<font color="#ffff00"><b>(</b></font><font color="#8080ff"><b>?request</b></font> <font color="#ffff00"><b>memberOf</b></font> <font color="#8080ff"><b>t1#detailedTraintimeResp</b></font><font color="#ffff00"><b>)</b></font>
<font color="#00ff00"><b>endForall</b></font>
<font color="#00ff00"><b>orchestration</b></font> orch
</div>
<html>
The choreography of this description essentially models a request response message exchange. The message arn't defined ver semantically, in fact they're just semantic string wrappers, but for the purpose of illustrating the basic choreography concept this shall suffice.
Copy above WSML code and paste it into the argument of the operation with the signature
registerProviderChoreography(String)
If all went well you should see a confirmation message. Now that we have a choreography installed we want to send an instance from the requester to the provider. Here it is:
<html>
<div style="background:black; color:white">
<font color="#00ff00"><b>wsmlVariant</b></font> <font color="#8080ff"><b>_"http://www.wsmo.org/wsml/wsml-syntax/wsml-rule"</b></font>
<font color="#00ff00"><b>namespace</b></font> <font color="#ffff00"><b>{</b></font> <font color="#8080ff"><b>_"http://deri.org/iswc2005tutorial/services/GetTimetable#"</b></font>,
t1 <font color="#8080ff"><b>_"http://deri.org/iswc2005tutorial/services/GetTimetable/travel1#"</b></font>
<font color="#ffff00"><b>}</b></font>
<font color="#00ff00"><b>ontology</b></font> clientRequest
<font color="#00ff00"><b>concept</b></font> <font color="#8080ff"><b>t1#traintimeReq</b></font>
<font color="#8080ff"><b>t1#type</b></font> <font color="#ffff00"><b>ofType</b></font><font color="#ff6060"><b> _string</b></font>
<font color="#00ff00"><b>concept</b></font> <font color="#8080ff"><b>t1#traintimeResp</b></font>
<font color="#8080ff"><b>t1#type</b></font> <font color="#ffff00"><b>ofType</b></font><font color="#ff6060"><b> _string</b></font>
<font color="#00ff00"><b>concept</b></font> <font color="#8080ff"><b>t1#detailedTraintimeResp</b></font>
<font color="#8080ff"><b>t1#type</b></font> <font color="#ffff00"><b>ofType</b></font><font color="#ff6060"><b> _string</b></font>
<font color="#00ff00"><b>instance</b></font> impatientClientRequest <font color="#ffff00"><b>memberOf</b></font> <font color="#8080ff"><b>t1#traintimeReq</b></font>
<font color="#8080ff"><b>t1#type</b></font> <font color="#ffff00"><b>hasValue</b></font> <font color="#ff40ff"><b>"detailed"</b></font>
</div>
</html>
Copy the above code and paste it into second argument of the operation
updateState(String, String)
Fill the first argument with >, the direction from requestor to provider. You should see a confirmation that one of the machines got updated and one got skipped.
The engine uses a listener model to implement linkers that inform other components about relevant state update. For the purpose of this tutorial a history listener is attached that logs all state updates. Invoker the operation with the signature
getProviderMachineHistory()
and you should see that our instance received a membership update, triggered by the transition rules of the choreography.
