Return-Path: X-Original-To: apmail-commonsrdf-commits-archive@minotaur.apache.org Delivered-To: apmail-commonsrdf-commits-archive@minotaur.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id 3E42E19371 for ; Tue, 29 Mar 2016 13:07:26 +0000 (UTC) Received: (qmail 16609 invoked by uid 500); 29 Mar 2016 13:07:26 -0000 Delivered-To: apmail-commonsrdf-commits-archive@commonsrdf.apache.org Received: (qmail 16579 invoked by uid 500); 29 Mar 2016 13:07:26 -0000 Mailing-List: contact commits-help@commonsrdf.incubator.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@commonsrdf.incubator.apache.org Delivered-To: mailing list commits@commonsrdf.incubator.apache.org Received: (qmail 16570 invoked by uid 99); 29 Mar 2016 13:07:26 -0000 Received: from pnap-us-west-generic-nat.apache.org (HELO spamd1-us-west.apache.org) (209.188.14.142) by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 29 Mar 2016 13:07:26 +0000 Received: from localhost (localhost [127.0.0.1]) by spamd1-us-west.apache.org (ASF Mail Server at spamd1-us-west.apache.org) with ESMTP id B8868CF0F9 for ; Tue, 29 Mar 2016 13:07:25 +0000 (UTC) X-Virus-Scanned: Debian amavisd-new at spamd1-us-west.apache.org X-Spam-Flag: NO X-Spam-Score: -4.216 X-Spam-Level: X-Spam-Status: No, score=-4.216 tagged_above=-999 required=6.31 tests=[KAM_ASCII_DIVIDERS=0.8, KAM_LAZY_DOMAIN_SECURITY=1, RCVD_IN_DNSWL_HI=-5, RCVD_IN_MSPIKE_H3=-0.01, RCVD_IN_MSPIKE_WL=-0.01, RP_MATCHES_RCVD=-0.996] autolearn=disabled Received: from mx1-lw-eu.apache.org ([10.40.0.8]) by localhost (spamd1-us-west.apache.org [10.40.0.7]) (amavisd-new, port 10024) with ESMTP id 4rLDjAHLYVtI for ; Tue, 29 Mar 2016 13:07:23 +0000 (UTC) Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by mx1-lw-eu.apache.org (ASF Mail Server at mx1-lw-eu.apache.org) with SMTP id A0BBC5FB08 for ; Tue, 29 Mar 2016 13:07:20 +0000 (UTC) Received: (qmail 15366 invoked by uid 99); 29 Mar 2016 13:07:19 -0000 Received: from git1-us-west.apache.org (HELO git1-us-west.apache.org) (140.211.11.23) by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 29 Mar 2016 13:07:19 +0000 Received: by git1-us-west.apache.org (ASF Mail Server at git1-us-west.apache.org, from userid 33) id 77135E03A9; Tue, 29 Mar 2016 13:07:19 +0000 (UTC) Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit From: stain@apache.org To: commits@commonsrdf.incubator.apache.org Date: Tue, 29 Mar 2016 13:07:28 -0000 Message-Id: <845f9c44b9b7472f8831eee2aef8d389@git.apache.org> In-Reply-To: <2f5838dcc1fd49df92551dbe70eabde9@git.apache.org> References: <2f5838dcc1fd49df92551dbe70eabde9@git.apache.org> X-Mailer: ASF-Git Admin Mailer Subject: [10/11] incubator-commonsrdf git commit: about asynchronous stuff about asynchronous stuff Project: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/commit/d7623dda Tree: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/tree/d7623dda Diff: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/diff/d7623dda Branch: refs/heads/parser-writer-interface Commit: d7623ddac75e408e62daa41c25649cc33f16d697 Parents: e7aa10d Author: Stian Soiland-Reyes Authored: Sun Mar 27 21:57:18 2016 +0100 Committer: Stian Soiland-Reyes Committed: Tue Mar 29 14:06:50 2016 +0100 ---------------------------------------------------------------------- .../commons/rdf/api/RDFParserBuilder.java | 118 +++++++++++-------- 1 file changed, 66 insertions(+), 52 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/d7623dda/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 3bf536d..3a853f5 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 @@ -29,9 +29,8 @@ import java.util.concurrent.Future; * This interface follows the * Builder pattern, * allowing to set parser settings like {@link #contentType(RDFSyntax)} and - * {@link #base(IRI)}. A caller MUST call one of the - * {@link #source(IRI)} methods before calling {@link #parse()} on the returned - * RDFParserBuilder. + * {@link #base(IRI)}. A caller MUST call one of the {@link #source(IRI)} + * methods before calling {@link #parse()} on the returned RDFParserBuilder. *

* It is undefined if a RDFParserBuilder is mutable or thread-safe, so callers * should always use the returned modified RDFParserBuilder from the builder @@ -98,9 +97,8 @@ public interface RDFParserBuilder { * any Content-Type headers or equivalent. *

* The content type MAY include a charset parameter if the RDF - * media types permit it; the default charset - * is {@link StandardCharsets#UTF_8} unless overridden within the - * document. + * media types permit it; the default charset is + * {@link StandardCharsets#UTF_8} unless overridden within the document. *

* This method will override any contentType set with * {@link #contentType(RDFSyntax)}. @@ -112,9 +110,8 @@ public interface RDFParserBuilder { * * RFC7231. * @throws IllegalArgumentException - * If the contentType has an invalid syntax, - * or this RDFParserBuilder does not support the specified - * contentType. + * If the contentType has an invalid syntax, or this + * RDFParserBuilder does not support the specified contentType. * @return An {@link RDFParserBuilder} that will use the specified content * type. */ @@ -125,9 +122,8 @@ public interface RDFParserBuilder { *

* The default (if this option has not been set) is that each call to * {@link #parse()} return a new {@link Graph}, which is created using - * {@link RDFTermFactory#createGraph()} - * if {@link #rdfTermFactory(RDFTermFactory)} - * has been set. + * {@link RDFTermFactory#createGraph()} if + * {@link #rdfTermFactory(RDFTermFactory)} has been set. * * @param graph * The {@link Graph} to add triples into. @@ -145,7 +141,7 @@ public interface RDFParserBuilder { * @base in Turtle documents). *

* If the source is in a syntax that does not support relative IRI - * references (e.g. {@link RDFSyntax#NTRIPLES}), setting the + * references (e.g. {@link RDFSyntax#NTRIPLES}), setting the * base has no effect. *

* This method will override any base IRI set with {@link #base(String)}. @@ -166,7 +162,7 @@ public interface RDFParserBuilder { * @base in Turtle documents). *

* If the source is in a syntax that does not support relative IRI - * references (e.g. {@link RDFSyntax#NTRIPLES}), setting the + * references (e.g. {@link RDFSyntax#NTRIPLES}), setting the * base has no effect. *

* This method will override any base IRI set with {@link #base(IRI)}. @@ -184,18 +180,18 @@ public interface RDFParserBuilder { * The source set will not be read before the call to {@link #parse()}. *

* The InputStream will not be closed after parsing. The InputStream does - * not need to support {@link InputStream#markSupported()}. + * not need to support {@link InputStream#markSupported()}. *

- * The parser might - * not consume the complete stream (e.g. an RDF/XML parser may not read beyond the - * closing tag of </rdf:Description>). + * The parser might not consume the complete stream (e.g. an RDF/XML parser + * may not read beyond the closing tag of + * </rdf:Description>). *

* The {@link #contentType(RDFSyntax)} or {@link #contentType(String)} * SHOULD be set before calling {@link #parse()}. *

* The character set is assumed to be {@link StandardCharsets#UTF_8} unless * the {@link #contentType(String)} specifies otherwise or the document - * declares its own charset (e.g. RDF/XML with a + * declares its own charset (e.g. RDF/XML with a * <?xml encoding="iso-8859-1"> header). *

* The {@link #base(IRI)} or {@link #base(String)} MUST be set before @@ -217,16 +213,16 @@ public interface RDFParserBuilder { * The source set will not be read before the call to {@link #parse()}. *

* The {@link #contentType(RDFSyntax)} or {@link #contentType(String)} - * SHOULD be set before calling {@link #parse()}. + * SHOULD be set before calling {@link #parse()}. *

* The character set is assumed to be {@link StandardCharsets#UTF_8} unless * the {@link #contentType(String)} specifies otherwise or the document - * declares its own charset (e.g. RDF/XML with a + * declares its own charset (e.g. RDF/XML with a * <?xml encoding="iso-8859-1"> header). *

- * The {@link #base(IRI)} or {@link #base(String)} MAY be set before - * calling {@link #parse()}, otherwise {@link Path#toUri()} will be used - * as the base IRI. + * The {@link #base(IRI)} or {@link #base(String)} MAY be set before calling + * {@link #parse()}, otherwise {@link Path#toUri()} will be used as the base + * IRI. *

* This method will override any source set with {@link #source(IRI)}, * {@link #source(InputStream)} or {@link #source(String)}. @@ -242,24 +238,23 @@ public interface RDFParserBuilder { *

* The source set will not be read before the call to {@link #parse()}. *

- * If this builder does not support the given IRI - * (e.g. urn:uuid:ce667463-c5ab-4c23-9b64-701d055c4890), - * this method should succeed, while the {@link #parse()} should - * throw an {@link IOException}. + * If this builder does not support the given IRI (e.g. + * urn:uuid:ce667463-c5ab-4c23-9b64-701d055c4890), this method + * should succeed, while the {@link #parse()} should throw an + * {@link IOException}. *

- * The {@link #contentType(RDFSyntax)} or {@link #contentType(String)} - * MAY be set before calling {@link #parse()}, in which case that - * type MAY be used for content negotiation (e.g. Accept header in HTTP), + * The {@link #contentType(RDFSyntax)} or {@link #contentType(String)} MAY + * be set before calling {@link #parse()}, in which case that type MAY be + * used for content negotiation (e.g. Accept header in HTTP), * and SHOULD be used for selecting the RDFSyntax. *

* The character set is assumed to be {@link StandardCharsets#UTF_8} unless - * the protocol's equivalent of Content-Type specifies otherwise or - * the document declares its own charset (e.g. RDF/XML with a + * the protocol's equivalent of Content-Type specifies + * otherwise or the document declares its own charset (e.g. RDF/XML with a * <?xml encoding="iso-8859-1"> header). *

- * The {@link #base(IRI)} or {@link #base(String)} MAY be set before - * calling {@link #parse()}, otherwise the source IRI will be used - * as the base IRI. + * The {@link #base(IRI)} or {@link #base(String)} MAY be set before calling + * {@link #parse()}, otherwise the source IRI will be used as the base IRI. *

* This method will override any source set with {@link #source(Path)}, * {@link #source(InputStream)} or {@link #source(String)}. @@ -275,24 +270,23 @@ public interface RDFParserBuilder { *

* The source set will not be read before the call to {@link #parse()}. *

- * If this builder does not support the given IRI - * (e.g. urn:uuid:ce667463-c5ab-4c23-9b64-701d055c4890), - * this method should succeed, while the {@link #parse()} should - * throw an {@link IOException}. + * If this builder does not support the given IRI (e.g. + * urn:uuid:ce667463-c5ab-4c23-9b64-701d055c4890), this method + * should succeed, while the {@link #parse()} should throw an + * {@link IOException}. *

- * The {@link #contentType(RDFSyntax)} or {@link #contentType(String)} - * MAY be set before calling {@link #parse()}, in which case that - * type MAY be used for content negotiation (e.g. Accept header in HTTP), + * The {@link #contentType(RDFSyntax)} or {@link #contentType(String)} MAY + * be set before calling {@link #parse()}, in which case that type MAY be + * used for content negotiation (e.g. Accept header in HTTP), * and SHOULD be used for selecting the RDFSyntax. *

* The character set is assumed to be {@link StandardCharsets#UTF_8} unless - * the protocol's equivalent of Content-Type specifies otherwise or - * the document declares its own charset (e.g. RDF/XML with a + * the protocol's equivalent of Content-Type specifies + * otherwise or the document declares its own charset (e.g. RDF/XML with a * <?xml encoding="iso-8859-1"> header). *

- * The {@link #base(IRI)} or {@link #base(String)} MAY be set before - * calling {@link #parse()}, otherwise the source IRI will be used - * as the base IRI. + * The {@link #base(IRI)} or {@link #base(String)} MAY be set before calling + * {@link #parse()}, otherwise the source IRI will be used as the base IRI. *

* This method will override any source set with {@link #source(Path)}, * {@link #source(InputStream)} or {@link #source(IRI)}. @@ -300,15 +294,35 @@ public interface RDFParserBuilder { * @param iri * An IRI to retrieve and parse * @return An {@link RDFParserBuilder} that will use the specified source. - */ + */ RDFParserBuilder source(String iri); /** * Parse the specified source. + *

+ * A source method (e.g. {@link #source(InputStream)}, {@link #source(IRI)}, + * {@link #source(Path)}, {@link #source(String)} or an equivalent subclass + * method) MUST have been called before calling this method, otherwise an + * {@link IllegalStateException} will be thrown. + *

+ * It is undefined if this method is thread-safe, however the + * {@link RDFParserBuilder} may be reused (e.g. setting a different source) + * as soon as the {@link Future} has been returned from this method. + *

+ * The RDFParserBuilder SHOULD perform the parsing as an asynchronous + * operation, and return the {@link Future} as soon as preliminary checks + * (such as validity of the {@link #source(IRI)} and + * {@link #contentType(RDFSyntax)} settings) have finished. The future + * SHOULD not mark {@link Future#isDone()} before parsing is complete. A + * synchronous implementation MAY be blocking on the parse() + * call and return a Future that is already {@link Future#isDone()}. + *

+ * If {@link #intoGraph(Graph)} has been specified, this SHOULD be the same + * {@link Graph} instance returned from {@link Future#get() once parsing has + * completed. * - * @return A Future that will return the graph containing (at least) the - * parsed triples. - * + * @return A Future that will return the populated graph when the parsing + * has finished. * @throws IOException * If an error occurred while reading the source. * @throws IllegalStateException