svn commit: r1642102 - /jena/site/trunk/content/documentation/hadoop/common.mdtext

[rv...@apache.org]

Author: rvesse
Date: Thu Nov 27 11:31:46 2014
New Revision: 1642102

URL: http://svn.apache.org/r1642102
Log:
Flesh our Common API page for RDF Tools for Hadoop documentation

Modified:
    jena/site/trunk/content/documentation/hadoop/common.mdtext

Modified: jena/site/trunk/content/documentation/hadoop/common.mdtext
URL: http://svn.apache.org/viewvc/jena/site/trunk/content/documentation/hadoop/common.mdtext?rev=1642102&r1=1642101&r2=1642102&view=diff
==============================================================================
--- jena/site/trunk/content/documentation/hadoop/common.mdtext (original)
+++ jena/site/trunk/content/documentation/hadoop/common.mdtext Thu Nov 27 11:31:46 2014
@@ -8,7 +8,7 @@ Currently we represent the three main RD
 
 ## Nodes
 
-The `Writable` type for nodes is predictably enough called `NodeWritable` and it implements the `WritableComparable` interface which means it can be used as both a key and/or value in Map/Reduce.  In standard Hadoop style a `get()` method returns the actual value as a Jena `Node` instance while a corresponding `set()` method allows the value to be set.
+The `Writable` type for nodes is predictably enough called `NodeWritable` and it implements the `WritableComparable` interface which means it can be used as both a key and/or value in Map/Reduce.  In standard Hadoop style a `get()` method returns the actual value as a Jena `Node` instance while a corresponding `set()` method allows the value to be set.  Coveying `null` values is acceptable and fully supported.
 
 Note that nodes are lazily converted to and from the underlying binary representation so there is minimal overhead if you create a `NodeWritable` instance that does not actually ever get read/written.
 
@@ -16,21 +16,31 @@ Note that nodes are lazily converted to 
 
 However the downside of this is that the sort order for nodes may not be as natural as the sort order using POJOs or when sorting with SPARQL.  Ultimately this is a performance trade off and in our experiments the benefits far outweigh the lack of a more natural sort order.
 
+You simply use it as follows
+
+    NodeWritable nw = new NodeWritable();
+
+    // Set the value
+    nw.set(NodeFactory.createURI("http://example.org"));
+
+    // Get the value (remember this may be null)
+    Node value = nw.get();
+
 ## Triples
 
-Again the `Writable` type for nodes is simply called `TripleWritable` and it also implements the `WritableComparable` interface meaning it may be used as both a key and/or value.  Again the standard Hadoop conventions of a `get()` and `set()` method to get/set the value as a Jena `Triple` are followed.
+Again the `Writable` type for nodes is simply called `TripleWritable` and it also implements the `WritableComparable` interface meaning it may be used as both a key and/or value.  Again the standard Hadoop conventions of a `get()` and `set()` method to get/set the value as a Jena `Triple` are followed.  Unlike the `NodeWritable` this class does not support conveying `null` values.
 
 Like the other primitives it is lazily converted to and from the underlying binary representations and it also supports & registers itself for Hadoop's `WritableComparator` mechanism.
 
 ## Quads
 
-Finally the `Writable` type for quads is again simply called `QuadWritable` and it implements the `WritableComparable` interface making it usable as both a key and/or value.  As per the other primitives standard Hadoop conventions of a `get()` and `set()` method are provided to get/set the value as a Jena `Quad`.
+Similarly the `Writable` type for quads is again simply called `QuadWritable` and it implements the `WritableComparable` interface making it usable as both a key and/or value.  As per the other primitives standard Hadoop conventions of a `get()` and `set()` method are provided to get/set the value as a Jena `Quad`.  Unlike the `NodeWritable` this class does not support conveying `null` values.
 
 Like the other primitives it is lazily converted to and from the underlying binary representations and it also supports & registers itself for Hadoop's `WritableComparator` mechanism.
 
 ## Arbitrary sized tuples
 
-In some cases you may have data that is RDF like but not itself RDF or that is a mix of triples and quads in which case you may wish to use the `NodeTupleWritable`.  This is used to represent an arbitrarily sized tuple consisting of zero or more `Node` instances, there is no restriction on the number of nodes per tuple and no requirement that tuple data be uniform.
+In some cases you may have data that is RDF like but not itself RDF or that is a mix of triples and quads in which case you may wish to use the `NodeTupleWritable`.  This is used to represent an arbitrarily sized tuple consisting of zero or more `Node` instances, there is no restriction on the number of nodes per tuple and no requirement that tuple data be uniform in size.
 
 Like the other primitives it implements `WritableComparable` so can be used as a key and/or value.  However this primitive does not support binary comparisons meaning it may not perform as well as using the other primitives.