Repository: incubator-commonsrdf Updated Branches: refs/heads/master 9782a5860 -> e0d319181
More source() docs Project: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/commit/dcf43835 Tree: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/tree/dcf43835 Diff: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/diff/dcf43835 Branch: refs/heads/master Commit: dcf43835742e90dcc7668b5ecaca44415e4bbc23 Parents: 4aacf85 Author: Stian Soiland-Reyes <st...@apache.org> Authored: Sun Mar 27 21:47:26 2016 +0100 Committer: Stian Soiland-Reyes <st...@apache.org> Committed: Fri Apr 1 16:19:58 2016 +0100 ---------------------------------------------------------------------- .../commons/rdf/api/RDFParserBuilder.java | 120 ++++++++++++++++--- 1 file changed, 105 insertions(+), 15 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/dcf43835/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 2cc60bb..3bf536d 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 @@ -145,15 +145,15 @@ 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 base has no - * effect. + * 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)}. * * @see #base(String) * @param base - * An absolute IRI to use as a base - * @return An {@link RDFParserBuilder} that will use the specified base IRI + * An absolute IRI to use as a base. + * @return An {@link RDFParserBuilder} that will use the specified base IRI. */ RDFParserBuilder base(IRI base); @@ -166,37 +166,41 @@ 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 base has no - * effect. + * 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)}. * * @see #base(IRI) * @param base - * An absolute IRI to use as a base - * @return An {@link RDFParserBuilder} that will use the specified base IRI + * 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. + * Specify a source {@link InputStream} to parse. * <p> * 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>). + * 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>). * <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. + * the {@link #contentType(String)} 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)} MUST be set before - * calling {@link #parse()}, unless the syntax does not permit relative - * IRIs. + * calling {@link #parse()}, unless the RDF syntax does not permit relative + * IRIs (e.g. {@link RDFSyntax#NTRIPLES}). * <p> * This method will override any source set with {@link #source(IRI)}, * {@link #source(Path)} or {@link #source(String)}. @@ -207,10 +211,96 @@ public interface RDFParserBuilder { */ RDFParserBuilder source(InputStream inputStream); + /** + * Specify a source file {@link Path} to parse. + * <p> + * 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()}. + * <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 + * <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. + * <p> + * This method will override any source set with {@link #source(IRI)}, + * {@link #source(InputStream)} or {@link #source(String)}. + * + * @param file + * A Path for a file to parse + * @return An {@link RDFParserBuilder} that will use the specified source. + */ RDFParserBuilder source(Path file); + /** + * Specify an absolute source {@link IRI} to retrieve and parse. + * <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}. + * <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), + * 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 + * <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. + * <p> + * This method will override any source set with {@link #source(Path)}, + * {@link #source(InputStream)} or {@link #source(String)}. + * + * @param iri + * An IRI to retrieve and parse + * @return An {@link RDFParserBuilder} that will use the specified source. + */ RDFParserBuilder source(IRI iri); + /** + * Specify an absolute source IRI to retrieve and parse. + * <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}. + * <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), + * 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 + * <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. + * <p> + * This method will override any source set with {@link #source(Path)}, + * {@link #source(InputStream)} or {@link #source(IRI)}. + * + * @param iri + * An IRI to retrieve and parse + * @return An {@link RDFParserBuilder} that will use the specified source. + */ RDFParserBuilder source(String iri); /**
