Merge pull request #54 from stain/patch-1
Markdown typo, http to https
diff --git a/source/documentation/permissions/evaluator.md b/source/documentation/permissions/evaluator.md
index bb46447..8687d56 100644
--- a/source/documentation/permissions/evaluator.md
+++ b/source/documentation/permissions/evaluator.md
@@ -8,6 +8,8 @@
**NOTE** The permissions system caches intermediate results and will only call the evaluator if the answer is not already in the cache. There is little or no advantage to implementing caching in the SecurityEvaluator itself.
+**NOTE** In earlier versions ReadDeniedException was thrown whenever read permissions were not granted. The current version defines a `isHardReadError` method that defines what action should be taken. **The default implementation has changed**. See Configuration Methods section below for information.
+
### Actions
Principals may perform Create, Read, Update or Delete operations on secured resources. These operations are defined in the `Action` enum in the SecurityEvaluator interface.
@@ -54,6 +56,13 @@
public Object getPrincipal() throws AuthenticationRequiredException;
Return the current principal or null if there is no current principal.
+### Configuration Methods
+
+The evaluator has one configuration method.
+
+ public default boolean isHardReadError()
+This method determines how the system will deal with read denied restrictions when attempting to create iterators, counts, or perform existential checks. If set `true` the system will throw a `ReadDeniedException`. This is the action that was perfomed in Jena version 3 and earlier. If set `false`, the default, methods that return iterators return empty iterators, methods that perform existential checks return `false`, and methods that return counts return 0 (zero).
+
## Sample Implementation
This sample is for a graph that contains a set of messages, access to the messages are limited to
@@ -67,13 +76,13 @@
<!-- language: lang-java -->
public class ExampleEvaluator implements SecurityEvaluator {
-
+
private Principal principal;
private Model model;
private RDFNode msgType = ResourceFactory.createResource( "http://example.com/msg" );
private Property pTo = ResourceFactory.createProperty( "http://example.com/to" );
private Property pFrom = ResourceFactory.createProperty( "http://example.com/from" );
-
+
/**
*
* @param model The graph we are going to evaluate against.
@@ -82,13 +91,13 @@
{
this.model = model;
}
-
+
@Override
public boolean evaluate(Object principal, Action action, Node graphIRI) {
// we allow any action on a graph.
return true;
}
-
+
// not that in this implementation all permission checks flow through
// this method. We can do this because we have a simple permissions
// requirement. A more complex set of permissions requirement would
@@ -104,7 +113,7 @@
{
throw new AuthenticationRequiredException();
}
-
+
// a message is only available to sender or recipient
if (r.hasProperty( RDF.type, msgType ))
{
@@ -113,7 +122,7 @@
}
return true;
}
-
+
// evaluate a node.
private boolean evaluate( Object principal, Node node )
{
@@ -122,55 +131,55 @@
// to be explicitly checked.
return false;
}
-
+
// if the node is a URI or a blank node evaluate it as a resource.
if (node.isURI() || node.isBlank()) {
- Resource r = model.getRDFNode( node ).asResource();
- return evaluate( principal, r );
- }
-
+ Resource r = model.getRDFNode( node ).asResource();
+ return evaluate( principal, r );
+ }
+
return true;
}
-
+
// evaluate the triple by evaluating the subject, predicate and object.
private boolean evaluate( Object principal, Triple triple ) {
return evaluate( principal, triple.getSubject()) &&
evaluate( principal, triple.getObject()) &&
evaluate( principal, triple.getPredicate());
}
-
+
@Override
public boolean evaluate(Object principal, Action action, Node graphIRI, Triple triple) {
return evaluate( principal, triple );
}
-
+
@Override
public boolean evaluate(Object principal, Set<Action> actions, Node graphIRI) {
return true;
}
-
+
@Override
public boolean evaluate(Object principal, Set<Action> actions, Node graphIRI,
Triple triple) {
return evaluate( principal, triple );
}
-
+
@Override
public boolean evaluateAny(Object principal, Set<Action> actions, Node graphIRI) {
return true;
}
-
+
@Override
public boolean evaluateAny(Object principal, Set<Action> actions, Node graphIRI,
Triple triple) {
return evaluate( principal, triple );
}
-
+
@Override
public boolean evaluateUpdate(Object principal, Node graphIRI, Triple from, Triple to) {
return evaluate( principal, from ) && evaluate( principal, to );
}
-
+
public void setPrincipal( String userName )
{
if (userName == null)
@@ -179,7 +188,7 @@
}
principal = new BasicUserPrincipal( userName );
}
-
+
@Override
public Principal getPrincipal() {
return principal;
diff --git a/source/documentation/tools/__index.md b/source/documentation/tools/__index.md
index b5ef3e3..4ff759d 100644
--- a/source/documentation/tools/__index.md
+++ b/source/documentation/tools/__index.md
@@ -63,3 +63,75 @@
[1]: https://github.com/apache/jena/tree/main/apache-jena/bat/
+### Command Line Tools Quick Reference
+
+#### riot and Related
+
+See [Reading and Writing RDF in Apache Jena](https://jena.apache.org/documentation/io/) for more information.
+
+- **`riot`**: parse RDF data, guessing the syntax from the file extension. Assumes that standard input is N-Quads/N-Triples unless
+you tell it otherwise with the `--syntax` parameter. `riot` can also do RDFS [inferencing](https://jena.apache.org/documentation/inference/), count triples, convert serializations,
+validate syntax, concatenate datasets, and more.
+
+- **`turtle`**, **`ntriples`**, **`nquads`**, **`trig`**, **`rdfxml`**: specialized versions of `riot` that assume that the input is in the named serialization.
+
+- **`rdfparse`**: parse an RDF/XML document, for which you can usually just use `riot`, but this can also pull triples out of `rdf:RDF` elements
+embedded at arbitrary places in an XML document if you need to deal with those.
+
+#### SPARQL Queries on Local Files and Endpoints
+
+See [ARQ - Command Line Applications](https://jena.apache.org/documentation/query/cmds.html) for more about these.
+
+- **`arq`** and **`sparql`**: run a query in a file named as a command line parameter on a dataset in one or more files named as command line parameters.
+
+- **`qparse`**: parse a query, report on any problems, and output a pretty-printed version of the query.
+
+- **`uparse`**: do the same thing as `qparse` but for update requests.
+
+- **`rsparql`**: send a local query to a SPARQL endpoint specified with a URL, giving you the same choice of output formats
+that `arq` does.
+
+- **`rupdate`**: send a local update query to a SPARQL endpoint specified with a URL, assuming that is accepting updates from you.
+
+#### Querying and Manipulating Fuseki Datasets
+
+The following utilities let you work with data stored using a local
+[Fuseki](https://jena.apache.org/documentation/fuseki2/) triplestore. They can
+be useful for automating queries and updates of data stored there. Each
+requires an [assembler file](https://jena.apache.org/documentation/assembler/assembler-howto.html)
+pointing at a dataset as a parameter; Fuseki creates these for you.
+
+For each pair of utilities shown, the first is used with data stored using the TDB format and the
+second with data stored using the newer and more efficient TDB2 format.
+
+The [TDB](https://jena.apache.org/documentation/tdb/) and [TDB2 - Command Line Tools](https://jena.apache.org/documentation/tdb2/tdb2_cmds.html)
+pages describe these further.
+
+- **`tdbquery`**, **`tdb2.tdbquery`**: query a dataset that has been stored with Fuseki.
+
+- **`tdbdump`**, **`tdb2.tdbdump`**: dump the contents of a Fuseki dataset to standard out.
+
+- **`tdbupdate`**, **`tdb2.tdbupdate`**: run an update request against a Fuseki dataset.
+
+- **`tdbloader`**, **`tdb2.tdbloader`**: load a data from a file into a Fuseki dataset.
+
+- **`tdbstats`**, **`tdb2.tdbstats`**: output a short report of information about a Fuseki dataset.
+
+- **`tdbbackup`**, **`tdb2.tdbbackup`**: create a gzipped copy of the Fuseki dataset's triples.
+
+- **`tdbcompact`**, **`tdb2.tdbcompact`**: reduce the size of the Fuseki dataset.
+
+
+
+#### Other Handy Command Line Tools
+
+- **`shacl`**: validate a dataset against a set of shapes and constraints described in a
+file that conforms to the W3C [SHACL](https://www.w3.org/TR/shacl/) standard.
+Jena's [SHACL](https://jena.apache.org/documentation/shacl/) page has more on this utility.
+
+- **`rdfdiff`**: compare the triples in two datasets, regardless of their serializations, and list
+which are different between the two datasets. (Modeled on the UNIX `diff` utility.)
+
+- **`iri`**: Parse a IRI and tell you about it, with errors and warnings. Good for
+checking for issues like proper escaping.
+
