[RDF] Draft introduction to Commons RDF

classic Classic list List threaded Threaded
3 messages Options
Reply | Threaded
Open this post in threaded view
|

[RDF] Draft introduction to Commons RDF

Stian Soiland-Reyes
As raised in the recent vote, Commons RDF could do with an
introduction to RDF for people who have not used RDF before. The API
should be quite suitable for RDF beginners, as unlike say Jena or
Sesame they should not be so easily overwhelmed by the API size.


Here's my first attempt at such a tutorial:
http://commonsrdf.incubator.apache.org/introduction.html


Feedback welcome - particularly from Commons folks who don't know too
much about RDF!


Note that this tutorial does not yet go into the crucial part of
loadinh/save of RDF files, as that involves using the other RDF
implementations, which would require use of Maven for dependencies. I
thing a second tutorial could cover that aspect.

--
Stian Soiland-Reyes
http://orcid.org/0000-0001-9842-9718

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: [RDF] Draft introduction to Commons RDF

garydgregory
Well done sir! I am glad to finally see text like this.

I would start with concepts ("RDF resources") rather than the mechanics of
getting a project set up with an template Java file. At least that's me. As
soon as I say the first graph, I though "oh, I want to see that up front".

More of an API design question on the example:

System.out.println(alice.ntriplesString());

Why is the method not called toNtriplesString() or toNTriplesString()? What
does toString() do? Give me a "debug" string?

"*Note*: For simplicity this tutorial use *relative IRI references* which
are not really global identifiers. While this is supported by SimpleRDF,
some implementations will require *absolute IRIs* like <
http://example.com/Alice>."

It would like to know what the W3C standard says when I read text like the
above. In general I think it would be helpful to have a POV like "This text
adheres to the standard unless otherwise stated."

In this example:

<Alice> <knows> <Bob> .

What does the "." mean?

In the text:

You will get a compiler error:

RDFTerm cannot be converted to BlankNodeOrIRI

This and the follow up is confusing from a RDF novice POV. Starting by
describing an error makes understanding more difficult. Why do not a
"correct" walkthrough _fisrt_ instead of _starting_ with an error. Then at
the end, you can say, if you tried X, you'd get an error. By that point, it
will either be obvious to the reader or just a side note.

When I see:


   - The *subject* must be a BlankNodeOrIRI
   <https://commonsrdf.incubator.apache.org/apidocs/org/apache/commons/rdf/api/BlankNodeOrIRI.html>,
   that is either a BlankNode or IRI
   - The *predicate* must be a IRI
   <https://commonsrdf.incubator.apache.org/apidocs/org/apache/commons/rdf/api/IRI.html>
(so
   we can look up what it means)
   - The *object* must be a RDFTerm
   <https://commonsrdf.incubator.apache.org/apidocs/org/apache/commons/rdf/api/RDFTerm.html>,
   that is either a BlankNode, IRI or Literal

I want to see a diagram (maybe UML) that shows, if or how these types
relate to each other.

Again, more of an API design question:

if (! (aliceFriend instanceof BlankNodeOrIRI)) {
        continue;
    }


This feels hacky and at least needs a clarification:

- If something is not a BN or IRI, is it always a Literal?
- Why not have methods like isLiteral(), isBlankNode() and isIRI() that is
implemented in all the right places.

I think RDFTerm is the root interface but I am not 100% sure without
looking at the Javadoc. I'd like to have this made obvious in the text (see
above WRT a diagram).

I'd like an explanation on whether I can or cannot do:

Literal aliceRating = rdf.createLiteral(13.37f, Types.XSD_FLOAT);


That's 13.37f as opposed to "13.37".

As above, tells me if I can be more OO and say:

Literal footballInEnglish = rdf.createLiteral("football", Locale.ENGLISH);


I just skimmed through the rest, out of time, sorry.

Gary

On Mon, Nov 21, 2016 at 6:09 AM, Stian Soiland-Reyes <[hidden email]>
wrote:

> As raised in the recent vote, Commons RDF could do with an
> introduction to RDF for people who have not used RDF before. The API
> should be quite suitable for RDF beginners, as unlike say Jena or
> Sesame they should not be so easily overwhelmed by the API size.
>
>
> Here's my first attempt at such a tutorial:
> http://commonsrdf.incubator.apache.org/introduction.html
>
>
> Feedback welcome - particularly from Commons folks who don't know too
> much about RDF!
>
>
> Note that this tutorial does not yet go into the crucial part of
> loadinh/save of RDF files, as that involves using the other RDF
> implementations, which would require use of Maven for dependencies. I
> thing a second tutorial could cover that aspect.
>
> --
> Stian Soiland-Reyes
> http://orcid.org/0000-0001-9842-9718
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [hidden email]
> For additional commands, e-mail: [hidden email]
>
>


--
E-Mail: [hidden email] | [hidden email]
Java Persistence with Hibernate, Second Edition
<https://www.amazon.com/gp/product/1617290459/ref=as_li_tl?ie=UTF8&camp=1789&creative=9325&creativeASIN=1617290459&linkCode=as2&tag=garygregory-20&linkId=cadb800f39946ec62ea2b1af9fe6a2b8>

<http:////ir-na.amazon-adsystem.com/e/ir?t=garygregory-20&l=am2&o=1&a=1617290459>
JUnit in Action, Second Edition
<https://www.amazon.com/gp/product/1935182021/ref=as_li_tl?ie=UTF8&camp=1789&creative=9325&creativeASIN=1935182021&linkCode=as2&tag=garygregory-20&linkId=31ecd1f6b6d1eaf8886ac902a24de418%22>

<http:////ir-na.amazon-adsystem.com/e/ir?t=garygregory-20&l=am2&o=1&a=1935182021>
Spring Batch in Action
<https://www.amazon.com/gp/product/1935182951/ref=as_li_tl?ie=UTF8&camp=1789&creative=9325&creativeASIN=1935182951&linkCode=%7B%7BlinkCode%7D%7D&tag=garygregory-20&linkId=%7B%7Blink_id%7D%7D%22%3ESpring+Batch+in+Action>
<http:////ir-na.amazon-adsystem.com/e/ir?t=garygregory-20&l=am2&o=1&a=1935182951>
Blog: http://garygregory.wordpress.com
Home: http://garygregory.com/
Tweet! http://twitter.com/GaryGregory
Reply | Threaded
Open this post in threaded view
|

Re: [RDF] Draft introduction to Commons RDF

Bruno P. Kinoshita-3
In reply to this post by Stian Soiland-Reyes
Great work Stian! Completed the tutorial in the main page, and the code in the examples
works flawlessly. Kudos.


Tried to push at least the trivial changes to https://git-wip-us.apache.org/repos/asf/incubator-commonsrdf.git but got back a "remote: You are not authorized to edit this repository." error.


## Introduction


* In the first paragraph, the link to the Apache Commons RDF is pointing to /index.md, and causing a 404. Not sure if this is due to the way the site was built? But probably worth checking. The link in the third paragraph is wrong too. Instead of index.md, use index.html (tested locally).

* This:

"Don’t worry about this syntax, RDF is a model with several ways to represent it when saved to a file; the Commons RDF API directly reflects the RDF model in a syntax-neutral way."

Perhaps could be rewritten as

RDF is a model with several ways to represent it when saved to a file. The Commons RDF API directly reflects the RDF model in a syntax-neutral way. So do not worry about the syntax for now.

?

* I think there is a typo here:

"Note: Using .findFirst() will not returned the “first” recorded triple, as triples in a graph are not necessarily kept in order."

s/returned/return/

* Under Typed Literals, I think there is another trivial typo.

"RDF reuse the XSD datatypes."

s/reuse/reuses/

## Implementations (followed this link from the intro, just to take a quick look)

* The local link to external implementations is broken. It must be External_implementations instead of External-implementations

* Under Eclipse RDF4J, in the first paragraph, it says Eclispe.

* In the bottom, in the External implementations section, there is a link to a line in a source file in GitHub. As it may change, it is better to reference a commit. You can go to that screen, click on the line number again, and then hit the "y" key in your keyboard. That should redirect you to the current commit URL with the most recent version of that code.

Will take a look at the other sections later this week if I find some spare time.

Cheers
Bruno

>________________________________
> From: Stian Soiland-Reyes <[hidden email]>
>To: Commons Developers List <[hidden email]>
>Sent: Tuesday, 22 November 2016 3:09 AM
>Subject: [RDF] Draft introduction to Commons RDF
>
>
>As raised in the recent vote, Commons RDF could do with an
>introduction to RDF for people who have not used RDF before. The API
>should be quite suitable for RDF beginners, as unlike say Jena or
>Sesame they should not be so easily overwhelmed by the API size.
>
>
>Here's my first attempt at such a tutorial:
>http://commonsrdf.incubator.apache.org/introduction.html
>
>
>Feedback welcome - particularly from Commons folks who don't know too
>much about RDF!
>
>
>Note that this tutorial does not yet go into the crucial part of
>loadinh/save of RDF files, as that involves using the other RDF
>implementations, which would require use of Maven for dependencies. I
>thing a second tutorial could cover that aspect.
>
>--
>Stian Soiland-Reyes
>http://orcid.org/0000-0001-9842-9718
>
>---------------------------------------------------------------------
>To unsubscribe, e-mail: [hidden email]
>For additional commands, e-mail: [hidden email]
>
>
>
>

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]