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 2014/01/21 22:09:50 UTC
svn commit: r1560189 - in /jena/branches/jena-fuseki-new-ui/docs: ./
fuseki-data-services.md fuseki-java.md fuseki-main.md fuseki-protocol.md
fuseki-stats.md
Author: andy
Date: Tue Jan 21 21:09:50 2014
New Revision: 1560189
URL: http://svn.apache.org/r1560189
Log:
Start of documentation
Added:
jena/branches/jena-fuseki-new-ui/docs/
jena/branches/jena-fuseki-new-ui/docs/fuseki-data-services.md
jena/branches/jena-fuseki-new-ui/docs/fuseki-java.md
jena/branches/jena-fuseki-new-ui/docs/fuseki-main.md
jena/branches/jena-fuseki-new-ui/docs/fuseki-protocol.md
jena/branches/jena-fuseki-new-ui/docs/fuseki-stats.md
Added: jena/branches/jena-fuseki-new-ui/docs/fuseki-data-services.md
URL: http://svn.apache.org/viewvc/jena/branches/jena-fuseki-new-ui/docs/fuseki-data-services.md?rev=1560189&view=auto
==============================================================================
--- jena/branches/jena-fuseki-new-ui/docs/fuseki-data-services.md (added)
+++ jena/branches/jena-fuseki-new-ui/docs/fuseki-data-services.md Tue Jan 21 21:09:50 2014
@@ -0,0 +1,56 @@
+# Fuseki : Data Services
+
+Fuseki provides a number of "data services" - each data service is an RDF datasets
+and a configurable set of endpoints for various operations such as SPARQL query,
+SPARQL update and file upload.
+
+----------------------------
+
+> _@@ Just rough notes : out-of-date and inconsistent_
+
+## Naming
+
+The naming style for application operations is:
+
+ / name / endpoint ? parameters
+
+where `name` is
+
+and `endpoint` is
+
+
+In the administration operations, the name is used after the
+
+ /
+
+e.g.
+
+In administration operations, the dataset name is appended to the operation. For
+example, `http://host:port/$/datasets/ds` accesses the assembler description
+of the dataset.
+
+There is also an internal name, generated by the server which is a UUID.
+This UUID is never reused even if the dataset name is reused after the
+first use is deleted.
+
+## The Dataset Lifecycle
+
+The lifecycle of a dataset
+
+* Active
+* Offline
+
+An *active* dataset is able to rpocess applications requests.
+
+An *offline* dataset is one whos configuration is know to the server but is currently not controlled by the server.
+
+When offline, the dataset is unavailable for application requests but the name remains in-use and the configuration information retained. When made active again, the dataset and it's associated services are recreated. When offline, Fuseki does not retain any access to the data so the dataset can be changed with tools outside of Fuseki. When active, Fuseki assumes it has full control of a dataset (in particular TDB datasets can not be updated by other applications while active).
+
+When Fuseki is not running, all datasets can be comnsidered offline even if theywere not explciitly made so prior to shutdown of the server.
+
+
+(If a datset uses in-memory storage, changes to its state are lost even though it is recreated from its; configuration when the server restarts.)
+
+
+## Links
+
Added: jena/branches/jena-fuseki-new-ui/docs/fuseki-java.md
URL: http://svn.apache.org/viewvc/jena/branches/jena-fuseki-new-ui/docs/fuseki-java.md?rev=1560189&view=auto
==============================================================================
--- jena/branches/jena-fuseki-new-ui/docs/fuseki-java.md (added)
+++ jena/branches/jena-fuseki-new-ui/docs/fuseki-java.md Tue Jan 21 21:09:50 2014
@@ -0,0 +1,5 @@
+## SPARQL etc from Java
+
+> _@@_
+
+Jena APIs
Added: jena/branches/jena-fuseki-new-ui/docs/fuseki-main.md
URL: http://svn.apache.org/viewvc/jena/branches/jena-fuseki-new-ui/docs/fuseki-main.md?rev=1560189&view=auto
==============================================================================
--- jena/branches/jena-fuseki-new-ui/docs/fuseki-main.md (added)
+++ jena/branches/jena-fuseki-new-ui/docs/fuseki-main.md Tue Jan 21 21:09:50 2014
@@ -0,0 +1,28 @@
+## index file
+
+> _@@_
+
+Contents
+
+ Download
+ Packaging
+ WAR, standalone server, servlets
+ Getting Started : Running the standalone server
+ Security
+ BE CAREFUL
+ Logging
+ Server URI scheme
+ Running a Fuseki Server
+ Development System
+ Fuseki Configuration File
+ SPARQL Over HTTP
+ Use from Java
+
+Other parts:
+
+[fuseki-data-services](fuseki-data-services.html)
+[fuseki-java](fuseki-java.html)
+[fuseki-main](fuseki-main.html)
+[fuseki-protocol](fuseki-protocol.html)
+[fuseki-stats](fuseki-stats.html)
+
Added: jena/branches/jena-fuseki-new-ui/docs/fuseki-protocol.md
URL: http://svn.apache.org/viewvc/jena/branches/jena-fuseki-new-ui/docs/fuseki-protocol.md?rev=1560189&view=auto
==============================================================================
--- jena/branches/jena-fuseki-new-ui/docs/fuseki-protocol.md (added)
+++ jena/branches/jena-fuseki-new-ui/docs/fuseki-protocol.md Tue Jan 21 21:09:50 2014
@@ -0,0 +1,147 @@
+# Fuseki HTTP Administration Protocol
+
+> _These functions are available in version 2.0 and later._
+
+This page describes the HTTP Protocol used to control an Fuseki server via its administrative interface. See "[Fuseki Administration](admin.html)" for an overview of server administration.
+
+* [Operations](#operations)
+* [Server Information](#server-information)
+* [Datasets and Services](#datasets-and-services)
+ * Adding a Dataset and its Services
+ * Removing a Dataset
+ * Dormant and Active
+* [Removing a dataset](#remove-dataset)
+
+These are enabled by starting the server with argument `--mgt`.
+
+
+
+All admin operations have URL paths starting `/$/` to avoid clashes
+with dataset names and this prefix is reserved for the Fuseki control functions.
+Further operations may be added within this naming scheme.
+
+## Operations
+
+| Method | URL pattern | Description |
+|-----------------|------------------------|---------------|
+||
+| <tt>GET</tt> | `/$/ping` | |
+| <tt>POST</tt> | `/$/ping` | |
+| <tt>GET</tt> | `/$/server` | |
+| <tt>POST</tt> | `/$/server` | |
+||
+| <tt>POST</tt> | `/$/datasets/` | |
+| <tt>GET</tt> | `/$/datasets/` | |
+| <tt>DELETE</tt> | `/$/datasets/*{name}*` | |
+| <tt>GET</tt> | `/$/datasets/*{name}*` | |
+| <tt>POST</tt> | `/$/datasets/*{name}*?state=offline` | |
+| <tt>POST</tt> | `/$/datasets/*{name}*?state=active` | |
+| <tt>POST</tt> | `/$/backup/*{name}*` | Not yet implemented |
+||
+| <tt>POST</tt> | `/$/server/shutdown` | Not yet implemented |
+||
+| <tt>GET</tt> | `/$/stats/` | |
+| <tt>GET</tt> | `/$/stats/*{name}*` | |
+
+## Ping
+Pattern: `/$/ping`
+
+The URL `/$/ping` is a guaranteed low cost point to test whether a server
+is running or not. It returns no other information other than to respond to the
+request over `GET` or `POST` (to avoid any HTTP caching) with a 200 response.
+
+## Server Information
+Pattern: `/$/server`
+
+The URL `/$/server` returns details about the server and it's current status in JSON.
+
+@@details of JSON format.
+
+## Datasets and Services
+Pattern: `/$/datasets/`
+
+`/$/datasets/` is a container representing all datasets present in the server.
+`/$/datasets/*{name}*` names a specific dataset.
+
+### Backup
+Pattern: `/$/backup/*{name}*`
+
+> _Not implemented_
+
+This operation initiates a backup and returns. It returns, via the Location head (@@?)
+the location of a resource that can be used to monitor the backup operation. Backup
+operations run asynchronously and may take a long time.
+
+Backups are written to the sever local directory 'backups' as gzip-compressed N-Quads files.
+
+### Adding a Dataset and its Services.
+
+> _@@ May add server-managed templates_
+
+A dataset set can be added to a running server. There ae several methods
+for doing this:
+
+* Post the assembler file
+* HTML Form upload the assembler file
+* Use a built-in template (in-memory or persistent)
+
+All requite HTTP `POST`.
+
+Changes to the server state are carried across restarts.
+
+For persistent datasets, for example [TDB](/documentation/tdb),
+the dataset is persists across restart.
+
+For in-memory datasets, the dataset is rebuilt from it's description
+(this may include loading data from a file) but any changes are lost.
+
+#### Templates
+
+A short-cut form for some common set-ups is provided by <tt>POST</tt>ing with
+the following parameters (query string or HTMl form):
+
+| Parameter | |
+|-----------|-----------------|
+| `dbType` | Either `mem` or `tdb` |
+| `dbName` | URL path name |
+
+The dataset name must not be already in-use.
+
+Datasets are created in director `databases/`.
+
+
+The following alternative
+
+#### Assembler example
+
+The assembler description contains data and service. It can be sent by posting the assembler RDF graph
+in any RDF format or by posting from an HTML form (the syntax must be Turtle).
+
+The assembler file is stored by the server will be used on restart or when makign the datsset active again.
+
+> _@@_
+
+### Removing a Dataset
+
+Note: `DELETE` means "gone for ever". The dataset name and the details of its
+configuration are completely deleted and can not be recovered.
+
+The data of a TDB dataset is not deleted.
+
+### Active and Offline
+
+A dataset is in one of two modes: "active", meaning it is services request over HTTP
+(subject to configuration and security), or "offline", meaning the configuration and name
+is known about by the server but the dataset is not attached to the server. When "offline",
+any persistent data can be manipulated outside the server.
+
+Datasets are initially "active". The transition from "active" to "offline" is graceful - all outstanding requests are completed.
+
+## Statistics
+> **`/$/stats/*{name}*`**
+
+Statistics can be obtained for each dataset or all datasets in a single response.
+`/$/stats/` is treated as a container for this information.
+
+> _@@ stats details_
+> See [Fuseki Statistics](fuseki-stats.html) for details of statistics kept by a Fuseki server.
Added: jena/branches/jena-fuseki-new-ui/docs/fuseki-stats.md
URL: http://svn.apache.org/viewvc/jena/branches/jena-fuseki-new-ui/docs/fuseki-stats.md?rev=1560189&view=auto
==============================================================================
--- jena/branches/jena-fuseki-new-ui/docs/fuseki-stats.md (added)
+++ jena/branches/jena-fuseki-new-ui/docs/fuseki-stats.md Tue Jan 21 21:09:50 2014
@@ -0,0 +1,113 @@
+# Fuseki Service Statistics
+
+A Fuseki server keeps detailed statistics for each dataset and each service
+of a dataset keeps counters as to the number
+of incoming requests, number of successful requests, number of bad requests
+(i.e client errors), and number of failing requests (i.e. server errors).
+Statistics are returned as JSON. They are also available via JMX.
+
+## Structure of the Statistics Report
+
+### SPARQL Protolo Service
+
+Query and Update
+
+### SPARQL Graph Store Protocol
+
+inc extensions - dataset HTTP verbs.
+
+#### Other services.
+
+File upload.
+
+## Example
+
+ { "datasets" : {
+ "/ds" :
+ { "Requests" : 0 ,
+ "RequestsBad" : 0 ,
+ "RequestsGood" : 0 ,
+ "services" : {
+ "query" :
+ {"QueryExecErrors" : 0 ,
+ "QueryTimeouts" : 0 ,
+ "Requests" : 0 ,
+ "RequestsBad" : 0 ,
+ "RequestsGood" : 0 ,
+ "endpoints" : [
+ "query" ,
+ "sparql"
+ ]
+ } ,
+ "update" :
+ {"Requests" : 0 ,
+ "RequestsBad" : 0 ,
+ "RequestsGood" : 0 ,
+ "UpdateExecErrors" : 0 ,
+ "endpoints" : [ ]
+ } ,
+ "upload" :
+ {"Requests" : 0 ,
+ "RequestsBad" : 0 ,
+ "RequestsGood" : 0 ,
+ "endpoints" : [ ]
+ } ,
+
+ "gspRead" :
+ {"GSPdelete" : 0 ,
+ "GSPdeleteBad" : 0 ,
+ "GSPdeleteGood" : 0 ,
+ "GSPget" : 0 ,
+ "GSPgetBad" : 0 ,
+ "GSPgetGood" : 0 ,
+ "GSPhead" : 0 ,
+ "GSPheadBad" : 0 ,
+ "GSPheadGood" : 0 ,
+ "GSPoptions" : 0 ,
+ "GSPoptionsBad" : 0 ,
+ "GSPoptionsGood" : 0 ,
+ "GSPpatch" : 0 ,
+ "GSPpatchBad" : 0 ,
+ "GSPpatchGood" : 0 ,
+ "GSPpost" : 0 ,
+ "GSPpostBad" : 0 ,
+ "GSPpostGood" : 0 ,
+ "GSPput" : 0 ,
+ "GSPputBad" : 0 ,
+ "GSPputGood" : 0 ,
+ "Requests" : 0 ,
+ "RequestsBad" : 0 ,
+ "RequestsGood" : 0 ,
+ "endpoints" : [ "data" ]
+ } ,
+ "gspReadWrite" :
+ {"GSPdelete" : 0 ,
+ "GSPdeleteBad" : 0 ,
+ "GSPdeleteGood" : 0 ,
+ "GSPget" : 0 ,
+ "GSPgetBad" : 0 ,
+ "GSPgetGood" : 0 ,
+ "GSPhead" : 0 ,
+ "GSPheadBad" : 0 ,
+ "GSPheadGood" : 0 ,
+ "GSPoptions" : 0 ,
+ "GSPoptionsBad" : 0 ,
+ "GSPoptionsGood" : 0 ,
+ "GSPpatch" : 0 ,
+ "GSPpatchBad" : 0 ,
+ "GSPpatchGood" : 0 ,
+ "GSPpost" : 0 ,
+ "GSPpostBad" : 0 ,
+ "GSPpostGood" : 0 ,
+ "GSPput" : 0 ,
+ "GSPputBad" : 0 ,
+ "GSPputGood" : 0 ,
+ "Requests" : 0 ,
+ "RequestsBad" : 0 ,
+ "RequestsGood" : 0 ,
+ "endpoints" : [ ]
+ }
+ }
+ }
+ }
+ }