-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathjsap.html
1323 lines (1245 loc) · 43 KB
/
jsap.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<html lang="en">
<head>
<meta content="text/html; charset=utf-8" http-equiv="content-type">
<title>JSON SPARQL Application Profile (JSAP)</title>
<!-- RESPEC CONFIGURATION -->
<script src="https://www.w3.org/Tools/respec/respec-w3c-common"
class="remove"></script>
<script class='remove'>
var respecConfig = {
// document info
specStatus : "unofficial",
shortName : "jsap",
copyrightStart : "2017",
edDraftURI : "https://vaimee.org/TR/jsap.html",
extraCSS : [ "css/respec.css" ],
// editors
editors : [{
name : "Luca Roffia",
mailto : "luca.roffia@unibo.it",
company: "University of Bologna",
companyURL: "https://www.unibo.it/sitoweb/luca.roffia/en"
} ],
formerEditors: [{
name : "Cristiano Aguzzi",
mailto : "cristiano.aguzzi@unibo.it"
}, {
name : "Francesco Antoniazzi",
mailto : "francesco.antoniazzi@unibo.it"
},
{
name : "Fabio Viola",
mailto : "fabio.viola@unibo.it"
} ],
// WG
wg : "Linked Data and Web of Things working group @ ARCES University of Bologna",
wgURI : "https://site.unibo.it/wot/en",
};
</script>
</head>
<body>
<!-- ABSTRACT -->
<section id="abstract">
This document describes the JSON SPARQL Application Profile (JSAP).
JSAP is used to describe an application based on the <a
href="http://vaimee.org/TR/sepa.html">SPARQL Event
Processing Architecture</a> (SEPA) and following the application design
pattern named <b>PAC</b> (<b>P</b>roducer-<b>A</b>ggregator-<b>C</b>onsumer)
described in this document. JSAP uses JSON as default format
[[!RFC7159]] .
</section>
<!-- STATUS OF THIS DOCUMENT -->
<section id="sotd">This is a first draft.</section>
<!-- INTRODUCTION -->
<section id="introduction">
<h2>Introduction</h2>
<p>
This document first presents the concept of SPARQL Application
Profile from a developer point a view. Developers are RECOMMENDED to
follow the PAC design pattern presented in this document (i.e., an
application is composed by a set of producers, consumers and
aggregators). The role of JSAP is to collect the <b>SPARQL
updates</b> [[sparql11-update]], <b><a
href="http://vaimee.org/TR/sparql11-subscribe.html">SPARQL
subscribes</a></b> and the <b>protocol parameters</b> used by a SEPA
application. JSAP MAY contain a list of SPARQL prefixes. In such a
way, JSAP acts as an <i>identity card</i> of a SEPA application.
</p>
<p>
A JSAP file MUST be a JSON document compliant with RFC 7159
[[!RFC7159]] and SHOULD NOT be modified at runtime, as it describes
the application scope. The need of runtime modifications of the JSAP
file is to be considered as a bad practice. Other serialization
formats (e.g., YAML, XML) MAY be used but their definition is out of
the context of this document.
<!--Instead, the Authors suggest the use of more than one JSAP file or, of course, the review of the SPARQL code.-->
</p>
<section id='conventions'>
<h3>Document conventions</h3>
When this document uses the words MUST, MUST NOT, SHOULD, SHOULD NOT,
MAY and RECOMMENDED, and the words appear as emphasized text, they
must be interpreted as described in RFC 2119 [[!RFC2119]].
</section>
<section id="terms">
<h3>Terminology</h3>
<dl>
<dt>JSAP</dt>
<dd>
JSON SPARQL Application Profile (as defined by this <a
href="http://vaimee.org/TR/jsap.html">document</a>)
</dd>
<dt>SPARQL</dt>
<dd>SPARQL Protocol and RDF Query Language (as defined by
[[sparql11-overview]])</dd>
<dt>SPARQL 1.1 Update Language</dt>
<dd>As defined by [[sparql11-update]]</dd>
<dt>SPARQL 1.1 Query Language</dt>
<dd>As defined by [[sparql11-query]]</dd>
<dt>SPARQL 1.1 Subscribe Language</dt>
<dd>
The <a href="http://vaimee.org/TR/sparql11-subscribe.html">subscription
language</a> introduced by the SEPA
</dd>
<dt>SPARQL 1.1 SE Protocol</dt>
<dd>
The <a
href="http://vaimee.org/TR/sparql11-se-protocol.html">protocol</a>
implemented by a SEPA broker
</dd>
<dt>SEPA</dt>
<dd>
<a href="http://vaimee.org/TR/sepa.html">SPARQL Event
Processing Architecture</a>
</dd>
<dt>SEPA application</dt>
<dd>
a collection of producers, consumers and aggregators (as defined by
this <a href="http://vaimee.org/TR/jsap.html">document</a>)
</dd>
<dt>SEPA broker</dt>
<dd>
The server component of the SEPA. It implements the
publish-subscribe mechanisms and algorithms. Clients interact with
a SEPA broker with the <a
href="http://vaimee.org/TR/sparql11-se-protocol.html">SPARQL
1.1 SE Protocol</a>
</dd>
</dl>
</section>
</section>
<!-- CORE OF THE DOCUMENT -->
<section>
<h2>Producer-Aggregator-Consumer design pattern</h2>
<p>The following figure gives an overview of the RECOMMENDED
application design pattern to be followed by SEPA applications
developers.</p>
<img src="media/pac-pattern.jpg" alt="PAC pattern">
<p>
Fig. 1 - The SEPA application design pattern also know as
"PAC-Pattern" (<b>P</b>roducer-<b>A</b>ggregator-<b>C</b>onsumer)
</p>
<p>
The design pattern assumes that a client SHOULD interact with a SEPA
broker using two primitives: <b>update</b> and <b>subscribe</b>. The
protocol used by a client to interact with a SEPA broker is described
in <a href="http://vaimee.org/TR/sparql11-se-protocol.html">SPARQL
1.1 Secure Event Protocol</a>. While an update corresponds to a SPARQL
1.1 Update [[sparql11-update]], a subscribe is described in <a
href="http://vaimee.org/TR/sparql11-subscribe.html">SPARQL
1.1 Subscribe Language</a>. A subscribe acts as a persistent SPARQL 1.1
Query [[sparql11-query]] and the content of a notification contains
the <i>delta</i> of the results since the previous notification
(i.e., when a subscribe is invoked the current query results are
returned to the client) as described in <a
href="http://vaimee.org/TR/sparql11-subscribe.html">SPARQL
1.1 Subscribe Language</a>. A client assumes a different role depending
on how it interacts with a SEPA broker.
</p>
<p></p>
<p>
A <i>producer</i> invokes a SPARQL 1.1 Update [[sparql11-update]] and
such update MUST be always the same (i.e., see <b><a
href="#forcedBindings">forced bindings</a></b>). A sensor producing some
measures is an example.
</p>
<p>
A <i>consumer</i> invokes a <a
href="http://vaimee.org/TR/sparql11-subscribe.html">SPARQL
1.1 Subscribe</a>. Like the update of a producer, a consumer MUST invoke
one and only one subscribe. When a consumer subscribes, it MAY
replace some variables within the <a
href="http://vaimee.org/TR/sparql11-subscribe.html">SPARQL
1.1 Subscribe</a> with actual values (i.e., see <b><a
href="#forcedBindings">forced bindings</a></b>). An actuator subscribed
to events (or commands) is an example.
</p>
<p>
An <i>aggregator</i> acts as follows: when it receives a
notification, it processes the notification content and invokes an
update (if needed). The processing of an aggregator can be
combinatorial or sequential. In the former case there is no need of
an internal <i>context memory</i>. To be classified as aggregator, a
relation between the notification and the corresponding update SHOULD
exist (i.e., an aggregator is not the sum of a producer and a
consumer). In the PAC pattern, <b>aggregators implement the
application business logic</b>.
</p>
<p class='note' title='PAC the Web of Things'>
The PAC pattern MAY be attractive for <b>Web of Things</b>
applications: producers and consumers interact with the physical
world and SHOULD be kept as simpler as possible. Aggregators MAY be
more resources greedy (e.g., MAY run on a high performance server
machine). This distinction is also very important for reuse and
modularization: the same set of producers and consumers can be
re-used in other applications and the application business logic can
be changed (or extended) just by adding (or extending) aggregators.
</p>
<p>
</section>
<section>
<h2>JSAP structure</h2>
<p>A JSAP is structured as follows.
<pre class="example" title="JASP structure" id="JSAPMainStructure">
{
"host":"...",
"oauth":{},
"sparql11protocol":{},
"sparql11seprotocol":{},
"namespaces":{},
"extended":{},
"graphs":{
"default-graph-uri": [],
"named-graph-uri": [],
"using-graph-uri": [],
"using-named-graph-uri": []
},
"updates":{
"UPDATE_IDENTIFIER_1":{},
"...":{},
"UPDATE_IDENTIFIER_N":{}
},
"queries":{
"QUERY_IDENTIFIER_1":{},
"...":{},
"QUERY_IDENTIFIER_N":{}
}
}
</pre>
The
<code>host</code>
,
<code>sparql11protocol</code>
and
<code>sparql11seprotocol</code>
MUST be all present. The
<code>host</code>
member contains the host name or IP of the SEPA broker. The other two
members allow to configure respectively the SPARQL 1.1 protocol
[[sparql11-protocol]] and <a
href="http://vaimee.org/TR/sparql11-se-protocol.html">SPARQL
1.1 Secure Event Protocol</a>. With reference to the SPARQL 1.1 protocol
[[sparql11-protocol]], the
<code>graphs</code>
member MAY be used to specify zero or more default graph URIs (
<code>default-graph-uri</code>
) and named graph URIs (
<code>named-graph-uri</code>
) for queries (i.e., subscribes), as well as zero or more default
graph URIs (
<code>using-graph-uri</code>
) and named graph URIs (
<code>using-named-graph-uri</code>
) for udpdates. The values of all these members MAY be overwritten
within the
<code>updates</code>
and
<code>queries</code>
as described later. The
<code>extended</code>
member is optional and it MAY be used to store application specific
data.
<section>
<h3>Protocol parameters</h3>
<p>
A semantic application profile, in order to fully describe an
application, MUST contain the protocol parameters needed by an
application to interact with a SEPA broker instance through the <a
href="http://vaimee.org/TR/sparql11-se-protocol.html">SPARQL
1.1 SE Protocol</a>, like the HTTPS interface (used by secure SPARQL
updates and SPARQL queries) and the Websocket interface (needed by
(secure) SPARQL subscriptions). In JSAP, such parameters are
described by two mandatory JSON objects named
<code>sparql11protocol</code>
and
<code>sparql11seprotocol</code>
.
<pre class="example"
title="SPARQL 1.1 protocol parameters (not secure)"
id="sparql11protocol-notsecure">
{
"sparql11protocol":{
"protocol":"http",
"port":8000,
"query":{
"path":"/query",
"method":"POST",
"format":"JSON"
},
"update":{
"path":"/update",
"method":"POST",
"format":"JSON"
}
}
}</pre>
<p>
The value of the
<code>host</code>
member specifies the host where the SEPA broker is running (e.g.,
vaimee.org).
</p>
<p>
The
<code>port</code>
member specifies the port where the SEPA broker is listening for
SPARQL 1.1 primitives (updates and queries).
</p>
<p>
The
<code>protocol</code>
member specifies the protocol used and it can assume the values:
<code>http</code>
or
<code>https</code>
.
</p>
<p>
The
<code>update</code>
and
<code>query</code>
members contain the following members:
<code>path</code>
(i.e., the path part of the URL),
<code>method</code>
(i.e., the HTTP method used) and
<code>format</code>
(i.e., the format of the response). According to the SPARQL 1.1
protocol [[sparql11-protocol]], for queries the
<code>format</code>
can be POST, GET, URL_ENCODED_POST, while for updates it can be POST
or URL_ENCODED_POST. All the SEPA implementations MUST support JSON
as return format, while other formats like XML, CSV or HTML MAY be
supported.
</p>
<pre class="example"
title="SPARQL 1.1 SE protocol parameters (not secure)"
id="sparql11seprotocol">
{
"sparql11seprotocol":{
"protocol":"ws",
"availableProtocols":{
"ws":{
"port":9000,
"path":"/subscribe"
},
"wss":{
"port":9443,
"path":"/secure/subscribe"
}
}
}
}
</pre>
The URLs corresponding to the above protocol configuration (not
secure) follow:
<pre class="example"
title="URLs used by SEPA primitives (not secure)">
- Query: http://vaimee.org:8000/query
- Update: http://vaimee.org:8000/update
- Subscribe: ws://vaimee.org:9000/subscribe</pre>
</section>
<section>
<h3>Security</h3>
Connecting to a secure SEPA broker require the following changes to
the above protocol configurations:
<pre class="example"
title="Enabling security and client authorization" id="oauth">
{
"oauth":{
"enable":true,
"register":"https://localhost:8443/oauth/register",
"tokenRequest":"https://localhost:8443/oauth/token"
}
}
</pre>
The
<code>oauth</code>
member allows to specify the Authorization Server URLs used to
register a new client identity and request tokens.
<pre class="example" title="SPARQL 1.1 protocol parameters (secure)"
id="sparql11protocol">
{
"sparql11protocol":{
"protocol":"https",
"port":8443,
"query":{
"path":"/secure/query",
"method":"POST",
"format":"JSON"
},
"update":{
"path":"/secure/update",
"method":"POST",
"format":"JSON"
}
}
}</pre>
<pre class="example"
title="SPARQL 1.1 SE protocol parameters (secure)"
id="sparql11seprotocol-secure">
{
"sparql11seprotocol":{
"protocol":"wss"
}
}</pre>
The corresponding URLs would be as follows:
<pre class="example" title="URLs used by SEPA primitives (secure)">
- SECURE Query: https://vaimee.org:8443/secure/query
- SECURE Update: https://vaimee.org:8443/secure/update
- SECURE Subscribe: wss://vaimee.org:9443/secure/subscribe
- Registration: https://vaimee.org:8443/oauth/register
- Token request: https://vaimee.org:8443/oauth/token
</pre>
<p>
JSAP MAY also be used by clients to store credentials (i.e., <i>clientId</i>
and <i>clientSecret</i>) and JSON Web Token. For security reasons,
it is RECOMMENDED to encrypt those elements (e.g., using <a
href="https://dx.doi.org/10.6028/NIST.FIPS.197">Advanced
Encryption Standard (AES)</a>) like in the following example:
</p>
<pre class="note" title="Storing client credentials">
{
"oauth":{
"client_id":"0IWFPpcBdkiZDqsvd2g/hjES9a3bvWhES7ieo/oH1nJx/lBURPHmu/uw9rSqs52M",
"client_secret":"kMEeuqq/tj8yILnL4u0rNIJAPcdkLTfx6yIt4wOoV1F3dWmZkG8NJUJKzyyMoiat",
"jwt":"xabtQWoH8RJJk1FyKJ78J8h8i2PcWmAugfJ4J6nMd+1jVSoiipV4Pcv8bH+8wJLJ2yRaVage8/TzdZJiz2jdRP8bhkuNzFhGx6N1/1mgmvfKihLheMmcU0pLj5uKOYWFb+TB98n1IpNO4G69lia2YoR15LScBzibBPpmKWF+XAr5TeDDHDZQK4N3VBS/e3tFL/yOhkfC9Mw45s3mz83oyeoFFePUX8MQIuqd3TIcjOhoPgYWd0E+L/EN5wItL5/n78pX/8mVZcpxdyNNqr3bVvrCi0I84mIAefwQ0GyPxFhUHu9PtVNQnXchZuFgppX/YDtOesZSxfIoffUpHFPBY3u4FRIYwpSZX96Knnp0J22RQm+0l8yobik3z6jftw0jbF5+/YC6PnfZT3Wzb6PRJPuVkDzpo+BTC9eKx87GEj8VjtfXjbYRTeZNumD+59wL5kV/OrntNqNQD+IzAYoIZk4rlRbNouNnvT0laEhV012tSD1uAfNUxAlZjSbSMTp5bPNp7PoutMr5q6zPYfAC1PTKnVdkD1CDNqZnhB838WDeISfVzXsf7dsZ0+SkNPtx2kMUYCOYsxNJxyzza3lmaCuvxfnDT3g5F41/p/zX1tXYy6emVfdOWSkJNm1z0FJB/ZIUES0WAA5UEM3kejND++vvIQr38ar72HdFzRvP2V29CsaE5PMRRRZIE5ru9Zwgdb5lfMdwDi4sZkQdNRGHiOfRCT9D92mFVps6s6kv7HKojx05R9WKMDG8bEmSgMYSYQlQzLm93Ardw/hpDoB1/DfNRxbc/GVNZEVOoRVMye8/vICZtxvVeKmu4QawWKSBtrXelWUT8AHTG6v/c88pZjtJWDzy6YIIXLDQ2eJPu30mt3gLfS2ukIV4Tl5Oqu3T1IIghmNgek8vwWNeuG/JGeKrfUp6X6mMH9hdmj5+naOIr8V5rUKCjXnlWLAsrGdOvV8vuYYbx2IFQScZQJD/sTKj3gs6yeYpOwQ2iEs9asA=",
"expires":"9SN2d0sZEIN16Kts7LxUuQ==",
"type":"XPrHEX2xHy+5IuXHPHigMw=="
}
}
</pre>
</section>
<section>
<h3>Namespaces</h3>
<p>
JSAP MAY include a set of namespaces used by SPARQL updates and
queries. Client-side APIs SHOULD take the namespaces and prepend
them to a SPARQL update/subscribe. This allows to simplify the
SPARQL text by using qualified names for URIs [[xml-names]].
Namespaces are specified as a JSON object assigned to the key
<code>namespaces</code>
. In this object, every key represents a prefix, while the value is
the relative namespace.
</p>
<pre class="example" title="Namespaces">
{
"namespaces":{
"rdf":"http://www.w3.org/1999/02/22-rdf-syntax-ns#",
"rdfs":"http://www.w3.org/1999/02/22-rdf-syntax-ns#",
"sosa":"http://www.w3.org/ns/sosa/",
"qudt-1-1":"http://qudt.org/1.1/schema/qudt#",
"qudt-unit-1-1":"http://qudt.org/1.1/vocab/unit#",
"arces-monitor":"http://wot.arces.unibo.it/monitor#",
"time":"http://www.w3.org/2006/time#",
"schema":"http://schema.org"
}
}
</pre>
</section>
<section>
<h3>Updates, queries and forced bindings</h3>
<p>
The main benefit of JSAP consists in the ability of creating
templates for applications. Those templates act as an <i>identity
card</i> of an application. JSAP MAY include two JSON objects named
<code>updates</code>
and
<code>queries</code>
listing all the SPARQL 1.1 updates [[sparql11-update]] and <a
href="http://vaimee.org/TR/sparql11-subscribe.html">SPARQL
1.1 subscribes</a> used by the application.The
<code>updates</code>
and
<code>queries</code>
members, if present, contain a list of objects sharing the structure
here reported:
</p>
<pre class="example" title="Update and query template">
{
"QUERY_OR_UPDATE_IDENTIFIER":{
"sparql":"SPARQL Update or Query",
"forcedBindings":{},
"sparql11protocol":{},
"sparql11seprotocol":{},
"graphs":{}
}
}
</pre>
<p>
The value of the mandatory
<code>sparql</code>
member is the SPARQL query [[sparql11-query]] or update
[[sparql11-update]]. The
<code>sparql11protocol</code>
,
<code>sparql11seprotocol</code>
and
<code>graphs</code>
members MAY be used to overwrite some protocol parameters.
</p>
<p>
SPARQL updates and subscribes can be fetched by the application and
modified at run-time to fit the application needs. For example, a
producer that updates the value of a temperature sensor will only
need to fill a field in the template (i.e., the current value). Here
is where the definition of <i>forced bindings</i> comes in help. A
forced binding enables the developer to substitute at run-time a
variable in a template with a custom value. To define forced
bindings, the key
<code>forcedBindings</code>
MUST be used. The value is a JSON object. The variable of a forced
binding is a key in that JSON object. Its value is again a JSON
object containing the keys
<code>type</code>
and
<code>value</code>
.
<code>type</code>
is mandatory and MUST be one of
<code>"uri"</code>
,
<code>"bnode"</code>
,
<code>"literal"</code>
. The
<code>value</code>
key is optional and SHOULD be used to specify a <i>default</i> value
for that variable.
</p>
<pre class="example" id="forcedBindings" title="Forced bindings">
{
"forcedBindings":{
"variable-X-uri":{
"type":"uri",
"value":"..."
},
"variable-Y-literal":{
"type":"literal",
"value":"...",
"datatype":"XSD Datatype"
},
"variable-Z-bnode":{
"type":"bnode",
"value":"..."
}
}
}
</pre>
<p>
The role of the
<code>forcedBindings</code>
member is to define which variables will be replaced at run-time by
their actual values. The use of forced bindings can be appreciated
by considering the following example. The updates listed within the
<code>updates</code>
member share a common template but with different forced bindings.
</p>
<pre class="example" title="The role of forced bindings">
{
"namespaces":{
"rdf":"http://www.w3.org/1999/02/22-rdf-syntax-ns#",
"wot":"http://wot.arces.unibo.it/wot#"
},
"updates":{
"UPDATE_ALL_TO_100":{
"sparql":"DELETE {?sensor wot:hasValue ?oldValue} INSERT {?sensor wot:hasValue '100'} WHERE {?sensor rdf:type wot:SENSOR . ?sensor wot:hasValue ?oldValue}"
},
"UPDATE_ALL_TO_X":{
"sparql":"DELETE {?sensor wot:hasValue ?oldValue} INSERT {?sensor wot:hasValue ?x} WHERE {?sensor rdf:type wot:SENSOR . ?sensor wot:hasValue ?oldValue}",
"forcedBindings":{
"x":{
"type":"literal",
"datatype":"xsd:integer"
}
}
},
"UPDATE_SENSOR_TO_X":{
"sparql":"DELETE {?sensor wot:hasValue ?oldValue} INSERT {?sensor wot:hasValue ?x} WHERE {?sensor rdf:type wot:SENSOR . ?sensor wot:hasValue ?oldValue}",
"forcedBindings":{
"x":{
"type":"literal",
"datatype":"xsd:integer"
},
"sensor":{
"type":"uri"
}
}
}
}
}
</pre>
<p>
The <b>UPDATE_ALL_TO_100</b> do not have any forced binding. The
update will be issued as it is to the SEPA broker and the effect
will be to update all the sensor data values (e.g., <i>wot:hasValue</i>)
to
<code>"100"</code>
.
</p>
<p>
In the update "UPDATE_ALL_TO_X", the fixed value
<code>"100"</code>
has been replaced by the variable
<code>?x</code>
, that is also a literal forced binding. At run-time, the a SEPA
agent would replace the variable
<code>?x</code>
with a literal value, like for example "46". The actual update
issued to the SEPA broker follows and the effect will be to update
all the sensor data values (e.g., <i>wot:hasValue</i>) to
<code>"46"</code>
.
</p>
<aside class="example"
title="Actual SPARQL update after replacing the ?x forced binding">
<br>DELETE {?sensor wot:hasValue ?oldValue} <br>INSERT
{?sensor wot:hasValue
<code>"46"</code>
} <br>WHERE {?sensor rdf:type wot:SENSOR . ?sensor wot:hasValue
?oldValue}
</aside>
<p>
The update "UPDATE_SENSOR_TO_X", is the same as the previous update,
but the
<code>?sensor</code>
variable is to be considered a forced binding. A SEPA agent is
supposed to replace both the forced bindings (i.e,
<code>?x</code>
and
<code>?sensor</code>
) before sending the update to the SEPA broker (e.g., ?x =
<code>"69"</code>
and ?sensor =
<code>wot:SENSOR_XYZ_URI</code>
). The actual update issued to the SEPA broker follows and the
effect will be to update the data value (e.g., <i>wot:hasValue</i>)
of the sensor identified by the URI
<code>wot:SENSOR_XYZ_URI</code>
to
<code>"69"</code>
.
</p>
<aside class="example"
title="Actual SPARQL update after replacing the ?x and ?sensor forced bindings">
<br>DELETE {
<code>wot:SENSOR_XYZ_URI</code>
wot:hasValue ?oldValue} <br>INSERT {
<code>wot:SENSOR_XYZ_URI</code>
wot:hasValue
<code>"69"</code>
} <br>WHERE {
<code>wot:SENSOR_XYZ_URI</code>
rdf:type wot:SENSOR .
<code>wot:SENSOR_XYZ_URI</code>
wot:hasValue ?oldValue}
</aside>
<p>Eventually, from the application point of view, JSAP hides
SPARQL complexity and allow the use of a simple portable interface
to create Dynamic Linked Data applications.</p>
</section>
</section>
<section>
<h3>A minimum working example: a SEPA based chat</h3>
<p>In order to provide the reader with a better understanding of
the SEPA application design pattern using the proposed JASP, this
section presents a simple and at the same time meaningful example.</p>
<p>The example is a chat application where users exchange
messages. A user should be able to send a message to an other user
and be notified when the message has been received. In the following
is described how this behaviour can be implemented thanks to the
publish-subscribe mechanism provided by SEPA. According to the
producer-aggregator-consumer design pattern proposed in this
document, a chat client can be implemented by the following agents:
<ul>
<li>A <b>producer</b>(Sender) who produces the message
</li>
<li>An <b>aggregator</b>(Receiver) who receives the
notification and then notify about the arrival
</li>
<li>An <b>aggregator</b>(Remover) who waits for the
notification sent by the Receiver and delete the message from the
knowledge base
</li>
</ul>
These entities can be mapped to the following interface of functions:
<ul>
<li>Updates:
<ul>
<li>Sender <i>calls</i> SEND(sender,receiver,text) where the
sender and receiver parameters are URIs, while the text is a
literal
</li>
<li>Remover <i>calls</i> REMOVE(message) where message
parameter is the message URI
</li>
<li>Receiver <i>calls</i> SET_RECEIVED(message) where message
parameter is the message URI
</li>
</ul>
</li>
<li>Queries:
<ul>
<li>Receiver <i>subscribes to</i> SENT
</li>
<li>Remover <i>subscribes to</i> REMOVED
</li>
</ul>
</li>
</ul>
These information define the semantic application and can be written
in a first draft of the JSAP:
<pre class="example"
title="Draft of the chat's JSAP. The JSAP includes all the primitives used by the application. For some primitives (e.g., SET_RECEIVED), the forced bindings are specified (e.g., message)">
{
"updates":{
"SEND":{
"sparql":"...",
"forcedBindings":{
"text":{
"type":"literal"
},
"sender":{
"type":"uri"
},
"receiver":{
"type":"uri"
}
}
},
"SET_RECEIVED":{
"sparql":"...",
"forcedBindings":{
"message":{
"type":"uri"
}
}
},
"REMOVE":{
"sparql":"...",
"forcedBindings":{
"message":{
"type":"uri"
}
}
}
},
"queries":{
"SENT":{},
"RECEIVED":{}
}
}
</pre>
<p>After defining the message format (i.e. how it is encoded in
RDF triples) the structure of the chat application obtained by this
design step is depicted in the following figure.</p>
<img src="media/chat.jpg" alt="chat">
<p>Fig. 2 - The SEPA Chat example: each client is composed by
three SEPA agents (sender, receiver and remover)</p>
<p>Finally the primitives are implemented with SPARQL
queries/updates and the JASP is filled with this information:</p>
<pre class="example" title="Chat's JSAP: updates and queries">
{
"namespaces":{
"schema":"http://schema.org/",
"rdf":"http://www.w3.org/1999/02/22-rdf-syntax-ns#"
},
"updates":{
"SEND":{
"sparql":"INSERT {?message rdf:type schema:Message ; schema:text ?text ; schema:sender ?sender ; schema:toRecipient ?receiver; schema:dateSent ?time} WHERE {?sender rdf:type schema:Person . ?receiver rdf:type schema:Person BIND(STR(now()) AS ?time) BIND(IRI(CONCAT(\"http://schema.org/Message-\",STRUUID())) AS ?message)}",
"forcedBindings":{
"text":{
"type":"literal"
},
"sender":{
"type":"uri"
},
"receiver":{
"type":"uri"
}
}
},
"SET_RECEIVED":{
"sparql":"INSERT {?message schema:dateReceived ?time} WHERE {?message rdf:type schema:Message BIND(STR(now()) AS ?time)}",
"forcedBindings":{
"message":{
"type":"uri"
}
}
},
"REMOVE":{
"sparql":"DELETE {?message ?p ?o} WHERE {?message rdf:type schema:Message ; schema:dateReceived ?time . ?message ?p ?o}",
"forcedBindings":{
"message":{
"type":"uri"
},
"time":{
"type":"literal"
}
}
}
},
"queries":{
"SENT":{
"sparql":"SELECT ?message ?sender ?name ?text ?time WHERE {?message rdf:type schema:Message ; schema:text ?text ; schema:sender ?sender ; schema:toRecipient ?receiver ; schema:dateSent ?time . ?sender rdf:type schema:Person ; schema:name ?name .?receiver rdf:type schema:Person} ORDER BY ?time",
"forcedBindings":{
"receiver":{
"type":"uri"
}
}
},
"RECEIVED":{
"sparql":"SELECT ?message ?time WHERE {?message schema:sender ?sender ; schema:dateReceived ?time ; rdf:type schema:Message}",
"forcedBindings":{
"sender":{
"type":"uri"
}
}
}
}
}
</pre>
At runtime when the two clients join the chat, their Receiver and
Remover agents subscribe to the SEPA broker by replacing respectively
the receiver forcedbinding in the SENT query and the sender
forcedbinding in the RECEIVED query with the client identifier (e.g.,
schema:PersonURI1 for client #1 and schema:PersonURI2 for client #2).
When client #1 sends a new message to client #2, it invokes the SEND
update, first replacing the sender and receiver forced bindings with
the current one (i.e., respectively schema:PersonURI1 and
schema:PersonURI2) and the text binding with the message to be sent.
The effect of the update is to create the bold graph shown in Fig. 2.
This update triggers a notification for client #2: its Receiver agent
inserts the dotted part of the graph to specify the receiving time.
This is done by invoking the SET_RECEIVED update, replacing the
message forced binding with the corresponding one included in the
notification. This update triggers a notification on client #1:
client #1 knows at this time that client #2 has received the
message(i.e.,the clients are synchronized)and can delete the
corresponding graph from the RDF store. This is done invoking the
REMOVE update, replacing the message forced binding with the
effective551 URI of the message to be removed. The effect of this
update is two folds: the RDF store is cleaned by all messages that
have been received (i.e., the store contains only the messages that
have been sent but not yet received) and the Receiver agent is
notified of the removed bindings (i.e., client #2 is aware that
client #1 has been notified by the SET_RECEIVED update).
<p>The flow of messages exchanged by the clients in the previous
example is described by following UML sequence diagram:</p>
<img src="media/SEPAChat.png" alt="SEPA chat">
<p>Fig. 3 - Send message; UML sequence diagram</p>
<p>Finally the following snippet show the full JSAP of the chat
application with the configuration parameters</p>
<pre class="example" title="Chat JSAP">
{
"host":"localhost",
"oauth":{
"enable":false,
"register":"https://localhost:8443/oauth/register",
"tokenRequest":"https://localhost:8443/oauth/token"
},
"sparql11protocol":{
"protocol":"http",
"port":8000,
"query":{
"path":"/query",
"method":"POST",
"format":"JSON"
},
"update":{
"path":"/update",
"method":"POST",
"format":"JSON"
}
},
"sparql11seprotocol":{
"protocol":"ws",
"availableProtocols":{
"ws":{
"port":9000,
"path":"/subscribe"
},
"wss":{
"port":9443,
"path":"/secure/subscribe"
}
}
},
"extended":{
"type":"basic",
"base":0,
"clients":10,
"messages":1
},
"graphs":{
"default-graph-uri":["http://wot.arces.unibo.it/chat"],
"named-graph-uri":["http://wot.arces.unibo.it/chat"],
"using-graph-uri":["http://wot.arces.unibo.it/chat"],
"using-named-graph-uri":["http://wot.arces.unibo.it/chat"]
},
"namespaces":{
"schema":"http://schema.org/",
"rdf":"http://www.w3.org/1999/02/22-rdf-syntax-ns#",
"chat":"http://wot.arces.unibo.it/chat#"
},
"updates":{
"SEND":{
"sparql":"INSERT {?message rdf:type schema:Message ; schema:text ?text ; schema:sender ?sender ; schema:toRecipient ?receiver; schema:dateSent ?time} WHERE {?sender rdf:type schema:Person . ?receiver rdf:type schema:Person BIND(STR(now()) AS ?time) BIND(IRI(CONCAT(\"http://schema.org/Message-\",STRUUID())) AS ?message)}",
"forcedBindings":{
"text":{
"type":"literal",
"value":"Ciao!"
},
"sender":{
"type":"uri",
"value":"chat:IamASender"
},
"receiver":{
"type":"uri",
"value":"chat:IamAReceiver"
}
}
},
"SET_RECEIVED":{
"sparql":"INSERT {?message schema:dateReceived ?time} WHERE {?message rdf:type schema:Message BIND(STR(now()) AS ?time)}",
"forcedBindings":{
"message":{
"type":"uri",
"value":"chat:ThisIsAMessage"
}
}
},
"REMOVE":{
"sparql":"DELETE {?message ?p ?o} WHERE {?message rdf:type schema:Message ; ?p ?o}",
"forcedBindings":{
"message":{
"type":"uri",
"value":"chat:ThisIsAMessage"
}
}
},
"STORE_SENT":{