You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@jena.apache.org by an...@apache.org on 2021/07/21 18:48:29 UTC
[jena-site] branch sparql-apis created (now f5f43f6)
This is an automated email from the ASF dual-hosted git repository.
andy pushed a change to branch sparql-apis
in repository https://gitbox.apache.org/repos/asf/jena-site.git.
at f5f43f6 Outline for documentation for SPARQL APIs upgrade
This branch includes the following new commits:
new f5f43f6 Outline for documentation for SPARQL APIs upgrade
The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
[jena-site] 01/01: Outline for documentation for SPARQL APIs upgrade
Posted by an...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
andy pushed a commit to branch sparql-apis
in repository https://gitbox.apache.org/repos/asf/jena-site.git
commit f5f43f6875aea7bc0a1a3bb74b3d910525377597
Author: Andy Seaborne <an...@apache.org>
AuthorDate: Wed Jul 21 19:48:13 2021 +0100
Outline for documentation for SPARQL APIs upgrade
---
source/documentation/__index.md | 2 +-
source/documentation/sparql-apis/__index.md | 254 ++++++++++++++++++++++++++++
2 files changed, 255 insertions(+), 1 deletion(-)
diff --git a/source/documentation/__index.md b/source/documentation/__index.md
index 3d5ac9e..16dc624 100644
--- a/source/documentation/__index.md
+++ b/source/documentation/__index.md
@@ -1,5 +1,5 @@
---
-title: Jena documentation overview
+title: Apache Jena documentation overview
slug: index
---
diff --git a/source/documentation/sparql-apis/__index.md b/source/documentation/sparql-apis/__index.md
new file mode 100644
index 0000000..e50cd72
--- /dev/null
+++ b/source/documentation/sparql-apis/__index.md
@@ -0,0 +1,254 @@
+---
+title: Apache Jena SPARQL APIs
+slug: index
+---
+TOC
+
+## Overview
+
+The SPARQL specifications provide
+[query](https://www.w3.org/TR/sparql11-query/),
+[update](https://www.w3.org/TR/sparql11-update/) and the
+[graph store protocol](https://www.w3.org/TR/sparql11-http-rdf-update/) (GSP).
+
+Jena provides a single interface, [`RDFConnection`](../rdfconnection) for working
+with local and remote RDF data using these protools in a unified way for local
+and remote data.
+
+HTTP Authentication is provides for remte operations.
+
+Applications can also use the different parts, such as query directly when they
+want additional control.
+
+The GPI, also called the "Graph SPI" - this is the lower level interface that
+implements generalized RDF (i.e. a triple is any three nodes, including ones
+like variables, and subsystem extension nodes).
+
+
+| API | GPI |
+| ---- | ---- |
+| `Dataset` | `DatasetGraph` |
+| `Model` | `Graph` |
+| `Statement` | `Triple` |
+| `Resource` | `Node` |
+| `Literal` | `Node` |
+| `String` | `Var` |
+
+For SPARQL,
+
+| API | GPI |
+| ---- | ---- |
+| `RDFConnection` | `RDFLink` |
+| `QueryExecution` | `QueryExec` |
+| `UpdateExecution` | `UpdateExec` |
+| `ResultSet` | `RowSet` |
+| | `GSP` |
+| | `SERVICE` |
+
+The GPI version is the main machinery working at the storage and network level,
+and the API version is an adapter to convert to the Model API and related
+classes.
+
+This documentation describes the API classes - the GPI companion classes are the
+same style, sometimes with slightly changed naming.
+
+`UpdateProcessor` is a legacy name for `UpdateExecution`
+
+`GSP` provides the SPARQL Graph Store Protocol, incliding extensions for sending
+and receiving datasets, rather than graphs.
+
+## Changes from Jena 4.1.0 to Jena 4.?.0
+
+* Execution object have a companion builder.
+ This is especially important of HTTP
+ as there a lot of configuration options that may be needed.
+
+* HTTP usage provided by the JDK `java.net.http` package, with challenage
+authentication provides on top by Jena. See below.
+
+* Authentication support is uniformly appied to query, update GSP and SPARQL `SERVICE`.
+
+* HTTP/2 support (Fuseki to follow unless done and tested in time).
+
+* Remove Apache HttpClient usage
+ * When using this for authentication, applciation code chnages wil be
+ necessary.
+
+* Deprecate modfying `QueryExecution` after it is built.
+ This is still supported for local `QueryExecution`.
+
+* Parameterization for remote queries
+
+* `HttpOp` is split into `HttpRDF` for GET/POST/PUT/DELETE of graphs and
+ datasets and new `HttpOp` for packaged up common patterns of HTTP usage.
+
+* DatasetAccessors will be removed.
+
+* GSP - support for dataset operations as well as graphs (also supported by Fuseki).
+
+## <tt>RDFConnection</tt>
+
+[RDFConnection](../rdfconnection/)
+
+```
+example with builder.
+```
+```
+example with factory
+```
+
+
+## Query Execution
+
+Factory Examples
+
+Builder Examples
+
+
+```
+try ( QueryExecution qExec = QueryExecution.create()
+ .dataset(dataset)
+ .query(query)
+ .build() ) {
+ ResultSet resulrs = qExec.execSelect();
+ ... use results ...
+}
+```
+
+```
+try ( QueryExecution qExec = QueryExecutionHTTP.create()
+ .service("http:// ....")
+ .query(query)
+ .build() ) {
+ ResultSet resulrs = qExec.execSelect();
+ ... use results ...
+}
+```
+
+```
+// JDK
+HttpClient httpClient = HttpClient.newBuilder()
+ .connectTimeout(Duration.ofSeconds(10))
+ .followRedirects(Redirect.NORMAL)
+ .build();
+try ( QueryExecution qExec = QueryExecutionHTTP.create()
+ .service("http:// ....")
+ .httpClient(httpClient)
+ .query(query)
+ .sendMode(QuerySendMode.asPost)
+ .timeout(30, TimeUnit.SECONDS)
+ .build() ) {
+ ResultSet resulrs = qExec.execSelect();
+ ... use results ...
+}
+```
+There is only one timeout setting for HTTP query execution. The "time to
+connect" is handled by the JDK `HttpClient`. Timeouts for local execution are
+"time to first result" and "time to all results" as before.
+
+## <tt>GSP</tt>
+
+```
+ Graph graph = GSP.request("http://fuseki/dataset").defaultGraph().GET();
+```
+
+```
+ Graph graph = ... ;
+ GSP.request("http://fuseki/dataset").graphName("http;//data/myGraph").POST(graph);
+```
+
+```
+ DatasetGraph dataset = GSP.request("http://fuseki/dataset").getDataset();
+```
+
+
+## Customization of HTTP requests
+@@
+
+Params (e.g. apikey)
+
+ARQ.httpRequestModifer
+
+## <tt>SERVICE</tt>
+@@
+[Old documentation ](../query/service.html) - passing parameters has changed.
+
+## Misc
+
+Request modifiers
+Params
+
+### ARQ.httpRequestModifer
+
+## Authentication
+
+For any use of users-password information, and especially HTTP basic
+authentication, information is visible in the HTTP headers. Using HTTPS is
+necessary to avoid snoppping. Digest authentication is also stronger over HTTPS
+because it protects againats man-in-the-middle attacks.
+
+4 kinds:
+
+1. Basic authentication
+2. Challenge-Basic authentication
+3. Challenge-Digest authentication
+4. URL userinfo (`users:passwrd@host.net`)
+
+Basic authentication occurs where the app provides the users and password
+information to the JDK `HttpClient` and that information is always used when
+sending HTTP requests with that `HttpClient`. It does not require an initial
+request-challenge-resend to initiate. This is provided natively by the `java.net.http`
+JDK code. See `HttpClient.newBuilder().authenticate(...)`.
+
+Challenge based authentication, for "basic" or "disgest", are provided by Jena.
+The challenge happens on the first contact with the remote endpoint and the
+server returns a 401 response with an HTTP header saying which style of
+authentication is required. There is a registry of users name and password for
+endpoints which is consulted and the appropriate
+[`Authorization:`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization)
+header is generated then the request resent. If no registration matches, the 401
+is passed back to the application as an exception.
+
+Because it is a challenge response to an request, the first request must be
+repeated, first to trigger the challenge and then again with the HTTP
+authentication information. To make this auotmatic, the first request must not be a streaming
+request (the stream is not repeatable). All HTTP request generated by Jena are reapeatible.
+
+While Jena supports user information in URLs using the URI `userinfo` part foa
+URI, this is inherently unsafe because the password is in-clear in the SPARQL
+query.
+
+### JDK HttpClient.authenticator
+
+### Challenge registration
+
+`AuthEnv`
+
+### <tt>SERVICE</tt>
+
+The previous authentication mecanism work with SPARQL queries using `SERVICE`.
+
+Params.
+
+Disable.
+
+
+1/ HttpClient
+
+2/ ?? ARQ.httpRequestModifer
+
+3/ (digest and basic)
+Register username/password
+Including presetting (basic) authentication into the local system
+
+4/ Modifiers (not auth)
+
+Old still supported:
+source/documentation/query/http-auth.md
+
+
+## @@
+
+Links:
+
+source/documentation/query/__index.md