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/04/03 04:12:18 UTC

[4/5] incubator-commonsrdf git commit: DFParserBuilder javadoc on error conditions

DFParserBuilder javadoc on error conditions


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

Branch: refs/heads/parser-writer-interface
Commit: df35ebca2329019ae9468176eb6467b7ce0ba9bf
Parents: b4342b9
Author: Stian Soiland-Reyes <st...@apache.org>
Authored: Sun Apr 3 03:11:28 2016 +0100
Committer: Stian Soiland-Reyes <st...@apache.org>
Committed: Sun Apr 3 03:11:28 2016 +0100

----------------------------------------------------------------------
 .../commons/rdf/api/RDFParserBuilder.java       | 27 +++++++++++++++++---
 1 file changed, 24 insertions(+), 3 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/df35ebca/api/src/main/java/org/apache/commons/rdf/api/RDFParserBuilder.java
----------------------------------------------------------------------
diff --git a/api/src/main/java/org/apache/commons/rdf/api/RDFParserBuilder.java b/api/src/main/java/org/apache/commons/rdf/api/RDFParserBuilder.java
index bc7d750..ee566c7 100644
--- a/api/src/main/java/org/apache/commons/rdf/api/RDFParserBuilder.java
+++ b/api/src/main/java/org/apache/commons/rdf/api/RDFParserBuilder.java
@@ -34,22 +34,34 @@ import java.util.concurrent.Future;
  * {@link #source(InputStream)}) before calling {@link #parse()} on the returned
  * RDFParserBuilder - however methods can be called in any order.
  * <p>
+ * The call to {@link #parse()} returns a {@link Future}, allowing asynchronous parse
+ * operations. This can be combined with {@link #intoGraph(Graph)}
+ * allowing access to the graph before parsing has completed,
+ * however callers are still recommended to to check 
+ * {@link Future#get()} for any exceptions thrown during parsing.
+ * <p>
  * Setting a method that has already been set will override any existing value
  * in the returned builder - irregardless of the parameter type (e.g.
  * {@link #source(IRI)} will override a previous {@link #source(Path)}. Settings
  * can be unset by passing <code>null</code> - this may require casting, e.g.
- * <code>contentType( (RDFSyntax) null )</code>.
+ * <code>contentType( (RDFSyntax) null )</code> to undo a previous call to
+ * {@link #contentType(RDFSyntax)}.
  * <p>
  * It is undefined if a RDFParserBuilder is mutable or thread-safe, so callers
  * should always use the returned modified RDFParserBuilder from the builder
  * methods. The builder may return itself, or a cloned builder with the modified
- * settings applied.
+ * settings applied. Implementations are however encouraged to be 
+ * immutable and thread-safe and document this, 
+ * as an example starting point, see 
+ * {@link org.apache.commons.rdf.simple.AbstractRDFParserBuilder}.
  * <p>
  * Example usage:
  * </p>
  * 
  * <pre>
- *   Graph g1 = ExampleRDFParserBuilder.source("http://example.com/graph.rdf").parse();
+ *   // Retrieve populated graph from the Future
+ *   Graph g1 = ExampleRDFParserBuilder.source("http://example.com/graph.rdf").parse().get(30, TimeUnit.Seconds);
+ *   // Or parsing into an existing Graph:
  *   ExampleRDFParserBuilder.source(Paths.get("/tmp/graph.ttl").contentType(RDFSyntax.TURTLE).intoGraph(g1).parse();
  * </pre>
  * 
@@ -138,6 +150,15 @@ public interface RDFParserBuilder {
 	 * {@link #parse()} return a new {@link Graph}, which is created using
 	 * {@link RDFTermFactory#createGraph()} if
 	 * {@link #rdfTermFactory(RDFTermFactory)} has been set.
+	 * <p>
+	 * It is undefined if any triples are added to the specified
+	 * {@link Graph} if the {@link Future#get()} returned from 
+	 * {@link #parse()} throws any exceptions. (However 
+	 * implementations are free to prevent this using transaction 
+	 * mechanisms or similar).  However, if {@link Future#get()}
+	 * does not indicatean exception, the 
+	 * parser implementation SHOULD have inserted all parsed triples 
+	 * to the specified graph.
 	 * 
 	 * @param graph
 	 *            The {@link Graph} to add triples into.