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/master 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.
