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/07/02 16:14:27 UTC
[10/50] [abbrv] incubator-commonsrdf git commit: charset fun
charset fun
Project: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/commit/a8a6bf12
Tree: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/tree/a8a6bf12
Diff: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/diff/a8a6bf12
Branch: refs/heads/jena
Commit: a8a6bf128a7b7f28741b76b46edf90fc424a6ad2
Parents: 01ed0da
Author: Stian Soiland-Reyes <st...@apache.org>
Authored: Sun Mar 27 20:11:00 2016 +0100
Committer: Stian Soiland-Reyes <st...@apache.org>
Committed: Sun Mar 27 21:25:04 2016 +0100
----------------------------------------------------------------------
.../commons/rdf/api/RDFParserBuilder.java | 101 ++++++++++++-------
1 file changed, 66 insertions(+), 35 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/a8a6bf12/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 3cd7c94..adee4e4 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
@@ -20,7 +20,10 @@ package org.apache.commons.rdf.api;
import java.io.IOException;
import java.io.InputStream;
import java.net.URL;
+import java.nio.charset.StandardCharsets;
import java.nio.file.Path;
+import java.util.Locale;
+import java.util.concurrent.Future;
/**
* Builder for parsing an RDF source into a Graph.
@@ -32,10 +35,10 @@ import java.nio.file.Path;
* <code>source</code> methods before calling {@link #parse()} on the returned
* RDFParserBuilder.
* <p>
- * It is undefined if a RDFParserBuilder is mutable or thread-safe, callers
+ * 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 its own mutated instance, or a cloned builder
- * with the modified setting.
+ * methods. The builder may return itself, or a cloned builder with the modified
+ * settings applied.
* <p>
* Example usage:
* </p>
@@ -70,7 +73,10 @@ public interface RDFParserBuilder {
* This option can be used to select the RDFSyntax of the source, overriding
* any <code>Content-Type</code> headers or equivalent.
* <p>
- * If the content type is a
+ * The character set of the RDFSyntax is assumed to be
+ * {@link StandardCharsets#UTF_8} unless overridden within the document
+ * (e.g. <?xml version="1.0" encoding="iso-8859-1"?></code> in
+ * {@link RDFSyntax#RDFXML}).
* <p>
* This method will override any contentType set with
* {@link #contentType(String)}.
@@ -93,12 +99,20 @@ public interface RDFParserBuilder {
* This option can be used to select the RDFSyntax of the source, overriding
* any <code>Content-Type</code> headers or equivalent.
* <p>
+ * The content type MAY include a <code>charset</code> parameter if the RDF
+ * media types which permit it; if <code>charset</code> is not specified the
+ * default is {@link StandardCharsets#UTF_8} unless overridden within the
+ * document.
+ * <p>
* This method will override any contentType set with
* {@link #contentType(RDFSyntax)}.
*
* @see #contentType(RDFSyntax)
* @param contentType
- * A content-type string, e.g. <code>text/turtle</code>
+ * A content-type string, e.g. <code>application/ld+json</code>
+ * or <code>text/turtle;charset="UTF-8"</code> as specified by
+ * <a href="https://tools.ietf.org/html/rfc7231#section-3.1.1.1">
+ * RFC7231</a>.
* @throws IllegalArgumentException
* If this RDFParserBuilder does not support the specified
* content-type, or it has an invalid syntax.
@@ -110,31 +124,35 @@ public interface RDFParserBuilder {
/**
* Specify which {@link Graph} to add triples into.
* <p>
- * The default if this option has not been set is that
- * each call to {@link #parse()} will return a new {@link Graph} (created using
+ * The default if this option has not been set is that each call to
+ * {@link #parse()} will return a new {@link Graph} (created using
* {@link RDFTermFactory#createGraph() if #rdfTermFactory(RDFTermFactory)
* has been set).
*
- * @param graph The {@link Graph} to add triples into.
- * @return An {@link RDFParserBuilder} that will insert triples into the specified graph.
+ * @param graph
+ * The {@link Graph} to add triples into.
+ * @return An {@link RDFParserBuilder} that will insert triples into the
+ * specified graph.
*/
RDFParserBuilder intoGraph(Graph graph);
/**
* Specify a base IRI to use for parsing any relative IRI references.
* <p>
- * Setting this option will override any protocol-specific base IRI
- * (e.g. <code>Content-Location</code> header) or the {@link #source(URL)} URL,
- * but does not override any base IRIs set within the source document
- * (e.g. <code>@base</code> in Turtle documents).
+ * Setting this option will override any protocol-specific base IRI (e.g.
+ * <code>Content-Location</code> header) or the {@link #source(URL)} URL,
+ * but does not override any base IRIs set within the source document (e.g.
+ * <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 base has no effect.
+ * If the source is in a syntax that does not support relative IRI
+ * references, e.g. {@link RDFSyntax#NTRIPLES}, setting the base has no
+ * effect.
* <p>
* This method will override any base IRI set with {@link #base(String)}.
*
* @see #base(String)
- * @param base An absolute IRI to use as a base
+ * @param base
+ * An absolute IRI to use as a base
* @return An {@link RDFParserBuilder} that will use the specified base IRI
*/
RDFParserBuilder base(IRI base);
@@ -142,38 +160,50 @@ public interface RDFParserBuilder {
/**
* Specify a base IRI to use for parsing any relative IRI references.
* <p>
- * Setting this option will override any protocol-specific base IRI
- * (e.g. <code>Content-Location</code> header) or the {@link #source(URL)} URL,
- * but does not override any base IRIs set within the source document
- * (e.g. <code>@base</code> in Turtle documents).
+ * Setting this option will override any protocol-specific base IRI (e.g.
+ * <code>Content-Location</code> header) or the {@link #source(URL)} URL,
+ * but does not override any base IRIs set within the source document (e.g.
+ * <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 base has no effect.
+ * If the source is in a syntax that does not support relative IRI
+ * references, e.g. {@link RDFSyntax#NTRIPLES}, setting the base has no
+ * effect.
* <p>
* This method will override any base IRI set with {@link #base(IRI)}.
*
* @see #base(IRI)
- * @param base An absolute IRI to use as a base
+ * @param base
+ * An absolute IRI to use as a base
* @return An {@link RDFParserBuilder} that will use the specified base IRI
- */
+ */
RDFParserBuilder base(String base);
/**
* Specify a source to parse.
* <p>
- * The source set will not be accessed before the call to {@link #parse()}.
+ * 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()}. The parser might
+ * not consume the complete stream (e.g. the parser may not read beyond the
+ * closing tag of <code></rdf:Description&;gt</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.
* <p>
- * The InputStream will not be closed after parsing. The
- * InputStream does not need to support {@link InputStream#markSupported()}.
+ * The {@link #base(IRI)} or {@link #base(String)} MUST be set before
+ * calling {@link #parse()}, unless the syntax does not permit relative
+ * IRIs.
* <p>
- * The {@link #contentType(RDFSyntax)} SHOULD be set unless the implementation
- * supports syntax guessing.
- * <p>
- * The {@link #base(IRI)} MUST be set unless the syntax does not permit relative IRIs
- * (e.g. {@link RDFSyntax#NTRIPLES}).
+ * This method will override any source set with {@link #source(IRI)},
+ * {@link #source(Path)} or {@link #source(String)}.
*
* @param inputStream
- * @return
+ * An InputStream to consume
+ * @return An {@link RDFParserBuilder} that will use the specified source.
*/
RDFParserBuilder source(InputStream inputStream);
@@ -186,7 +216,8 @@ public interface RDFParserBuilder {
/**
* Parse the specified source.
*
- * @return The graph containing (at least) the parsed triples.
+ * @return A Future that will return the graph containing (at least) the
+ * parsed triples.
*
* @throws IOException
* If an error occurred while reading the source.
@@ -194,5 +225,5 @@ public interface RDFParserBuilder {
* If the builder is in an invalid state, e.g. a
* <code>source</code> has not been set.
*/
- Graph parse() throws IOException, IllegalStateException;
+ Future<Graph> parse() throws IOException, IllegalStateException;
}