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.