You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commonsrdf.apache.org by st...@apache.org on 2016/11/21 14:02:13 UTC
[1/3] incubator-commonsrdf git commit: about Blank Nodes and literals
Repository: incubator-commonsrdf
Updated Branches:
refs/heads/master 567b775be -> c6c4cbfcf
about Blank Nodes and literals
Project: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/commit/ba779e35
Tree: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/tree/ba779e35
Diff: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/diff/ba779e35
Branch: refs/heads/master
Commit: ba779e356ed985edf549453b943a601a354aad88
Parents: 567b775
Author: Stian Soiland-Reyes <st...@apache.org>
Authored: Mon Nov 21 13:43:27 2016 +0000
Committer: Stian Soiland-Reyes <st...@apache.org>
Committed: Mon Nov 21 13:43:27 2016 +0000
----------------------------------------------------------------------
src/site/markdown/introduction.md | 264 ++++++++++++++++++++++++++++++++-
1 file changed, 260 insertions(+), 4 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/ba779e35/src/site/markdown/introduction.md
----------------------------------------------------------------------
diff --git a/src/site/markdown/introduction.md b/src/site/markdown/introduction.md
index d494562..9d9530b 100644
--- a/src/site/markdown/introduction.md
+++ b/src/site/markdown/introduction.md
@@ -377,7 +377,263 @@ for (Triple triple : graph.iterate(alice, knows, null)) {
## Literal values
-We talked briefly about literals above as a way to represent values in RDF.
-What is a value? In a way you could a value is when we no longer want to
-stay in graph land and just want to use primitive types like `long`,
-`int` or `String`.
+We talked briefly about literals above as a way to represent _values_ in RDF.
+What is a literal value? In a way you could think of a value as when you no longer
+want to stay in graph-land of related resources, and just want to use primitive
+types like `float`, `int` or `String` to represent values like
+a player rating, the number of matches played, or the full name of a person
+(including spaces and punctuation which don't work well in an identifier).
+
+Such values are in Commons RDF represented as instances of `Literal`,
+which we can create using `rdf.createLiteral(..)`. Strings are easy:
+
+```java
+Literal aliceName = rdf.createLiteral("Alice W. Land");
+```
+
+We can then add a triple that relates the resource `<Alice>`
+to this value, let's use a new predicate `<name>`:
+
+```java
+IRI name = rdf.createIRI("name");
+graph.add(alice, name, aliceName);
+```
+
+When you look up literal properties in a graph,
+take care that in RDF a property is not necessarily _functional_, that is,
+it would be perfectly valid RDF-wise for a person to have multiple names;
+Alice might also have a `<name> "Alice Land"`. Instead of using
+`graph.iterate()` and `break` in a for-loop, it might be easier to use the
+Java 8 `Stream` returned from `.stream()` together with `.findAny()`
+- which return an `Optional` in case there is no `<name>`:
+
+```java
+System.out.println(graph.stream(alice, name, null).findAny());
+```
+
+> `Optional[<Alice> <name> "Alice W. Land" .]``
+
+**Note:** Using `.findFirst()` will not returned the "first"
+recorded triple, as triples in a graph are not necessarily
+kept in order.
+
+You can use `optional.isPresent()` and `optional.get()` to check if a
+`Triple` matched the graph stream pattern:
+
+```java
+Optional<? extends Triple> nameTriple = graph.stream(alice, name, null).findAny();
+if (nameTriple.isPresent()) {
+ System.out.println(nameTriple.get());
+}
+```
+
+If you feel adventerous, you can try the
+[Java 8 functional programming](http://www.oracle.com/webfolder/technetwork/tutorials/obe/java/Lambda-QuickStart/index.html)
+style to work with of `Stream` and `Optional` and get the literal value unquoted:
+
+```java
+graph.stream(alice, name, null)
+ .findAny().map(Triple::getObject)
+ .filter(obj -> obj instanceof Literal)
+ .map(literalName -> ((Literal)literalName).getLexicalForm())
+ .ifPresent(System.out::println);
+```
+
+> `Alice W. Land`
+
+Notice how we here used a `.filter` to skip any non-`Literal` names
+(which would not have the `.getLexicalForm()` method).
+
+
+
+### Typed literals
+
+Non-String value types are represented in RDF as _typed literals_;
+which is similar to (but not the same as) Java native types. A
+typed literal is a combination of a _string representation_
+(e.g. "13.37") and a data type IRI, e.g. `<http://www.w3.org/2001/XMLSchema#float>`.
+RDF reuse the XSD datatypes.
+
+A collection of the standardized datatype `IRI`s
+are provided in Simple's [Types](apidocs/org/apache/commons/rdf/simple/Types.html)
+class, which we can use with `createLiteral` by adding the corresponding `import`:
+
+```java
+import org.apache.commons.rdf.simple.Types;
+// ...
+IRI playerRating = rdf.createIRI("playerRating");
+Literal aliceRating = rdf.createLiteral("13.37", Types.XSD_FLOAT);
+graph.add(alice, playerRating, aliceRating);
+```
+
+Note that Commons RDF does not currently provide converters
+from/to native Java data types and the RDF string representations.
+
+### Language-specific literals
+
+We live in a globalized world, with many spoken and written languages.
+While we can often agree about a concept like `<Football>`, different
+languages might call it differently. The distinction in RDF
+between identified resources and literal values, mean we can represent
+names or labels for the same thing.
+
+Rather than introducing language-specific predicates like
+`<name_in_english>` and `<name_in_norwegian>`
+it is usually better in RDF to use _language-typed literals_:
+
+```java
+Literal footballInEnglish = rdf.createLiteral("football", "en");
+Literal footballInNorwegian = rdf.createLiteral("fotball", "no");
+
+graph.add(football, name, footballInEnglish);
+graph.add(football, name, footballInNorwegian);
+```
+
+The language tags like `"en"` and `"no"` are
+identified by [BCP47](https://tools.ietf.org/html/bcp47) - you can't just make
+up your own but must use one that matches the language. It is possible to use
+localized languages as well, e.g.
+
+```java
+Literal footballInAmericanEnglish = rdf.createLiteral("soccer", "en-US");
+graph.add(football, name, footballInAmericanEnglish);
+```
+
+Note that Commons RDF does not currently provide constants for
+the standardized languages or methods to look up localized languages.
+
+## Blank nodes - when you don't know the identity
+
+Sometimes you don't know the identity of a resource. This can be the case
+where you know the _existence_ of a resource, similar to "someone" or "some"
+in English. For instance,
+
+```turtle
+<Charlie> <knows> _:someone .
+_:someone <plays> <Football> .
+```
+
+We don't know who this `_:someone` is, it could be `<Bob>` (which we know
+plays football), it could be someone else, even `<Alice>`
+(we don't know that she doesn't play football).
+
+In RDF we represent `_:someone` as a _blank node_ - it's a resource without
+a global identity. Different RDF files can all talk about `_:blanknode`, but they
+would all be different resources. Crucially, a blank node can be used
+in multiple triples within the same graph, so that we can relate
+a subject to a blank node resource, and then describe that resource (usually incomplete).
+
+Let's add the blank node statements to our graph:
+
+```turtle
+BlankNode someone = rdf.createBlankNode();
+graph.add(charlie, knows, someone);
+graph.add(someone, plays, football);
+BlankNode someoneElse = rdf.createBlankNode();
+graph.add(charlie, knows, someoneElse);
+```
+
+Every call to `rdf.createBlankNode()` creates a new, unrelated blank node
+with an internal identifier. Let's have a look:
+
+```java
+for (Triple heKnows : graph.iterate(charlie, knows, null)) {
+ if (! (heKnows.getObject() instanceof BlankNodeOrIRI)) {
+ continue;
+ }
+ BlankNodeOrIRI who = (BlankNodeOrIRI)heKnows.getObject();
+ System.out.println("Charlie knows "+ who);
+ for (Triple whoPlays : graph.iterate(who, plays, null)) {
+ System.out.println(" who plays " + whoPlays.getObject());
+ }
+}
+```
+
+> `Charlie knows _:ae4115fb-86bf-3330-bc3b-713810e5a1ea` <br>
+> ` who plays <Football>` <br>
+> `Charlie knows _:884d5c05-93a9-3709-b655-4152c2e51258`
+
+As we see above, given a `BlankNode` instance it is perfectly
+valid to ask the same `Graph` about further triples
+relating to the `BlankNode`.
+
+### Blank node labels
+
+In Commons RDF it is also possible to create a blank node from a
+_name_ - which can be useful if you don't want to keep (or look up)
+the `BlankNode` instance to later add statements about the same node.
+
+Let's first delete the old BlankNode statements:
+
+```java
+graph.remove(null,null,someone);
+graph.remove(someone,null,null);
+```
+
+And now we'll try an alternate approach:
+
+```java
+// no Java variable for the new BlankNode instance
+graph.add(charlie, knows, rdf.createBlankNode("someone"));
+// at any point later (with the same RDF instance)
+graph.add(rdf.createBlankNode("someone"), plays, football);
+```
+
+
+Running the `"Charlie knows"` query again should still work, but now
+return a different identifier.
+
+
+> `Charlie knows _:5e2a75b2-33b4-3bb8-b2dc-019d42c2215a` <br>
+> ` who plays <Football>` <br>
+> `Charlie knows _:884d5c05-93a9-3709-b655-4152c2e51258`
+
+
+You may notice that with `SimpleRDF` the string `"someone"` does not
+survive into the string representation of the `BlankNode` label `_:someone`,
+other `RDF` implementations may support that.
+
+Note that it needs to be the same `RDF` instance to recreate
+the same _"someone"_ `BlankNode`. This is a Commons RDF-specific behaviour to improve
+cross-graph compatibility, other RDF frameworks may save the blank node using
+the provided name as a blank node label, which in some cases
+could cause collisions (but perhaps more readable output).
+
+
+### Open world assumption
+
+How to interpret a blank node depends on the assumptions you build into your
+RDF application - it could be thought of as a logical "there exists a resource that.."
+or a more pragmatic "I don't know/care about the resource's IRI". Blank nodes can be
+useful if your RDF model describes intermediate resources like
+"a person's membership of an organization" or "a participant's result in a race"
+which it often is not worth maintaining identifiers for.
+
+It is common on the semantic web to use the
+[open world assumption](http://wiki.opensemanticframework.org/index.php/Overview_of_the_Open_World_Assumption) -
+if it is not stated as a _triple_ in your graph, then you don't know if
+something is is true or false,
+for instance if `<Alice> <plays> <Football> .`
+
+Note that the open world assumption applies both to `IRI`s and `BlankNode`s,
+that is, you can't necessarily assume that the
+resources `<Alice>` and `<Charlie>` describe
+two different people just because they have
+two different identifiers - in fact it is very common that different systems use
+different identifiers to describe the same (or pretty much the same) thing in the
+real world.
+
+It is however common for applications to
+"close the world"; saying "given this information I have
+gathered as RDF, I'll assume these resources are all separate things in the world,
+then do I then know if `<Alice> <plays> <Football>` is false?".
+
+Using logical _inference rules_ and _ontologies_
+is one method to get stronger assumptions and conclusions.
+Note that building good rules or ontologies requires a fair
+bit more knowledge than what can be conveyed in this short tutorial.
+
+It is out of scope for Commons RDF to support the many ways to deal with
+logical assumptions and conclusions, however you may find interest in using
+[Jena implementation](implementations.html#Apache_Jena)
+combined with Jena's [ontology API](https://jena.apache.org/documentation/ontology/).
[3/3] incubator-commonsrdf git commit: clarificatoins
Posted by st...@apache.org.
clarificatoins
Project: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/commit/c6c4cbfc
Tree: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/tree/c6c4cbfc
Diff: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/diff/c6c4cbfc
Branch: refs/heads/master
Commit: c6c4cbfcfc2feb58ad1cb9607a69c663526adfe0
Parents: e2af2a5
Author: Stian Soiland-Reyes <st...@apache.org>
Authored: Mon Nov 21 14:02:02 2016 +0000
Committer: Stian Soiland-Reyes <st...@apache.org>
Committed: Mon Nov 21 14:02:02 2016 +0000
----------------------------------------------------------------------
src/site/markdown/introduction.md | 39 ++++++++++++++++++----------------
1 file changed, 21 insertions(+), 18 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/c6c4cbfc/src/site/markdown/introduction.md
----------------------------------------------------------------------
diff --git a/src/site/markdown/introduction.md b/src/site/markdown/introduction.md
index 76571f1..6d731e0 100644
--- a/src/site/markdown/introduction.md
+++ b/src/site/markdown/introduction.md
@@ -224,7 +224,7 @@ than `<Bob>` or `<Tennis>`.
It is therefore possible to _query_ the graph, such as _"Who plays Tennis?_ or
_"Who does Alice know?"_, but also more complex, like
-_"Does Alice anyone that plays Football?"_.
+_"Does Alice know anyone that plays Football?"_.
Let's try that now using Commons RDF. To keep the triples we'll need a `Graph`:
@@ -305,7 +305,7 @@ for (Triple triple : graph.iterate(alice, knows, null)) {
Let's try to look up which of those friends play football:
```java
-System.out.println("Does Alice anyone that plays Football?");
+System.out.println("Does Alice know anyone that plays Football?");
for (Triple triple : graph.iterate(alice, knows, null)) {
RDFTerm aliceFriend = triple.getObject();
if (graph.contains(aliceFriend, plays, football)) {
@@ -360,7 +360,7 @@ check (skipping any literals) and cast to `BlankNodeOrIRI`:
```java
-System.out.println("Does Alice anyone that plays Football?");
+System.out.println("Does Alice know anyone that plays Football?");
for (Triple triple : graph.iterate(alice, knows, null)) {
RDFTerm aliceFriend = triple.getObject();
if (! (aliceFriend instanceof BlankNodeOrIRI)) {
@@ -372,7 +372,7 @@ for (Triple triple : graph.iterate(alice, knows, null)) {
}
```
-> `Does Alice anyone that plays Football?` <br />
+> `Does Alice know anyone that plays Football?` <br />
> `Yes, <Bob>`
## Literal values
@@ -522,9 +522,9 @@ In RDF we represent `_:someone` as a _blank node_ - it's a resource without
a global identity. Different RDF files can all talk about `_:blanknode`, but they
would all be different resources. Crucially, a blank node can be used
in multiple triples within the same graph, so that we can relate
-a subject to a blank node resource, and then describe that resource (usually incomplete).
+a subject to a blank node resource, and then describe the blank node further.
-Let's add the blank node statements to our graph:
+Let's add some blank node statements to our graph:
```turtle
BlankNode someone = rdf.createBlankNode();
@@ -556,15 +556,16 @@ for (Triple heKnows : graph.iterate(charlie, knows, null)) {
As we see above, given a `BlankNode` instance it is perfectly
valid to ask the same `Graph` about further triples
-relating to the `BlankNode`.
+relating to the `BlankNode`. (Asking any other graph will probably
+not give any results).
### Blank node labels
In Commons RDF it is also possible to create a blank node from a
-_name_ - which can be useful if you don't want to keep (or look up)
+_name_ or _label_ - which can be useful if you don't want to keep or retrieve
the `BlankNode` instance to later add statements about the same node.
-Let's first delete the old BlankNode statements:
+Let's first delete the old `BlankNode` statements:
```java
graph.remove(null,null,someone);
@@ -581,8 +582,9 @@ graph.add(rdf.createBlankNode("someone"), plays, football);
```
-Running the `"Charlie knows"` query again should still work, but now
-return a different identifier.
+Running the `"Charlie knows"` query again (try making it into a function)
+should still work, but now return a different label for the football
+player:
> `Charlie knows _:5e2a75b2-33b4-3bb8-b2dc-019d42c2215a` <br />
@@ -590,15 +592,16 @@ return a different identifier.
> `Charlie knows _:884d5c05-93a9-3709-b655-4152c2e51258`
-You may notice that with `SimpleRDF` the string `"someone"` does not
-survive into the string representation of the `BlankNode` label `_:someone`,
-other `RDF` implementations may support that.
+You may notice that with `SimpleRDF` the string `"someone"` does **not**
+survive into the string representation of the `BlankNode` label as `_:someone`,
+that is because unlike `IRI`s the label of a blank node carries no meaning
+and does not need to be preserved.
Note that it needs to be the same `RDF` instance to recreate
-the same _"someone"_ `BlankNode`. This is a Commons RDF-specific behaviour to improve
-cross-graph compatibility, other RDF frameworks may save the blank node using
-the provided name as a blank node label, which in some cases
-could cause collisions (but perhaps more readable output).
+the same _"someone"_ `BlankNode`. This is a Commons RDF-specific
+behaviour to improve cross-graph compatibility, other RDF frameworks may save
+the blank node using the provided label as-is with a `_:` prefix,
+which in some cases could cause collisions (but perhaps more readable output).
### Open world assumption
[2/3] incubator-commonsrdf git commit: now valid markdown / xhtml
Posted by st...@apache.org.
now valid markdown / xhtml
Project: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/commit/e2af2a57
Tree: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/tree/e2af2a57
Diff: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/diff/e2af2a57
Branch: refs/heads/master
Commit: e2af2a573c0d61eab5a90499f57ac25f0ceb2110
Parents: ba779e3
Author: Stian Soiland-Reyes <st...@apache.org>
Authored: Mon Nov 21 13:53:36 2016 +0000
Committer: Stian Soiland-Reyes <st...@apache.org>
Committed: Mon Nov 21 13:53:36 2016 +0000
----------------------------------------------------------------------
src/site/markdown/introduction.md | 31 ++++++++++++++++---------------
1 file changed, 16 insertions(+), 15 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/e2af2a57/src/site/markdown/introduction.md
----------------------------------------------------------------------
diff --git a/src/site/markdown/introduction.md b/src/site/markdown/introduction.md
index 9d9530b..76571f1 100644
--- a/src/site/markdown/introduction.md
+++ b/src/site/markdown/introduction.md
@@ -183,8 +183,8 @@ System.out.println(aliceKnowsBob.getPredicate().ntriplesString());
System.out.println(aliceKnowsBob.getObject().ntriplesString());
```
-> `<Alice>` <br>
-> `<knows>` <br>
+> `<Alice>` <br />
+> `<knows>` <br />
> `<Bob>`
_**Tip**: Instances from `SimpleRDF` can be printed directly, as
@@ -270,8 +270,8 @@ for (Triple triple : graph.iterate(null, plays, tennis)) {
}
```
-> `Who plays Tennis?` <br>
-> `<Alice>` <br>
+> `Who plays Tennis?` <br />
+> `<Alice>` <br />
> `<Charlie>`
@@ -298,8 +298,8 @@ for (Triple triple : graph.iterate(alice, knows, null)) {
}
```
-> `Who does Alice know?` <br>
-> `<Bob>` <br>
+> `Who does Alice know?` <br />
+> `<Bob>` <br />
> `<Charlie>`
Let's try to look up which of those friends play football:
@@ -344,7 +344,7 @@ As we are retrieving triples from the graph, the `triple.getObject()` is only kn
to be an RDFTerm if we use it as a Java variable - there could in theory be triples
in the graph with `Literal` and `BlankNode` objects:
-```
+```turtle
<Alice> <knows> "Santa Claus".
<Alice> <knows> _:someone.
```
@@ -372,7 +372,7 @@ for (Triple triple : graph.iterate(alice, knows, null)) {
}
```
-> `Does Alice anyone that plays Football?`
+> `Does Alice anyone that plays Football?` <br />
> `Yes, <Bob>`
## Literal values
@@ -402,8 +402,9 @@ graph.add(alice, name, aliceName);
When you look up literal properties in a graph,
take care that in RDF a property is not necessarily _functional_, that is,
it would be perfectly valid RDF-wise for a person to have multiple names;
-Alice might also have a `<name> "Alice Land"`. Instead of using
-`graph.iterate()` and `break` in a for-loop, it might be easier to use the
+Alice might also be called _"Alice Land"_.
+
+Instead of using `graph.iterate()` and `break` in a for-loop, it might be easier to use the
Java 8 `Stream` returned from `.stream()` together with `.findAny()`
- which return an `Optional` in case there is no `<name>`:
@@ -411,7 +412,7 @@ Java 8 `Stream` returned from `.stream()` together with `.findAny()`
System.out.println(graph.stream(alice, name, null).findAny());
```
-> `Optional[<Alice> <name> "Alice W. Land" .]``
+> `Optional[<Alice> <name> "Alice W. Land" .]`
**Note:** Using `.findFirst()` will not returned the "first"
recorded triple, as triples in a graph are not necessarily
@@ -549,8 +550,8 @@ for (Triple heKnows : graph.iterate(charlie, knows, null)) {
}
```
-> `Charlie knows _:ae4115fb-86bf-3330-bc3b-713810e5a1ea` <br>
-> ` who plays <Football>` <br>
+> `Charlie knows _:ae4115fb-86bf-3330-bc3b-713810e5a1ea` <br />
+> ` who plays <Football>` <br />
> `Charlie knows _:884d5c05-93a9-3709-b655-4152c2e51258`
As we see above, given a `BlankNode` instance it is perfectly
@@ -584,8 +585,8 @@ Running the `"Charlie knows"` query again should still work, but now
return a different identifier.
-> `Charlie knows _:5e2a75b2-33b4-3bb8-b2dc-019d42c2215a` <br>
-> ` who plays <Football>` <br>
+> `Charlie knows _:5e2a75b2-33b4-3bb8-b2dc-019d42c2215a` <br />
+> ` who plays <Football>` <br />
> `Charlie knows _:884d5c05-93a9-3709-b655-4152c2e51258`