-
Notifications
You must be signed in to change notification settings - Fork 2
/
index.html
265 lines (247 loc) · 10.2 KB
/
index.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
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>RDF/JS: Stream interfaces</title>
<script src="https://www.w3.org/Tools/respec/respec-w3c-common" class="remove"></script>
<script class="remove">
var respecConfig = {
specStatus: "CG-DRAFT",
shortName: "rdfjs-streams",
subtitle: "RDF/JS: Stream interfaces",
processVersion: 2017,
edDraftURI: "https://github.com/rdfjs/stream-spec/",
issueBase: "https://github.com/rdfjs/stream-spec/issues/",
githubAPI: "https://api.github.com/repos/rdfjs/stream-spec",
// TODO: testSuiteURIkey: "",
editors: [{
name: "Thomas Bergwinkl",
url: "https://www.bergnet.org/"
}, {
name: "Ruben Verborgh",
url: "https://ruben.verborgh.org/",
company: "Ghent University – imec",
companyURL: "http://idlab.ugent.be/"
}],
authors: [{
name: "Thomas Bergwinkl",
url: "https://www.bergnet.org/"
}, {
name: "Michael Luggen",
url: "http://oiu.ch",
company: "Bern University of Applied Sciences",
companyURL: "http://www.bfh.ch"
}, {
name: "elf Pavlik",
url: "https://elf-pavlik.hackers4peace.net/"
}, {
name: "Blake Regalia",
company: "STKO Lab @ UCSB",
companyURL: "http://stko.geog.ucsb.edu/"
}, {
name: "Piero Savastano",
url: "http://pieroit.org",
company: "Freelance Data Scientist"
}, {
name: "Ruben Verborgh",
url: "https://ruben.verborgh.org/",
company: "Ghent University – imec",
companyURL: "http://idlab.ugent.be/"
}],
bugTracker: {
open: "https://github.com/rdfjs/stream-spec/issues?utf8=%E2%9C%93&q=is%3Aissue%20is%3Aopen%20",
new: "https://github.com/rdfjs/stream-spec/issues/new"
},
otherLinks: [{
key: "Version control",
data: [{
value: "Github Repository",
href: "https://github.com/rdfjs/stream-spec"
}]
}],
wg: "RDF JavaScript Libraries Community Group",
wgURI: "https://www.w3.org/community/rdfjs/",
wgPublicList: "public-rdfjs",
maxTocLevel: 2
};
</script>
</head>
<body>
<section id="abstract">
<p>
</p>
</section>
<section id="sotd">
<p>
This document provides a specification of a low level interface definition representing RDF data
independent of a serialized format in a JavaScript environment. The task force which defines
this interface was formed by RDF JavaScript library developers with the wish to make existing
and future libraries interoperable. This definition strives to provide the minimal necessary
interface to enable interoperability of libraries such as serializers, parsers and higher level
accessors and manipulators.
</p>
</section>
<section>
<h2>Stream interfaces</h2>
<p>
Streams are used only in a readable manner. This requires only a single queue per stream, which
simplifies implementations and doesn't have performance drawbacks, compared to writeable
streams.
</p>
<p>
The interfaces introduces in this spec make use of the <dfn>Term</dfn> and <dfn>DataFactory</dfn> interfaces from the <a href="https://rdf.js.org/data-model-spec/">RDF/JS Data model specification</a>
</p>
<img src="img/stream_diagram.svg" alt="UML data interface diagram" style="width: 100%;">
<section data-dfn-for="Stream">
<h3><dfn>Stream</dfn> interface</h3>
<pre class="idl">
[Exposed=(Window,Worker)]
interface Stream : EventEmitter {
any read();
attribute Event readable;
attribute Event end;
attribute Event error;
attribute Event data;
attribute Event prefix;
};
</pre>
<p>
A Stream handles a sequence of data as chunks which are emitted or manually pulled over time.
The type of the chunks must be consistent.
Typical types are Buffer or String for serialized data or Quad for RDF data.
</p>
<p>The <dfn>EventEmitter</dfn> and <dfn>Event</dfn> types originate from <a href="https://nodejs.org/docs/latest-v17.x/api/">Node.JS</a></p>
<p>
This specification uses the following notation, for a known type <code>T</code> of a Stream:
<pre>Stream<T></pre>
</p>
<p>
<dfn>read()</dfn>
This method pulls a chunk of data out of the internal buffer and returns it.
If there is no chunk available, then it will return null.
</p>
<p>
<dfn>readable</dfn> When a chunk can be read from the stream, it will emit this event.
</p>
<p>
<dfn>end</dfn> This event fires when there will be no more chunks to read.
</p>
<p>
<dfn>error</dfn> `error(Error error)` This event fires if any error occurs. The `message` describes the error.
</p>
<p>
<dfn>data</dfn> `data(any chunk)` This event is emitted for every chunk that can be read from the stream. The `chunk` is the content of the data.
</p>
<h4>Optional Events</h4>
<p>
These events are not required, but if an implementation wishes to support such events, they should conform to these definitions:
</p>
<p>
<dfn>prefix</dfn> `prefix(string prefix, NamedNode iri)` This event is emitted every time a prefix is mapped to some IRI.
</p>
</section>
<section data-dfn-for="ConstructorOptions">
<h3><dfn>ConstructorOptions</dfn> interface</h3>
<pre class="idl">
[Exposed=(Window,Worker)]
interface ConstructorOptions {
attribute DataFactory? dataFactory;
attribute DOMString? baseIRI;
};
</pre>
<p>
Constructors of all other interfaces defined in this spec accept options parameter. While we define this parameter as optional as well as all its attributes as optional, specific implementations may choose to require them. All implementations SHOULD provide documentation of the constructors and their options.
</p>
<p>
<dfn>dataFactory</dfn> DataFactory implementation that created instance implementing the interface will use to create all the Data Model instances.
</p>
<p>
<dfn>baseIRI</dfn> Base IRI that created instance implementing the interface will use to resolve or create relative IRIs.
</p>
</section>
<section data-dfn-for="Source">
<h3><dfn>Source</dfn> interface</h3>
<pre class="idl">
[Exposed=(Window,Worker)]
interface Source {
constructor();
constructor(ConstructorOptions options);
Stream match(optional Term? subject, optional Term? predicate, optional Term? _object, optional Term? graph);
};
</pre>
<p>
A Source is an object that emits quads. It can contain quads but also generate them on the
fly. For example, parsers and transformations which generate quads can implement the Source
interface.
</p>
<p>
<dfn>match()</dfn> Returns a stream of <code>Quad</code>s that processes all quads matching the pattern.
</p>
<p class="note">
When matching with <code>graph</code> set to <code>undefined</code> or <code>null</code>
it MUST match all the graphs (sometimes called <em>the union graph</em>). To match only <em>the default graph</em>
set <code>graph</code> to a <code>DefaultGraph</code>
</p>
</section>
<section data-dfn-for="Sink">
<h3><dfn>Sink</dfn> interface</h3>
<pre class="idl">
[Exposed=(Window,Worker)]
interface Sink {
constructor();
constructor(ConstructorOptions options);
EventEmitter import(Stream stream);
};
</pre>
<p>
A Sink is an object that consumes data from different kinds of streams. It can store the
content of the stream or do some further processing. For example parsers, serializers,
transformations and stores can implement the Sink interface.
</p>
<p>
<dfn>import()</dfn> Consumes the given stream. The <code>end</code> and <code>error</code>
events are used like described in the <code>Stream</code> interface. Depending on the use
case, subtypes of <code>EventEmitter</code> or <code>Stream</code> are used.
</p>
<h4>Typical use cases</h4>
<ul>
<li><strong>Parser:</strong><pre>Stream<Quad> import(Stream stream)</pre></li>
<li><strong>Serializer</strong><pre>Stream import(Stream<Quad> stream)</pre></li>
<li><strong>Transformation</strong><pre>Stream<Quad> import(Stream<Quad> stream)</pre></li>
<li><strong>Store</strong><pre>EventEmitter .import(Stream<Quad> stream)</pre></li>
</ul>
</section>
<section data-dfn-for="Store">
<h3><dfn>Store</dfn> interface</h3>
<pre class="idl">
[Exposed=(Window,Worker)]
interface Store { // Extends Source and Sink
constructor();
constructor(ConstructorOptions options);
EventEmitter remove(Stream stream);
EventEmitter removeMatches(optional Term? subject, optional Term? predicate, optional Term? _object, optional Term? graph);
EventEmitter deleteGraph((Term or DOMString) graph);
};
</pre>
<p>
A Store is an object that usually used to persist quads. The interface allows removing quads,
beside read and write access. The quads can be stored locally or remotely. Access to stores
LDP or SPARQL endpoints can be implemented with a Store inteface.
</p>
<p>
<dfn>remove()</dfn> Removes all streamed <code>Quad</code>s. The <code>end</code> and <code>error</code>
events are used like described in the <code>Stream</code> interface.
</p>
<p>
<dfn>removeMatches()</dfn> All quads matching the pattern will be removed. The
<code>end</code> and <code>error</code> events are used like described in the
<code>Stream</code> interface.
</p>
<p>
<dfn>deleteGraph()</dfn> Deletes the given named graph. The <code>end</code> and
<code>error</code> events are used like described in the <code>Stream</code> interface.
</p>
</section>
</section>
</body>
</html>