commonsrdf-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From st...@apache.org
Subject incubator-commonsrdf git commit: COMMONSRDF-9: Example of usage
Date Thu, 23 Apr 2015 16:08:31 GMT
Repository: incubator-commonsrdf
Updated Branches:
  refs/heads/master 0a3076dac -> aae188614


COMMONSRDF-9: Example of usage


Project: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/commit/aae18861
Tree: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/tree/aae18861
Diff: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/diff/aae18861

Branch: refs/heads/master
Commit: aae1886140b026960b1be915a0ed460f3e66f8e0
Parents: 0a3076d
Author: Stian Soiland-Reyes <stain@apache.org>
Authored: Thu Apr 23 17:04:29 2015 +0100
Committer: Stian Soiland-Reyes <stain@apache.org>
Committed: Thu Apr 23 17:07:54 2015 +0100

----------------------------------------------------------------------
 src/site/markdown/examples.md | 141 +++++++++++++++++++++++++++++++++++++
 src/site/markdown/index.md    |   2 +
 src/site/site.xml             |   1 +
 3 files changed, 144 insertions(+)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/aae18861/src/site/markdown/examples.md
----------------------------------------------------------------------
diff --git a/src/site/markdown/examples.md b/src/site/markdown/examples.md
new file mode 100644
index 0000000..268f27a
--- /dev/null
+++ b/src/site/markdown/examples.md
@@ -0,0 +1,141 @@
+# Examples of using the Commons RDF API
+
+This page shows some examples of a client using the Commons RDF API.
+
+## Using Commons RDF from Maven
+
+To use Commons RDF API from an 
+[Apache Maven](http://maven.apache.org/) projects, 
+add the following dependency to your `pom.xml`:
+
+```xml
+<dependencies>
+    <dependency>
+        <groupId>org.apache.commons</groupId>
+        <artifactId>commons-rdf-api</artifactId>
+        <version>0.1-incubating-SNAPSHOT</version>
+    </dependency>
+</dependencies>
+```
+
+If you are using a `SNAPSHOT` version, then you will have to either build 
+Commons RDF from [source](https://github.com/apache/incubator-commonsrdf), or 
+add the [snapshot repository](https://github.com/apache/incubator-commonsrdf#snapshot-repository)
+
+In the examples below we will use the 
+[`simple` implementation](apidocs/org/apache/commons/rdf/simple/package-summary.html), but

+the examples should be equally applicable to other implementations. To add a dependency for
the
+`simple` implementation, add to your `pom.xml` section `<dependencies>`: 
+
+```xml
+    <dependency>
+        <groupId>org.apache.commons</groupId>
+        <artifactId>commons-rdf-simple</artifactId>
+        <version>0.1.0-incubating-SNAPSHOT</version>
+    </dependency>
+```
+
+
+## RDFTermFactory
+
+To create instances of Commons RDF interfaces like 
+[`Graph`](apidocs/org/apache/commons/rdf/api/Graph.html) and 
+[`IRI`](apidocs/org/apache/commons/rdf/api/IRI.html) you will need a
+[RDFTermFactory](/apidocs/org/apache/commons/rdf/api/RDFTermFactory.html).
+
+How to get an instance of this factory is implementation specific, for the
+`simple` implementation, you can construct the 
+[SimpleRDFTermFactory](apidocs/org/apache/commons/rdf/simple/SimpleRDFTermFactory.html):
+
+```java
+import org.apache.commons.rdf.api.RDFTermFactory;
+import org.apache.commons.rdf.simple.SimpleRDFTermFactory;
+// ..
+RDFTermFactory rdfTermFactory = new SimpleRDFTermFactory();
+```
+
+Using the factory you can create 
+any [RDFTerm](apidocs/org/apache/commons/rdf/api/RDFTerm.html), e.g. to create a
+[BlankNode](apidocs/org/apache/commons/rdf/api/BlankNode.html),
+[IRI](apidocs/org/apache/commons/rdf/api/IRI.html) and
+[Literal](apidocs/org/apache/commons/rdf/api/Literal.html):
+
+```java
+BlankNode blankNode = factory.createBlankNode();
+IRI iri = factory.createIRI("http://example.com/name");
+Literal literal = factory.createLiteral("Alice");
+```
+
+You can also create a stand-alone [Triple](apidocs/org/apache/commons/rdf/api/Triple.html):
+
+```java
+Triple triple = factory.createTriple(blankNode, iri, literal);
+```
+
+To keep your triples, you might want a [Graph](apidocs/org/apache/commons/rdf/api/Graph.html):
+
+```java
+Graph graph = factory.createGraph();
+```
+
+The [RDFTermFactory](apidocs/org/apache/commons/rdf/api/RDFTermFactory.html) also 
+contains more specific variants of some of the methods above, e.g. to create a
+typed literal.  
+
+Note that for any given implementation, `RDFTerm` instances need not be created
+using a `RDFTermFactory`. More likely, implementation-specific methods might create these

+objects as part of data parsing, storage lookup and queries.
+
+
+
+## Graph
+
+A [Graph](apidocs/org/apache/commons/rdf/api/Graph.html) is a collection of
+[Triple](apidocs/org/apache/commons/rdf/api/Triple.html)s.
+
+Given the [previous example](#RDFTermFactory), we can 
+[add](apidocs/org/apache/commons/rdf/api/Graph.html#add-org.apache.commons.rdf.api.Triple-)
+the `triple` to the `graph`:
+
+```java
+graph.add(triple);
+```
+
+And check that the graph 
+[contains](apidocs/org/apache/commons/rdf/api/Graph.html#contains-org.apache.commons.rdf.api.Triple-)

+the triple:
+
+```java
+System.out.println(graph.contains(triple));
+```
+> true
+
+As an alternative you can also use the expanded form of these methods:
+
+```java
+IRI bob = factory.createIRI("http://example.com/bob");
+Literal bobName = factory.createLiteral("Bob");
+graph.add(bob, iri, bobName);
+```
+
+and
+
+```java
+System.out.println(graph.contains(null, iri, bobName));
+```
+> true
+
+Notice that the 
+expanded [Graph.contains()](apidocs/org/apache/commons/rdf/api/Graph.html#contains-org.apache.commons.rdf.api.BlankNodeOrIRI-org.apache.commons.rdf.api.IRI-org.apache.commons.rdf.api.RDFTerm-)
+allow `null` as a wildcard parameters.
+
+
+
+
+**TODO:** Remaining Graph operations, incl. `getTriples()` streams
+
+**TODO:** [Types](apidocs/org/apache/commons/rdf/simple/Types.html)
+
+**TODO:** Methods on `Literal`, `IRI`, `BlankNode` etc.
+
+**TODO:** Serialize as n-triples example
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/aae18861/src/site/markdown/index.md
----------------------------------------------------------------------
diff --git a/src/site/markdown/index.md b/src/site/markdown/index.md
index a41bdb4..a08327b 100644
--- a/src/site/markdown/index.md
+++ b/src/site/markdown/index.md
@@ -60,6 +60,8 @@ a W3C Recommendation published on 25 February 2014. The idea is that Commons
RDF
 will provide a common library for RDF 1.1 that could be implemented by systems 
 on the Java Virtual Machine, allowing the portability across different implementations.
 
+See the [examples](examples.html) for how to interact with these interfaces.
+
 ## Modules
 
 The project is actually composed by two modules:

http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/aae18861/src/site/site.xml
----------------------------------------------------------------------
diff --git a/src/site/site.xml b/src/site/site.xml
index 170e32f..82390d0 100644
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -55,6 +55,7 @@
     <menu name="Project">
       <item name="Home"                 href="/index.html" />
       <item name="API"                  href="/apidocs/index.html?org/apache/commons/rdf/api/package-summary.html"
/>
+      <item name="Examples"             href="/examples.html" />       
       <item name="Download"             href="/download.html" />
       <item name="Contributing"         href="/contributing.html" />
       <item name="Team"                 href="/team-list.html" />


Mime
View raw message