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/09/28 13:51:59 UTC
[07/36] 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/5e41513a
Tree: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/tree/5e41513a
Diff: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/diff/5e41513a
Branch: refs/heads/master
Commit: 5e41513aaa4a5f71e979a65a7e221e64cf7cd4d1
Parents: dcf4383
Author: Stian Soiland-Reyes <st...@apache.org>
Authored: Sun Mar 27 21:57:18 2016 +0100
Committer: Stian Soiland-Reyes <st...@apache.org>
Committed: Fri Apr 1 16:19:59 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/5e41513a/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
* <a href="https://en.wikipedia.org/wiki/Builder_pattern">Builder pattern</a>,
* 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.
* <p>
* 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 <code>Content-Type</code> headers or equivalent.
* <p>
* The content type MAY include a <code>charset</code> 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.
* <p>
* This method will override any contentType set with
* {@link #contentType(RDFSyntax)}.
@@ -112,9 +110,8 @@ public interface RDFParserBuilder {
* <a href="https://tools.ietf.org/html/rfc7231#section-3.1.1.1">
* RFC7231</a>.
* @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 {
* <p>
* 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 {
* <code>@base</code> in Turtle documents).
* <p>
* 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
* <code>base</code> has no effect.
* <p>
* This method will override any base IRI set with {@link #base(String)}.
@@ -166,7 +162,7 @@ public interface RDFParserBuilder {
* <code>@base</code> in Turtle documents).
* <p>
* 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
* <code>base</code> has no effect.
* <p>
* 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()}.
* <p>
* 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()}.
* <p>
- * The parser might
- * not consume the complete stream (e.g. an RDF/XML parser may not read beyond the
- * closing tag of <code></rdf:Description></code>).
+ * The parser might not consume the complete stream (e.g. an RDF/XML parser
+ * may not read beyond the closing tag of
+ * <code></rdf:Description></code>).
* <p>
* The {@link #contentType(RDFSyntax)} or {@link #contentType(String)}
* SHOULD be set before calling {@link #parse()}.
* <p>
* 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
* <code><?xml encoding="iso-8859-1"></code> header).
* <p>
* 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()}.
* <p>
* The {@link #contentType(RDFSyntax)} or {@link #contentType(String)}
- * SHOULD be set before calling {@link #parse()}.
+ * SHOULD be set before calling {@link #parse()}.
* <p>
* 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
* <code><?xml encoding="iso-8859-1"></code> header).
* <p>
- * 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.
* <p>
* 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 {
* <p>
* The source set will not be read before the call to {@link #parse()}.
* <p>
- * If this builder does not support the given IRI
- * (e.g. <code>urn:uuid:ce667463-c5ab-4c23-9b64-701d055c4890</code>),
- * this method should succeed, while the {@link #parse()} should
- * throw an {@link IOException}.
+ * If this builder does not support the given IRI (e.g.
+ * <code>urn:uuid:ce667463-c5ab-4c23-9b64-701d055c4890</code>), this method
+ * should succeed, while the {@link #parse()} should throw an
+ * {@link IOException}.
* <p>
- * 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. <code>Accept</code> 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. <code>Accept</code> header in HTTP),
* and SHOULD be used for selecting the RDFSyntax.
* <p>
* The character set is assumed to be {@link StandardCharsets#UTF_8} unless
- * the protocol's equivalent of <code>Content-Type</code> specifies otherwise or
- * the document declares its own charset (e.g. RDF/XML with a
+ * the protocol's equivalent of <code>Content-Type</code> specifies
+ * otherwise or the document declares its own charset (e.g. RDF/XML with a
* <code><?xml encoding="iso-8859-1"></code> header).
* <p>
- * 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.
* <p>
* 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 {
* <p>
* The source set will not be read before the call to {@link #parse()}.
* <p>
- * If this builder does not support the given IRI
- * (e.g. <code>urn:uuid:ce667463-c5ab-4c23-9b64-701d055c4890</code>),
- * this method should succeed, while the {@link #parse()} should
- * throw an {@link IOException}.
+ * If this builder does not support the given IRI (e.g.
+ * <code>urn:uuid:ce667463-c5ab-4c23-9b64-701d055c4890</code>), this method
+ * should succeed, while the {@link #parse()} should throw an
+ * {@link IOException}.
* <p>
- * 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. <code>Accept</code> 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. <code>Accept</code> header in HTTP),
* and SHOULD be used for selecting the RDFSyntax.
* <p>
* The character set is assumed to be {@link StandardCharsets#UTF_8} unless
- * the protocol's equivalent of <code>Content-Type</code> specifies otherwise or
- * the document declares its own charset (e.g. RDF/XML with a
+ * the protocol's equivalent of <code>Content-Type</code> specifies
+ * otherwise or the document declares its own charset (e.g. RDF/XML with a
* <code><?xml encoding="iso-8859-1"></code> header).
* <p>
- * 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.
* <p>
* 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.
+ * <p>
+ * 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.
+ * <p>
+ * 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.
+ * <p>
+ * 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 <code>parse()</code>
+ * call and return a Future that is already {@link Future#isDone()}.
+ * <p>
+ * 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