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/10/28 13:08:24 UTC
[46/50] [abbrv] incubator-commonsrdf git commit: Reformat tab ->
spaces
http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/413dd09a/api/src/main/java/org/apache/commons/rdf/api/RDF.java
----------------------------------------------------------------------
diff --git a/api/src/main/java/org/apache/commons/rdf/api/RDF.java b/api/src/main/java/org/apache/commons/rdf/api/RDF.java
index 32b7f66..b942b30 100644
--- a/api/src/main/java/org/apache/commons/rdf/api/RDF.java
+++ b/api/src/main/java/org/apache/commons/rdf/api/RDF.java
@@ -23,21 +23,18 @@ import java.util.Locale;
/**
* A RDF implementation.
* <p>
- * A <code>RDF</code> implementation can create instances of
- * the {@link RDFTerm} types
- * {@link IRI}, {@link BlankNode} and {@link Literal}, as well as creating
+ * A <code>RDF</code> implementation can create instances of the {@link RDFTerm}
+ * types {@link IRI}, {@link BlankNode} and {@link Literal}, as well as creating
* instances of the types {@link Triple}, {@link Quad}, {@link Graph} or
* {@link Dataset}.
* <p>
- * A <em>partial RDF implementation</em>
- * should be clearly documented as such, and may throw
- * {@link UnsupportedOperationException} where applicable, e.g. if it
- * does not support creating {@link Dataset}s or {@link Quad}s.
+ * A <em>partial RDF implementation</em> should be clearly documented as such,
+ * and may throw {@link UnsupportedOperationException} where applicable, e.g. if
+ * it does not support creating {@link Dataset}s or {@link Quad}s.
* <p>
- * Instances of <code>RDF</code> work like a factory for
- * creating Commons RDF instances.
- * spezializations of this interface may also provide methods
- * for conversions from/to their underlying RDF framework.
+ * Instances of <code>RDF</code> work like a factory for creating Commons RDF
+ * instances. spezializations of this interface may also provide methods for
+ * conversions from/to their underlying RDF framework.
* <p>
* If a factory method of a particular implementation does not allow or support
* a provided parameter, e.g. because an IRI is considered invalid, then it
@@ -54,36 +51,37 @@ public interface RDF {
* Create a new blank node.
* <p>
* The returned blank node MUST NOT be equal to any existing
- * {@link BlankNode} instances according to {@link BlankNode#equals(Object)}.
+ * {@link BlankNode} instances according to
+ * {@link BlankNode#equals(Object)}.
*
* @return A new, unique {@link BlankNode}
*/
- public BlankNode createBlankNode();
+ public BlankNode createBlankNode();
/**
* Create a blank node based on the given name.
* <p>
- * All {@link BlankNode}s created with the given <code>name</code>
- * <em>on a particular instance</em> of <code>RDF</code> MUST be
- * equivalent according to {@link BlankNode#equals(Object)},
+ * All {@link BlankNode}s created with the given <code>name</code> <em>on a
+ * particular instance</em> of <code>RDF</code> MUST be equivalent according
+ * to {@link BlankNode#equals(Object)},
* <p>
* The returned BlankNode MUST NOT be equal to <code>BlankNode</code>
* instances returned for any other <code>name</code> or those returned from
* {@link #createBlankNode()}.
* <p>
* The returned BlankNode SHOULD NOT be equivalent to any BlankNodes created
- * on a <em>different</em> <code>RDF</code> instance, e.g.
- * different instances of <code>RDF</code> should produce
- * different blank nodes for the same <code>name</code> unless they
- * purposely are intending to create equivalent {@link BlankNode}
- * instances (e.g. a reinstated {@link Serializable} factory).
+ * on a <em>different</em> <code>RDF</code> instance, e.g. different
+ * instances of <code>RDF</code> should produce different blank nodes for
+ * the same <code>name</code> unless they purposely are intending to create
+ * equivalent {@link BlankNode} instances (e.g. a reinstated
+ * {@link Serializable} factory).
*
* @param name
* A non-empty, non-null, String that is unique to this blank
* node in the context of this {@link RDF}.
* @return A BlankNode for the given name
*/
- public BlankNode createBlankNode(String name);
+ public BlankNode createBlankNode(String name);
/**
* Create a new graph.
@@ -93,31 +91,33 @@ public interface RDF {
*
* @return A new Graph
*/
- public Graph createGraph();
+ public Graph createGraph();
/**
* Create a new dataset.
*
- * It is undefined if the dataset will be persisted by any underlying storage
- * mechanism.
+ * It is undefined if the dataset will be persisted by any underlying
+ * storage mechanism.
*
* @return A new Dataset
*/
- public Dataset createDataset();
+ public Dataset createDataset();
/**
* Create an IRI from a (possibly escaped) String.
*
- * The provided iri string MUST be valid according to the <a
- * href="http://www.w3.org/TR/rdf11-concepts/#dfn-iri">W3C RDF-1.1 IRI</a>
- * definition.
+ * The provided iri string MUST be valid according to the
+ * <a href="http://www.w3.org/TR/rdf11-concepts/#dfn-iri">W3C RDF-1.1
+ * IRI</a> definition.
*
- * @param iri Internationalized Resource Identifier
+ * @param iri
+ * Internationalized Resource Identifier
* @return A new IRI
- * @throws IllegalArgumentException If the provided string is not acceptable, e.g. does not
- * conform to the RFC3987 syntax.
+ * @throws IllegalArgumentException
+ * If the provided string is not acceptable, e.g. does not
+ * conform to the RFC3987 syntax.
*/
- public IRI createIRI(String iri) throws IllegalArgumentException;
+ public IRI createIRI(String iri) throws IllegalArgumentException;
/**
* Create a simple literal.
@@ -131,13 +131,14 @@ public interface RDF {
* {@link Literal#getDatatype()} that is equal to the IRI
* <code>http://www.w3.org/2001/XMLSchema#string</code>.
*
- * @param lexicalForm The literal value in plain text
+ * @param lexicalForm
+ * The literal value in plain text
* @return The created Literal
- * @throws IllegalArgumentException If the provided lexicalForm is not acceptable, e.g. because
- * it is too large for an underlying storage.
+ * @throws IllegalArgumentException
+ * If the provided lexicalForm is not acceptable, e.g. because
+ * it is too large for an underlying storage.
*/
- public Literal createLiteral(String lexicalForm)
- throws IllegalArgumentException;
+ public Literal createLiteral(String lexicalForm) throws IllegalArgumentException;
/**
* Create a literal with the specified data type.
@@ -145,12 +146,12 @@ public interface RDF {
* The provided lexical form should not be escaped in any sense, e.g. should
* not include "quotes" unless those are part of the literal value.
*
- * It is RECOMMENDED that the provided dataType is one of the <a
- * href="http://www.w3.org/TR/rdf11-concepts/#xsd-datatypes">RDF-compatible
- * XSD types</a>.
+ * It is RECOMMENDED that the provided dataType is one of the <a href=
+ * "http://www.w3.org/TR/rdf11-concepts/#xsd-datatypes">RDF-compatible XSD
+ * types</a>.
*
- * The provided lexical form SHOULD be in the <a
- * href="http://www.w3.org/TR/rdf11-concepts/#dfn-lexical-space">lexical
+ * The provided lexical form SHOULD be in the
+ * <a href="http://www.w3.org/TR/rdf11-concepts/#dfn-lexical-space">lexical
* space</a> of the provided dataType.
*
* The returned Literal SHOULD have a {@link Literal#getLexicalForm()} that
@@ -159,15 +160,17 @@ public interface RDF {
* {@link Literal#getDatatype()} that is equivalent to the provided dataType
* IRI.
*
- * @param lexicalForm The literal value
- * @param dataType The data type IRI for the literal value, e.g.
- * <code>http://www.w3.org/2001/XMLSchema#integer</code>
+ * @param lexicalForm
+ * The literal value
+ * @param dataType
+ * The data type IRI for the literal value, e.g.
+ * <code>http://www.w3.org/2001/XMLSchema#integer</code>
* @return The created Literal
- * @throws IllegalArgumentException If any of the provided arguments are not acceptable, e.g.
- * because the provided dataType is not permitted.
+ * @throws IllegalArgumentException
+ * If any of the provided arguments are not acceptable, e.g.
+ * because the provided dataType is not permitted.
*/
- public Literal createLiteral(String lexicalForm, IRI dataType)
- throws IllegalArgumentException;
+ public Literal createLiteral(String lexicalForm, IRI dataType) throws IllegalArgumentException;
/**
* Create a language-tagged literal.
@@ -175,11 +178,12 @@ public interface RDF {
* The provided lexical form should not be escaped in any sense, e.g. should
* not include "quotes" unless those are part of the literal value.
*
- * The provided language tag MUST be valid according to <a
- * href="http://tools.ietf.org/html/bcp47">BCP47</a>, e.g. <code>en</code>.
+ * The provided language tag MUST be valid according to
+ * <a href="http://tools.ietf.org/html/bcp47">BCP47</a>, e.g.
+ * <code>en</code>.
*
- * The provided language tag <a
- * href="http://www.w3.org/TR/rdf11-concepts/#dfn-language-tagged-string"
+ * The provided language tag
+ * <a href="http://www.w3.org/TR/rdf11-concepts/#dfn-language-tagged-string"
* >MAY be converted to lower case</a>.
*
* The returned Literal SHOULD have a {@link Literal#getLexicalForm()} which
@@ -190,15 +194,17 @@ public interface RDF {
* equal to the provided language tag (compared as
* {@link String#toLowerCase(Locale)} using {@link Locale#ENGLISH}).
*
- * @param lexicalForm The literal value
- * @param languageTag The non-empty language tag as defined by <a
- * href="http://tools.ietf.org/html/bcp47">BCP47</a>
+ * @param lexicalForm
+ * The literal value
+ * @param languageTag
+ * The non-empty language tag as defined by
+ * <a href="http://tools.ietf.org/html/bcp47">BCP47</a>
* @return The created Literal
- * @throws IllegalArgumentException If the provided values are not acceptable, e.g. because the
- * languageTag was syntactically invalid.
+ * @throws IllegalArgumentException
+ * If the provided values are not acceptable, e.g. because the
+ * languageTag was syntactically invalid.
*/
- public Literal createLiteral(String lexicalForm, String languageTag)
- throws IllegalArgumentException;
+ public Literal createLiteral(String lexicalForm, String languageTag) throws IllegalArgumentException;
/**
* Create a triple.
@@ -208,37 +214,45 @@ public interface RDF {
* equal to the provided predicate, and a {@link Triple#getObject()} that is
* equal to the provided object.
*
- * @param subject The IRI or BlankNode that is the subject of the triple
- * @param predicate The IRI that is the predicate of the triple
- * @param object The IRI, BlankNode or Literal that is the object of the triple
+ * @param subject
+ * The IRI or BlankNode that is the subject of the triple
+ * @param predicate
+ * The IRI that is the predicate of the triple
+ * @param object
+ * The IRI, BlankNode or Literal that is the object of the triple
* @return The created Triple
- * @throws IllegalArgumentException If any of the provided arguments are not acceptable, e.g.
- * because a Literal has a lexicalForm that is too large for an
- * underlying storage.
+ * @throws IllegalArgumentException
+ * If any of the provided arguments are not acceptable, e.g.
+ * because a Literal has a lexicalForm that is too large for an
+ * underlying storage.
*/
- public Triple createTriple(BlankNodeOrIRI subject, IRI predicate,
- RDFTerm object) throws IllegalArgumentException;
+ public Triple createTriple(BlankNodeOrIRI subject, IRI predicate, RDFTerm object) throws IllegalArgumentException;
/**
* Create a quad.
* <p>
- * The returned Quad SHOULD have a
- * {@link Quad#getGraphName()} that is equal to the provided graphName, a
- * {@link Quad#getSubject()} that is
- * equal to the provided subject, a {@link Quad#getPredicate()} that is
- * equal to the provided predicate, and a {@link Quad#getObject()} that is
- * equal to the provided object.
+ * The returned Quad SHOULD have a {@link Quad#getGraphName()} that is equal
+ * to the provided graphName, a {@link Quad#getSubject()} that is equal to
+ * the provided subject, a {@link Quad#getPredicate()} that is equal to the
+ * provided predicate, and a {@link Quad#getObject()} that is equal to the
+ * provided object.
*
- * @param graphName The IRI or BlankNode that this quad belongs to, or <code>null</code> for the public graph
- * @param subject The IRI or BlankNode that is the subject of the quad
- * @param predicate The IRI that is the predicate of the quad
- * @param object The IRI, BlankNode or Literal that is the object of the quad
+ * @param graphName
+ * The IRI or BlankNode that this quad belongs to, or
+ * <code>null</code> for the public graph
+ * @param subject
+ * The IRI or BlankNode that is the subject of the quad
+ * @param predicate
+ * The IRI that is the predicate of the quad
+ * @param object
+ * The IRI, BlankNode or Literal that is the object of the quad
* @return The created Quad
- * @throws IllegalArgumentException If any of the provided arguments are not acceptable, e.g.
- * because a Literal has a lexicalForm that is too large for an
- * underlying storage.
+ * @throws IllegalArgumentException
+ * If any of the provided arguments are not acceptable, e.g.
+ * because a Literal has a lexicalForm that is too large for an
+ * underlying storage.
*/
- public Quad createQuad(BlankNodeOrIRI graphName, BlankNodeOrIRI subject, IRI predicate,
- RDFTerm object) throws IllegalArgumentException;
+ public Quad createQuad(BlankNodeOrIRI graphName, BlankNodeOrIRI subject, IRI predicate, RDFTerm object)
+ throws IllegalArgumentException;
}
http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/413dd09a/api/src/main/java/org/apache/commons/rdf/api/RDFSyntax.java
----------------------------------------------------------------------
diff --git a/api/src/main/java/org/apache/commons/rdf/api/RDFSyntax.java b/api/src/main/java/org/apache/commons/rdf/api/RDFSyntax.java
index 541469f..2637a96 100644
--- a/api/src/main/java/org/apache/commons/rdf/api/RDFSyntax.java
+++ b/api/src/main/java/org/apache/commons/rdf/api/RDFSyntax.java
@@ -21,163 +21,174 @@ import java.util.Arrays;
import java.util.Locale;
import java.util.Optional;
-/**
+/**
* Enumeration of the RDF 1.1 serialization syntaxes.
* <p>
- * This enumeration lists the W3C standardized
- * RDF 1.1 syntaxes like {@link #TURTLE} and {@link #JSONLD}.
- * Note the existence of other RDF syntaxes that are not included here,
- * e.g. <a href="http://www.w3.org/TeamSubmission/n3/">N3</a>
- * and <a href="https://en.wikipedia.org/wiki/TriX_%28syntax%29">TriX</a>.
+ * This enumeration lists the W3C standardized RDF 1.1 syntaxes like
+ * {@link #TURTLE} and {@link #JSONLD}. Note the existence of other RDF syntaxes
+ * that are not included here, e.g.
+ * <a href="http://www.w3.org/TeamSubmission/n3/">N3</a> and
+ * <a href="https://en.wikipedia.org/wiki/TriX_%28syntax%29">TriX</a>.
*
- * @see <a href="https://www.w3.org/TR/rdf11-primer/#section-graph-syntax">RDF 1.1 Primer</a>
+ * @see <a href="https://www.w3.org/TR/rdf11-primer/#section-graph-syntax">RDF
+ * 1.1 Primer</a>
* @see org.apache.commons.rdf.experimental.RDFParser
*/
public enum RDFSyntax {
-
- /**
- * JSON-LD 1.0
- *
- * @see <a href="https://www.w3.org/TR/json-ld/">https://www.w3.org/TR/json-ld/</a>
- *
- */
- JSONLD("JSON-LD 1.0", "application/ld+json", ".jsonld", true),
-
- /**
- * RDF 1.1 Turtle
- *
- * @see <a href="https://www.w3.org/TR/turtle/">https://www.w3.org/TR/turtle/</a>
- *
- */
- TURTLE("RDF 1.1 Turtle", "text/turtle", ".ttl", false),
-
- /**
- * RDF 1.1 N-Quads
- *
- * @see <a href="https://www.w3.org/TR/n-quads/">https://www.w3.org/TR/n-quads/</a>
- */
- NQUADS("RDF 1.1 N-Quads", "application/n-quads", ".nq", true),
-
- /**
- * RDF 1.1 N-Triples
- *
- * @see <a href="https://www.w3.org/TR/n-triples/">https://www.w3.org/TR/n-triples/</a>
- */
- NTRIPLES("RDF 1.1 N-Triples", "application/n-triples", ".nt", false),
-
- /**
- * HTML+RDFa 1.1
- *
- * @see <a href="https://www.w3.org/TR/html-rdfa/">https://www.w3.org/TR/html-rdfa/</a>
- */
- RDFA_HTML("HTML+RDFa 1.1", "text/html", ".html", false),
-
- /**
- * XHTML+RDFa 1.1
- *
- * @see <a href="https://www.w3.org/TR/xhtml-rdfa/">https://www.w3.org/TR/xhtml-rdfa/</a>
- */
- RDFA_XHTML("XHTML+RDFa 1.1", "application/xhtml+xml", ".xhtml", false),
-
- /**
- * RDF 1.1 XML Syntax
- *
- * @see <a href="https://www.w3.org/TR/rdf-syntax-grammar/">https://www.w3.org/TR/rdf-syntax-grammar/</a>
- */
- RDFXML("RDF 1.1 XML Syntax", "application/rdf+xml", ".rdf", false),
-
- /**
- * RDF 1.1 TriG
- *
- * @see <a href="https://www.w3.org/TR/trig/">https://www.w3.org/TR/trig/</a>
- */
- TRIG("RDF 1.1 TriG", "application/trig", ".trig", true);
-
- /**
- * The <a href="https://tools.ietf.org/html/rfc2046">IANA media type</a> for the RDF syntax.
- * <p>
- * The media type can be used as part of
- * <code>Content-Type</code>
- * and <code>Accept</code> for <em>content negotiation</em> in the
- * <a href="https://tools.ietf.org/html/rfc7231#section-3.1.1.1">HTTP protocol</a>.
- */
- public final String mediaType;
-
- /**
- * The <a href="https://tools.ietf.org/html/rfc2046">IANA-registered</a> file extension.
- * <p>
- * The file extension includes the leading period, e.g. <code>.jsonld</code>
- */
- public final String fileExtension;
-
- /**
- * Indicate if this RDF syntax supports <a href="https://www.w3.org/TR/rdf11-concepts/#section-dataset">RDF Datasets</a>.
- */
- public final boolean supportsDataset;
-
- private final String name;
-
- /**
- * A human-readable name for the RDF syntax.
- * <p>
- * The name is equivalent to the the title of the corresponding W3C Specification.
- */
- @Override
- public String toString() {
- return name;
- }
-
- private RDFSyntax(String name, String mediaType, String fileExtension, boolean supportsDataset) {
- this.name = name;
- this.mediaType = mediaType;
- this.fileExtension = fileExtension;
- this.supportsDataset = supportsDataset;
- }
-
- /**
- * Return the RDFSyntax with the specified media type.
- * <p>
- * The <code>mediaType</code> is compared in lower case, therefore it might
- * not be equal to the {@link RDFSyntax#mediaType} of the returned
- * RDFSyntax.
- * <p>
- * For convenience matching of media types used in a
- * <code>Content-Type</code> header, if the <code>mediaType</code> contains
- * the characters <code>;</code>, <code>,</code> or white space, only the
- * part of the string to the left of those characters are considered.
- *
- * @param mediaType
- * The media type to match
- * @return If {@link Optional#isPresent()}, the {@link RDFSyntax} which has
- * a matching {@link RDFSyntax#mediaType}, otherwise
- * {@link Optional#empty()} indicating that
- * no matching syntax was found.
- */
- public static Optional<RDFSyntax> byMediaType(String mediaType) {
- final String type = mediaType.toLowerCase(Locale.ENGLISH).
- split("\\s*[;,]", 2)[0];
- return Arrays.stream(RDFSyntax.values()).filter(
- t -> t.mediaType.equals(type)).findAny();
- }
-
- /**
- * Return the RDFSyntax with the specified file extension.
- * <p>
- * The <code>fileExtension</code> is compared in lower case, therefore it
- * might not be equal to the {@link RDFSyntax#fileExtension} of the returned
- * RDFSyntax.
- *
- * @param fileExtension
- * The fileExtension to match, starting with <code>.</code>
- * @return If {@link Optional#isPresent()}, the {@link RDFSyntax} which has
- * a matching {@link RDFSyntax#fileExtension}, otherwise
- * {@link Optional#empty()} indicating that no matching file
- * extension was found.
- */
- public static Optional<RDFSyntax> byFileExtension(String fileExtension) {
- final String ext = fileExtension.toLowerCase(Locale.ENGLISH);
- return Arrays.stream(RDFSyntax.values()).filter(
- t -> t.fileExtension.equals(ext)).findAny();
- }
+
+ /**
+ * JSON-LD 1.0
+ *
+ * @see <a href=
+ * "https://www.w3.org/TR/json-ld/">https://www.w3.org/TR/json-ld/</a>
+ *
+ */
+ JSONLD("JSON-LD 1.0", "application/ld+json", ".jsonld", true),
+
+ /**
+ * RDF 1.1 Turtle
+ *
+ * @see <a href=
+ * "https://www.w3.org/TR/turtle/">https://www.w3.org/TR/turtle/</a>
+ *
+ */
+ TURTLE("RDF 1.1 Turtle", "text/turtle", ".ttl", false),
+
+ /**
+ * RDF 1.1 N-Quads
+ *
+ * @see <a href=
+ * "https://www.w3.org/TR/n-quads/">https://www.w3.org/TR/n-quads/</a>
+ */
+ NQUADS("RDF 1.1 N-Quads", "application/n-quads", ".nq", true),
+
+ /**
+ * RDF 1.1 N-Triples
+ *
+ * @see <a href=
+ * "https://www.w3.org/TR/n-triples/">https://www.w3.org/TR/n-triples/</a>
+ */
+ NTRIPLES("RDF 1.1 N-Triples", "application/n-triples", ".nt", false),
+
+ /**
+ * HTML+RDFa 1.1
+ *
+ * @see <a href=
+ * "https://www.w3.org/TR/html-rdfa/">https://www.w3.org/TR/html-rdfa/</a>
+ */
+ RDFA_HTML("HTML+RDFa 1.1", "text/html", ".html", false),
+
+ /**
+ * XHTML+RDFa 1.1
+ *
+ * @see <a href=
+ * "https://www.w3.org/TR/xhtml-rdfa/">https://www.w3.org/TR/xhtml-rdfa/</a>
+ */
+ RDFA_XHTML("XHTML+RDFa 1.1", "application/xhtml+xml", ".xhtml", false),
+
+ /**
+ * RDF 1.1 XML Syntax
+ *
+ * @see <a href=
+ * "https://www.w3.org/TR/rdf-syntax-grammar/">https://www.w3.org/TR/rdf-syntax-grammar/</a>
+ */
+ RDFXML("RDF 1.1 XML Syntax", "application/rdf+xml", ".rdf", false),
+
+ /**
+ * RDF 1.1 TriG
+ *
+ * @see <a href=
+ * "https://www.w3.org/TR/trig/">https://www.w3.org/TR/trig/</a>
+ */
+ TRIG("RDF 1.1 TriG", "application/trig", ".trig", true);
+
+ /**
+ * The <a href="https://tools.ietf.org/html/rfc2046">IANA media type</a> for
+ * the RDF syntax.
+ * <p>
+ * The media type can be used as part of <code>Content-Type</code> and
+ * <code>Accept</code> for <em>content negotiation</em> in the
+ * <a href="https://tools.ietf.org/html/rfc7231#section-3.1.1.1">HTTP
+ * protocol</a>.
+ */
+ public final String mediaType;
+
+ /**
+ * The <a href="https://tools.ietf.org/html/rfc2046">IANA-registered</a>
+ * file extension.
+ * <p>
+ * The file extension includes the leading period, e.g. <code>.jsonld</code>
+ */
+ public final String fileExtension;
+
+ /**
+ * Indicate if this RDF syntax supports
+ * <a href="https://www.w3.org/TR/rdf11-concepts/#section-dataset">RDF
+ * Datasets</a>.
+ */
+ public final boolean supportsDataset;
+
+ private final String name;
+
+ /**
+ * A human-readable name for the RDF syntax.
+ * <p>
+ * The name is equivalent to the the title of the corresponding W3C
+ * Specification.
+ */
+ @Override
+ public String toString() {
+ return name;
+ }
+
+ private RDFSyntax(String name, String mediaType, String fileExtension, boolean supportsDataset) {
+ this.name = name;
+ this.mediaType = mediaType;
+ this.fileExtension = fileExtension;
+ this.supportsDataset = supportsDataset;
+ }
+
+ /**
+ * Return the RDFSyntax with the specified media type.
+ * <p>
+ * The <code>mediaType</code> is compared in lower case, therefore it might
+ * not be equal to the {@link RDFSyntax#mediaType} of the returned
+ * RDFSyntax.
+ * <p>
+ * For convenience matching of media types used in a
+ * <code>Content-Type</code> header, if the <code>mediaType</code> contains
+ * the characters <code>;</code>, <code>,</code> or white space, only the
+ * part of the string to the left of those characters are considered.
+ *
+ * @param mediaType
+ * The media type to match
+ * @return If {@link Optional#isPresent()}, the {@link RDFSyntax} which has
+ * a matching {@link RDFSyntax#mediaType}, otherwise
+ * {@link Optional#empty()} indicating that no matching syntax was
+ * found.
+ */
+ public static Optional<RDFSyntax> byMediaType(String mediaType) {
+ final String type = mediaType.toLowerCase(Locale.ENGLISH).split("\\s*[;,]", 2)[0];
+ return Arrays.stream(RDFSyntax.values()).filter(t -> t.mediaType.equals(type)).findAny();
+ }
+
+ /**
+ * Return the RDFSyntax with the specified file extension.
+ * <p>
+ * The <code>fileExtension</code> is compared in lower case, therefore it
+ * might not be equal to the {@link RDFSyntax#fileExtension} of the returned
+ * RDFSyntax.
+ *
+ * @param fileExtension
+ * The fileExtension to match, starting with <code>.</code>
+ * @return If {@link Optional#isPresent()}, the {@link RDFSyntax} which has
+ * a matching {@link RDFSyntax#fileExtension}, otherwise
+ * {@link Optional#empty()} indicating that no matching file
+ * extension was found.
+ */
+ public static Optional<RDFSyntax> byFileExtension(String fileExtension) {
+ final String ext = fileExtension.toLowerCase(Locale.ENGLISH);
+ return Arrays.stream(RDFSyntax.values()).filter(t -> t.fileExtension.equals(ext)).findAny();
+ }
}
http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/413dd09a/api/src/main/java/org/apache/commons/rdf/api/RDFTerm.java
----------------------------------------------------------------------
diff --git a/api/src/main/java/org/apache/commons/rdf/api/RDFTerm.java b/api/src/main/java/org/apache/commons/rdf/api/RDFTerm.java
index 59d8fa1..2b69b24 100644
--- a/api/src/main/java/org/apache/commons/rdf/api/RDFTerm.java
+++ b/api/src/main/java/org/apache/commons/rdf/api/RDFTerm.java
@@ -32,11 +32,12 @@ package org.apache.commons.rdf.api;
public interface RDFTerm {
/**
- * Return the term serialised as specified by the RDF-1.1 N-Triples Canonical form.
+ * Return the term serialised as specified by the RDF-1.1 N-Triples
+ * Canonical form.
*
* @return The term serialised as RDF-1.1 N-Triples.
* @see <a href="http://www.w3.org/TR/n-triples/#canonical-ntriples">
- * RDF-1.1 N-Triples Canonical form</a>
+ * RDF-1.1 N-Triples Canonical form</a>
*/
String ntriplesString();
http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/413dd09a/api/src/main/java/org/apache/commons/rdf/api/RDFTermFactory.java
----------------------------------------------------------------------
diff --git a/api/src/main/java/org/apache/commons/rdf/api/RDFTermFactory.java b/api/src/main/java/org/apache/commons/rdf/api/RDFTermFactory.java
index 37c4ead..f245cce 100644
--- a/api/src/main/java/org/apache/commons/rdf/api/RDFTermFactory.java
+++ b/api/src/main/java/org/apache/commons/rdf/api/RDFTermFactory.java
@@ -20,8 +20,8 @@ package org.apache.commons.rdf.api;
/**
* Factory for creating RDFTerm instances..
* <p>
- * This interface is <strong>deprecated</strong> in favour of
- * the richer {@link RDF}.
+ * This interface is <strong>deprecated</strong> in favour of the richer
+ * {@link RDF}.
*
* @see RDF
*/
@@ -29,49 +29,38 @@ package org.apache.commons.rdf.api;
public interface RDFTermFactory {
default BlankNode createBlankNode() throws UnsupportedOperationException {
- throw new UnsupportedOperationException(
- "createBlankNode() not supported");
+ throw new UnsupportedOperationException("createBlankNode() not supported");
}
- default BlankNode createBlankNode(String name)
- throws UnsupportedOperationException {
- throw new UnsupportedOperationException(
- "createBlankNode(String) not supported");
+ default BlankNode createBlankNode(String name) throws UnsupportedOperationException {
+ throw new UnsupportedOperationException("createBlankNode(String) not supported");
}
default Graph createGraph() throws UnsupportedOperationException {
throw new UnsupportedOperationException("createGraph() not supported");
}
- default IRI createIRI(String iri) throws IllegalArgumentException,
- UnsupportedOperationException {
- throw new UnsupportedOperationException(
- "createIRI(String) not supported");
+ default IRI createIRI(String iri) throws IllegalArgumentException, UnsupportedOperationException {
+ throw new UnsupportedOperationException("createIRI(String) not supported");
}
- default Literal createLiteral(String lexicalForm)
- throws IllegalArgumentException, UnsupportedOperationException {
- throw new UnsupportedOperationException(
- "createLiteral(String) not supported");
+ default Literal createLiteral(String lexicalForm) throws IllegalArgumentException, UnsupportedOperationException {
+ throw new UnsupportedOperationException("createLiteral(String) not supported");
}
default Literal createLiteral(String lexicalForm, IRI dataType)
throws IllegalArgumentException, UnsupportedOperationException {
- throw new UnsupportedOperationException(
- "createLiteral(String) not supported");
+ throw new UnsupportedOperationException("createLiteral(String) not supported");
}
default Literal createLiteral(String lexicalForm, String languageTag)
throws IllegalArgumentException, UnsupportedOperationException {
- throw new UnsupportedOperationException(
- "createLiteral(String,String) not supported");
+ throw new UnsupportedOperationException("createLiteral(String,String) not supported");
}
- default Triple createTriple(BlankNodeOrIRI subject, IRI predicate,
- RDFTerm object) throws IllegalArgumentException,
- UnsupportedOperationException {
- throw new UnsupportedOperationException(
- "createTriple(BlankNodeOrIRI,IRI,RDFTerm) not supported");
+ default Triple createTriple(BlankNodeOrIRI subject, IRI predicate, RDFTerm object)
+ throws IllegalArgumentException, UnsupportedOperationException {
+ throw new UnsupportedOperationException("createTriple(BlankNodeOrIRI,IRI,RDFTerm) not supported");
}
}
http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/413dd09a/api/src/main/java/org/apache/commons/rdf/api/Triple.java
----------------------------------------------------------------------
diff --git a/api/src/main/java/org/apache/commons/rdf/api/Triple.java b/api/src/main/java/org/apache/commons/rdf/api/Triple.java
index b0866bd..ef9bdaa 100644
--- a/api/src/main/java/org/apache/commons/rdf/api/Triple.java
+++ b/api/src/main/java/org/apache/commons/rdf/api/Triple.java
@@ -21,14 +21,14 @@ import java.util.Objects;
/**
* An <a href= "http://www.w3.org/TR/rdf11-concepts/#dfn-rdf-triple" >RDF-1.1
- * Triple</a>, as defined by <a href= "http://www.w3.org/TR/rdf11-concepts/"
- * >RDF-1.1 Concepts and Abstract Syntax</a>, a W3C Recommendation published on
- * 25 February 2014.<br>
+ * Triple</a>, as defined by
+ * <a href= "http://www.w3.org/TR/rdf11-concepts/" >RDF-1.1 Concepts and
+ * Abstract Syntax</a>, a W3C Recommendation published on 25 February 2014.<br>
*
- * @see Quad
+ * @see Quad
* @see RDF#createTriple(BlankNodeOrIRI,IRI,RDFTerm)
* @see <a href= "http://www.w3.org/TR/rdf11-concepts/#dfn-rdf-triple" >RDF-1.1
- * Triple</a>
+ * Triple</a>
*/
public interface Triple extends TripleLike {
@@ -39,7 +39,7 @@ public interface Triple extends TripleLike {
*
* @return The subject {@link BlankNodeOrIRI} of this triple.
* @see <a href="http://www.w3.org/TR/rdf11-concepts/#dfn-subject">RDF-1.1
- * Triple subject</a>
+ * Triple subject</a>
*/
BlankNodeOrIRI getSubject();
@@ -48,7 +48,7 @@ public interface Triple extends TripleLike {
*
* @return The predicate {@link IRI} of this triple.
* @see <a href="http://www.w3.org/TR/rdf11-concepts/#dfn-predicate">RDF-1.1
- * Triple predicate</a>
+ * Triple predicate</a>
*/
IRI getPredicate();
@@ -59,7 +59,7 @@ public interface Triple extends TripleLike {
*
* @return The object {@link RDFTerm} of this triple.
* @see <a href="http://www.w3.org/TR/rdf11-concepts/#dfn-object">RDF-1.1
- * Triple object</a>
+ * Triple object</a>
*/
RDFTerm getObject();
@@ -74,7 +74,8 @@ public interface Triple extends TripleLike {
* Triples produce the same hash code.
* </p>
*
- * @param other Another object
+ * @param other
+ * Another object
* @return true if other is a Triple and is equal to this
* @see Object#equals(Object)
*/
@@ -84,13 +85,13 @@ public interface Triple extends TripleLike {
/**
* Calculate a hash code for this Triple.
* <p>
- * The returned hash code MUST be equal to the result
- * of {@link Objects#hash(Object...)} with
- * the arguments
- * {@link #getSubject()}, {@link #getPredicate()}, {@link #getObject()}.
+ * The returned hash code MUST be equal to the result of
+ * {@link Objects#hash(Object...)} with the arguments {@link #getSubject()},
+ * {@link #getPredicate()}, {@link #getObject()}.
* <p>
- * This method MUST be implemented in conjunction with {@link #equals(Object)}
- * so that two equal {@link Triple}s produce the same hash code.
+ * This method MUST be implemented in conjunction with
+ * {@link #equals(Object)} so that two equal {@link Triple}s produce the
+ * same hash code.
*
* @return a hash code value for this Triple.
* @see Object#hashCode()
http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/413dd09a/api/src/main/java/org/apache/commons/rdf/api/TripleLike.java
----------------------------------------------------------------------
diff --git a/api/src/main/java/org/apache/commons/rdf/api/TripleLike.java b/api/src/main/java/org/apache/commons/rdf/api/TripleLike.java
index 30e303a..b469aa4 100644
--- a/api/src/main/java/org/apache/commons/rdf/api/TripleLike.java
+++ b/api/src/main/java/org/apache/commons/rdf/api/TripleLike.java
@@ -23,10 +23,9 @@ package org.apache.commons.rdf.api;
* <p>
* A TripleLike statement has at least a {@link #getSubject()},
* {@link #getPredicate()} and {@link #getObject()}, but unlike a {@link Triple}
- * does not have a formalised
- * {@link Triple#equals(Object)} or
- * {@link Triple#hashCode()} semantics. This interfaced can also be
- * used for <em>generalised triples</em> (e.g. a {@link BlankNode} as predicate).
+ * does not have a formalised {@link Triple#equals(Object)} or
+ * {@link Triple#hashCode()} semantics. This interfaced can also be used for
+ * <em>generalised triples</em> (e.g. a {@link BlankNode} as predicate).
* <p>
* Implementations should specialise which specific {@link RDFTerm} types they
* return by overriding {@link #getSubject()}, {@link #getPredicate()} and
@@ -40,25 +39,25 @@ package org.apache.commons.rdf.api;
*/
public interface TripleLike {
- /**
- * The subject of this statement.
- *
- * @return The subject, typically an {@link IRI} or {@link BlankNode}.
- */
- RDFTerm getSubject();
+ /**
+ * The subject of this statement.
+ *
+ * @return The subject, typically an {@link IRI} or {@link BlankNode}.
+ */
+ RDFTerm getSubject();
- /**
- * The predicate of this statement.
- *
- * @return The predicate, typically an {@link IRI}.
- */
- RDFTerm getPredicate();
+ /**
+ * The predicate of this statement.
+ *
+ * @return The predicate, typically an {@link IRI}.
+ */
+ RDFTerm getPredicate();
- /**
- * The object of this statement.
- *
- * @return The object, typically an {@link IRI}, {@link BlankNode} or
- * {@link Literal}.
- */
- RDFTerm getObject();
+ /**
+ * The object of this statement.
+ *
+ * @return The object, typically an {@link IRI}, {@link BlankNode} or
+ * {@link Literal}.
+ */
+ RDFTerm getObject();
}
http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/413dd09a/api/src/main/java/org/apache/commons/rdf/api/package-info.java
----------------------------------------------------------------------
diff --git a/api/src/main/java/org/apache/commons/rdf/api/package-info.java b/api/src/main/java/org/apache/commons/rdf/api/package-info.java
index 4cecc4f..5099cb0 100644
--- a/api/src/main/java/org/apache/commons/rdf/api/package-info.java
+++ b/api/src/main/java/org/apache/commons/rdf/api/package-info.java
@@ -22,30 +22,26 @@
* are represented by corresponding interfaces:
* <p>
* A {@link org.apache.commons.rdf.api.Graph} is a collection of
- * {@link org.apache.commons.rdf.api.Triple}s,
- * which have a <em>subject</em>, <em>predicate</em> and <em>object</em> of
- * {@link org.apache.commons.rdf.api.RDFTerm}s.
- * The three types of RDF terms are {@link org.apache.commons.rdf.api.IRI},
+ * {@link org.apache.commons.rdf.api.Triple}s, which have a <em>subject</em>,
+ * <em>predicate</em> and <em>object</em> of
+ * {@link org.apache.commons.rdf.api.RDFTerm}s. The three types of RDF terms are
+ * {@link org.apache.commons.rdf.api.IRI},
* {@link org.apache.commons.rdf.api.Literal} and
* {@link org.apache.commons.rdf.api.BlankNode}.
* <p>
* Implementations of this API should provide an
- * {@link org.apache.commons.rdf.api.RDF} to facilitate
- * creation of these objects.
+ * {@link org.apache.commons.rdf.api.RDF} to facilitate creation of these
+ * objects.
* <p>
* All the {@link org.apache.commons.rdf.api.RDFTerm} objects are immutable,
- * while a {@link org.apache.commons.rdf.api.Graph}
- * MAY be mutable (e.g. support methods like
- * {@link org.apache.commons.rdf.api.Graph#add(Triple)}).
+ * while a {@link org.apache.commons.rdf.api.Graph} MAY be mutable (e.g. support
+ * methods like {@link org.apache.commons.rdf.api.Graph#add(Triple)}).
* <p>
- * {@link org.apache.commons.rdf.api.RDFSyntax} enumerates the
- * W3C standard RDF 1.1 syntaxes and their media types.
+ * {@link org.apache.commons.rdf.api.RDFSyntax} enumerates the W3C standard RDF
+ * 1.1 syntaxes and their media types.
* <p>
* For further documentation and contact details, see the
- * <a href="http://commonsrdf.incubator.apache.org/">Commons RDF</a>
- * web site.
+ * <a href="http://commonsrdf.incubator.apache.org/">Commons RDF</a> web site.
*
*/
package org.apache.commons.rdf.api;
-
-
http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/413dd09a/api/src/main/java/org/apache/commons/rdf/experimental/RDFParser.java
----------------------------------------------------------------------
diff --git a/api/src/main/java/org/apache/commons/rdf/experimental/RDFParser.java b/api/src/main/java/org/apache/commons/rdf/experimental/RDFParser.java
index d5684e4..6c93998 100644
--- a/api/src/main/java/org/apache/commons/rdf/experimental/RDFParser.java
+++ b/api/src/main/java/org/apache/commons/rdf/experimental/RDFParser.java
@@ -37,11 +37,10 @@ import org.apache.commons.rdf.api.Triple;
/**
* Parse an RDF source into a target (e.g. a Graph/Dataset).
- * <h2>Experimental</h2>
- * This interface (and its implementations) should be considered <strong>at
- * risk</strong>; they might change or be removed in the next minor update of
- * Commons RDF. It may move to the the {@link org.apache.commons.rdf.api}
- * package when it has stabilized.
+ * <h2>Experimental</h2> This interface (and its implementations) should be
+ * considered <strong>at risk</strong>; they might change or be removed in the
+ * next minor update of Commons RDF. It may move to the the
+ * {@link org.apache.commons.rdf.api} package when it has stabilized.
* <h2>Description</h2>
* <p>
* This interface follows the
@@ -62,436 +61,425 @@ import org.apache.commons.rdf.api.Triple;
* Setting a method that has already been set will override any existing value
* in the returned builder - regardless 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> - note that this may
- * require casting, e.g. <code>contentType( (RDFSyntax) null )</code>
- * to undo a previous call to {@link #contentType(RDFSyntax)}.
+ * can be unset by passing <code>null</code> - note that this may require
+ * casting, e.g. <code>contentType( (RDFSyntax) null )</code> to undo a previous
+ * call to {@link #contentType(RDFSyntax)}.
* <p>
- * It is undefined if a RDFParser is mutable or thread-safe, so callers
- * should always use the returned modified RDFParser from the builder
- * methods. The builder may return itself after modification,
- * or a cloned builder with the modified settings applied.
- * Implementations are however encouraged to be immutable,
- * thread-safe and document this. As an example starting point, see
+ * It is undefined if a RDFParser is mutable or thread-safe, so callers should
+ * always use the returned modified RDFParser from the builder methods. The
+ * builder may return itself after modification, or a cloned builder with the
+ * modified settings applied. Implementations are however encouraged to be
+ * immutable, thread-safe and document this. As an example starting point, see
* <code>org.apache.commons.rdf.simple.AbstractRDFParser</code>.
* <p>
* Example usage:
* </p>
*
* <pre>
- * Graph g1 = rDFTermFactory.createGraph();
- * new ExampleRDFParserBuilder()
- * .source(Paths.get("/tmp/graph.ttl"))
- * .contentType(RDFSyntax.TURTLE)
- * .target(g1)
- * .parse().get(30, TimeUnit.Seconds);
+ * Graph g1 = rDFTermFactory.createGraph();
+ * new ExampleRDFParserBuilder().source(Paths.get("/tmp/graph.ttl")).contentType(RDFSyntax.TURTLE).target(g1).parse()
+ * .get(30, TimeUnit.Seconds);
* </pre>
*
*/
public interface RDFParser {
- /**
- * The result of {@link RDFParser#parse()} indicating
- * parsing completed.
- * <p>
- * This is a marker interface that may be subclassed to include
- * parser details, e.g. warning messages or triple counts.
- */
- public interface ParseResult {
- }
+ /**
+ * The result of {@link RDFParser#parse()} indicating parsing completed.
+ * <p>
+ * This is a marker interface that may be subclassed to include parser
+ * details, e.g. warning messages or triple counts.
+ */
+ public interface ParseResult {
+ }
- /**
- * Specify which {@link RDF} to use for generating
- * {@link RDFTerm}s.
- * <p>
- * This option may be used together with {@link #target(Graph)} to
- * override the implementation's default factory and graph.
- * <p>
- * <strong>Warning:</strong> Using the same {@link RDF} for
- * multiple {@link #parse()} calls may accidentally merge
- * {@link BlankNode}s having the same label, as the parser may
- * use the {@link RDF#createBlankNode(String)} method
- * from the parsed blank node labels.
- *
- * @see #target(Graph)
- * @param rdfTermFactory
- * {@link RDF} to use for generating RDFTerms.
- * @return An {@link RDFParser} that will use the specified
- * rdfTermFactory
- */
- RDFParser rdfTermFactory(RDF rdfTermFactory);
+ /**
+ * Specify which {@link RDF} to use for generating {@link RDFTerm}s.
+ * <p>
+ * This option may be used together with {@link #target(Graph)} to override
+ * the implementation's default factory and graph.
+ * <p>
+ * <strong>Warning:</strong> Using the same {@link RDF} for multiple
+ * {@link #parse()} calls may accidentally merge {@link BlankNode}s having
+ * the same label, as the parser may use the
+ * {@link RDF#createBlankNode(String)} method from the parsed blank node
+ * labels.
+ *
+ * @see #target(Graph)
+ * @param rdfTermFactory
+ * {@link RDF} to use for generating RDFTerms.
+ * @return An {@link RDFParser} that will use the specified rdfTermFactory
+ */
+ RDFParser rdfTermFactory(RDF rdfTermFactory);
- /**
- * Specify the content type of the RDF syntax to parse.
- * <p>
- * This option can be used to select the RDFSyntax of the source, overriding
- * any <code>Content-Type</code> headers or equivalent.
- * <p>
- * The character set of the RDFSyntax is assumed to be
- * {@link StandardCharsets#UTF_8} unless overridden within the document
- * (e.g. {@code <?xml version="1.0" encoding="iso-8859-1"?>} in
- * {@link RDFSyntax#RDFXML}).
- * <p>
- * This method will override any contentType set with
- * {@link #contentType(String)}.
- *
- * @see #contentType(String)
- * @param rdfSyntax
- * An {@link RDFSyntax} to parse the source according to, e.g.
- * {@link RDFSyntax#TURTLE}.
- * @throws IllegalArgumentException
- * If this RDFParser does not support the specified
- * RDFSyntax.
- * @return An {@link RDFParser} that will use the specified content
- * type.
- */
- RDFParser contentType(RDFSyntax rdfSyntax) throws IllegalArgumentException;
+ /**
+ * Specify the content type of the RDF syntax to parse.
+ * <p>
+ * This option can be used to select the RDFSyntax of the source, overriding
+ * any <code>Content-Type</code> headers or equivalent.
+ * <p>
+ * The character set of the RDFSyntax is assumed to be
+ * {@link StandardCharsets#UTF_8} unless overridden within the document
+ * (e.g. {@code <?xml version="1.0" encoding="iso-8859-1"?>} in
+ * {@link RDFSyntax#RDFXML}).
+ * <p>
+ * This method will override any contentType set with
+ * {@link #contentType(String)}.
+ *
+ * @see #contentType(String)
+ * @param rdfSyntax
+ * An {@link RDFSyntax} to parse the source according to, e.g.
+ * {@link RDFSyntax#TURTLE}.
+ * @throws IllegalArgumentException
+ * If this RDFParser does not support the specified RDFSyntax.
+ * @return An {@link RDFParser} that will use the specified content type.
+ */
+ RDFParser contentType(RDFSyntax rdfSyntax) throws IllegalArgumentException;
- /**
- * Specify the content type of the RDF syntax to parse.
- * <p>
- * 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 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)}.
- *
- * @see #contentType(RDFSyntax)
- * @param contentType
- * 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>.
- * @return An {@link RDFParser} that will use the specified content
- * type.
- * @throws IllegalArgumentException
- * If the contentType has an invalid syntax, or this
- * RDFParser does not support the specified contentType.
- */
- RDFParser contentType(String contentType) throws IllegalArgumentException;
+ /**
+ * Specify the content type of the RDF syntax to parse.
+ * <p>
+ * 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 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)}.
+ *
+ * @see #contentType(RDFSyntax)
+ * @param contentType
+ * 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>.
+ * @return An {@link RDFParser} that will use the specified content type.
+ * @throws IllegalArgumentException
+ * If the contentType has an invalid syntax, or this RDFParser
+ * does not support the specified contentType.
+ */
+ RDFParser contentType(String contentType) throws IllegalArgumentException;
- /**
- * Specify a {@link Graph} to add parsed triples to.
- * <p>
- * If the source supports datasets (e.g. the {@link #contentType(RDFSyntax)}
- * set has {@link RDFSyntax#supportsDataset} is true)), then only quads in
- * the <em>default graph</em> will be added to the Graph as {@link Triple}s.
- * <p>
- * It is undefined if any triples are added to the specified {@link Graph}
- * if {@link #parse()} throws any exceptions. (However implementations are
- * free to prevent this using transaction mechanisms or similar). If
- * {@link Future#get()} does not indicate an exception, the parser
- * implementation SHOULD have inserted all parsed triples to the specified
- * graph.
- * <p>
- * Calling this method will override any earlier targets set with
- * {@link #target(Graph)}, {@link #target(Consumer)} or
- * {@link #target(Dataset)}.
- * <p>
- * The default implementation of this method calls {@link #target(Consumer)}
- * with a {@link Consumer} that does {@link Graph#add(Triple)} with
- * {@link Quad#asTriple()} if the quad is in the default graph.
- *
- * @param graph
- * The {@link Graph} to add triples to.
- * @return An {@link RDFParser} that will insert triples into the
- * specified graph.
- */
- default RDFParser target(Graph graph) {
- return target(q -> {
- if (! q.getGraphName().isPresent()) {
- graph.add(q.asTriple());
- }
- });
- }
+ /**
+ * Specify a {@link Graph} to add parsed triples to.
+ * <p>
+ * If the source supports datasets (e.g. the {@link #contentType(RDFSyntax)}
+ * set has {@link RDFSyntax#supportsDataset} is true)), then only quads in
+ * the <em>default graph</em> will be added to the Graph as {@link Triple}s.
+ * <p>
+ * It is undefined if any triples are added to the specified {@link Graph}
+ * if {@link #parse()} throws any exceptions. (However implementations are
+ * free to prevent this using transaction mechanisms or similar). If
+ * {@link Future#get()} does not indicate an exception, the parser
+ * implementation SHOULD have inserted all parsed triples to the specified
+ * graph.
+ * <p>
+ * Calling this method will override any earlier targets set with
+ * {@link #target(Graph)}, {@link #target(Consumer)} or
+ * {@link #target(Dataset)}.
+ * <p>
+ * The default implementation of this method calls {@link #target(Consumer)}
+ * with a {@link Consumer} that does {@link Graph#add(Triple)} with
+ * {@link Quad#asTriple()} if the quad is in the default graph.
+ *
+ * @param graph
+ * The {@link Graph} to add triples to.
+ * @return An {@link RDFParser} that will insert triples into the specified
+ * graph.
+ */
+ default RDFParser target(Graph graph) {
+ return target(q -> {
+ if (!q.getGraphName().isPresent()) {
+ graph.add(q.asTriple());
+ }
+ });
+ }
- /**
- * Specify a {@link Dataset} to add parsed quads to.
- * <p>
- * It is undefined if any quads are added to the specified
- * {@link Dataset} if {@link #parse()} throws any exceptions.
- * (However implementations are free to prevent this using transaction
- * mechanisms or similar). On the other hand, if {@link #parse()}
- * does not indicate an exception, the
- * implementation SHOULD have inserted all parsed quads
- * to the specified dataset.
- * <p>
- * Calling this method will override any earlier targets set with
- * {@link #target(Graph)}, {@link #target(Consumer)} or {@link #target(Dataset)}.
- * <p>
- * The default implementation of this method calls {@link #target(Consumer)}
- * with a {@link Consumer} that does {@link Dataset#add(Quad)}.
- *
- * @param dataset
- * The {@link Dataset} to add quads to.
- * @return An {@link RDFParser} that will insert triples into the
- * specified dataset.
- */
- default RDFParser target(Dataset dataset) {
- return target(dataset::add);
- }
+ /**
+ * Specify a {@link Dataset} to add parsed quads to.
+ * <p>
+ * It is undefined if any quads are added to the specified {@link Dataset}
+ * if {@link #parse()} throws any exceptions. (However implementations are
+ * free to prevent this using transaction mechanisms or similar). On the
+ * other hand, if {@link #parse()} does not indicate an exception, the
+ * implementation SHOULD have inserted all parsed quads to the specified
+ * dataset.
+ * <p>
+ * Calling this method will override any earlier targets set with
+ * {@link #target(Graph)}, {@link #target(Consumer)} or
+ * {@link #target(Dataset)}.
+ * <p>
+ * The default implementation of this method calls {@link #target(Consumer)}
+ * with a {@link Consumer} that does {@link Dataset#add(Quad)}.
+ *
+ * @param dataset
+ * The {@link Dataset} to add quads to.
+ * @return An {@link RDFParser} that will insert triples into the specified
+ * dataset.
+ */
+ default RDFParser target(Dataset dataset) {
+ return target(dataset::add);
+ }
- /**
- * Specify a consumer for parsed quads.
- * <p>
- * The quads will include triples in all named graphs of the parsed
- * source, including any triples in the default graph.
- * When parsing a source format which do not support datasets, all quads
- * delivered to the consumer will be in the default graph
- * (e.g. their {@link Quad#getGraphName()} will be
- * as {@link Optional#empty()}), while for a source
- * <p>
- * It is undefined if any quads are consumed if {@link #parse()} throws any
- * exceptions. On the other hand, if {@link #parse()} does not indicate an
- * exception, the implementation SHOULD have produced all parsed quads to
- * the specified consumer.
- * <p>
- * Calling this method will override any earlier targets set with
- * {@link #target(Graph)}, {@link #target(Consumer)} or
- * {@link #target(Dataset)}.
- * <p>
- * The consumer is not assumed to be thread safe - only one
- * {@link Consumer#accept(Object)} is delivered at a time for a given
- * {@link RDFParser#parse()} call.
- * <p>
- * This method is typically called with a functional consumer, for example:
- * <pre>
- * {@code
- * List<Quad> quads = new ArrayList<Quad>;
- * parserBuilder.target(quads::add).parse();
- * }
- * </pre>
- *
- * @param consumer
- * A {@link Consumer} of {@link Quad}s
- * @return An {@link RDFParser} that will call the consumer for into
- * the specified dataset.
- */
- RDFParser target(Consumer<Quad> consumer);
-
- /**
- * 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(IRI)} IRI,
- * 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
- * <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 RDFParser} that will use the specified base IRI.
- */
- RDFParser base(IRI base);
+ /**
+ * Specify a consumer for parsed quads.
+ * <p>
+ * The quads will include triples in all named graphs of the parsed source,
+ * including any triples in the default graph. When parsing a source format
+ * which do not support datasets, all quads delivered to the consumer will
+ * be in the default graph (e.g. their {@link Quad#getGraphName()} will be
+ * as {@link Optional#empty()}), while for a source
+ * <p>
+ * It is undefined if any quads are consumed if {@link #parse()} throws any
+ * exceptions. On the other hand, if {@link #parse()} does not indicate an
+ * exception, the implementation SHOULD have produced all parsed quads to
+ * the specified consumer.
+ * <p>
+ * Calling this method will override any earlier targets set with
+ * {@link #target(Graph)}, {@link #target(Consumer)} or
+ * {@link #target(Dataset)}.
+ * <p>
+ * The consumer is not assumed to be thread safe - only one
+ * {@link Consumer#accept(Object)} is delivered at a time for a given
+ * {@link RDFParser#parse()} call.
+ * <p>
+ * This method is typically called with a functional consumer, for example:
+ *
+ * <pre>
+ * {@code
+ * List<Quad> quads = new ArrayList<Quad>;
+ * parserBuilder.target(quads::add).parse();
+ * }
+ * </pre>
+ *
+ * @param consumer
+ * A {@link Consumer} of {@link Quad}s
+ * @return An {@link RDFParser} that will call the consumer for into the
+ * specified dataset.
+ */
+ RDFParser target(Consumer<Quad> consumer);
- /**
- * 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(IRI)} IRI,
- * 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
- * <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 RDFParser} that will use the specified base IRI.
- * @throws IllegalArgumentException
- * If the base is not a valid absolute IRI string
- */
- RDFParser base(String base) throws IllegalArgumentException;
+ /**
+ * 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(IRI)} IRI,
+ * 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
+ * <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 RDFParser} that will use the specified base IRI.
+ */
+ RDFParser base(IRI base);
- /**
- * 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()}.
- * <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 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 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)}.
- *
- * @param inputStream
- * An InputStream to consume
- * @return An {@link RDFParser} that will use the specified source.
- */
- RDFParser source(InputStream inputStream);
+ /**
+ * 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(IRI)} IRI,
+ * 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
+ * <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 RDFParser} that will use the specified base IRI.
+ * @throws IllegalArgumentException
+ * If the base is not a valid absolute IRI string
+ */
+ RDFParser base(String base) throws IllegalArgumentException;
- /**
- * 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 RDFParser} that will use the specified source.
- */
- RDFParser source(Path file);
+ /**
+ * 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()}.
+ * <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 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 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)}.
+ *
+ * @param inputStream
+ * An InputStream to consume
+ * @return An {@link RDFParser} that will use the specified source.
+ */
+ RDFParser source(InputStream inputStream);
- /**
- * 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 protocol (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 RDFParser} that will use the specified source.
- */
- RDFParser source(IRI iri);
+ /**
+ * 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 RDFParser} that will use the specified source.
+ */
+ RDFParser source(Path file);
- /**
- * 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 RDFParser} that will use the specified source.
- * @throws IllegalArgumentException
- * If the base is not a valid absolute IRI string
- *
- */
- RDFParser source(String iri) throws IllegalArgumentException;
+ /**
+ * 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 protocol (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 RDFParser} that will use the specified source.
+ */
+ RDFParser source(IRI 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>
- * A target method (e.g. {@link #target(Consumer)}, {@link #target(Dataset)},
- * {@link #target(Graph)} or an equivalent subclass method) MUST have been
- * called before calling parse(), otherwise an
- * {@link IllegalStateException} will be thrown.
- * <p>
- * It is undefined if this method is thread-safe, however the
- * {@link RDFParser} may be reused (e.g. setting a different source)
- * as soon as the {@link Future} has been returned from this method.
- * <p>
- * The RDFParser 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>
- * The returned {@link Future} contains a {@link ParseResult}.
- * Implementations may subclass this interface to provide any
- * parser details, e.g. list of warnings. <code>null</code> is a
- * possible return value if no details are available, but
- * parsing succeeded.
- * <p>
- * If an exception occurs during parsing, (e.g. {@link IOException} or
- * <code>org.apache.commons.rdf.simple.experimental.RDFParseException</code>),
- * it should be indicated as the
- * {@link java.util.concurrent.ExecutionException#getCause()} in the
- * {@link java.util.concurrent.ExecutionException} thrown on
- * {@link Future#get()}.
- *
- * @return A Future that will return the populated {@link Graph} when the
- * parsing has finished.
- * @throws IOException
- * If an error occurred while starting to read the source (e.g.
- * file not found, unsupported IRI protocol). Note that IO
- * errors during parsing would instead be the
- * {@link java.util.concurrent.ExecutionException#getCause()} of
- * the {@link java.util.concurrent.ExecutionException} thrown on
- * {@link Future#get()}.
- * @throws IllegalStateException
- * If the builder is in an invalid state, e.g. a
- * <code>source</code> has not been set.
- */
- Future<? extends ParseResult> parse() throws IOException, IllegalStateException;
+ /**
+ * 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 RDFParser} that will use the specified source.
+ * @throws IllegalArgumentException
+ * If the base is not a valid absolute IRI string
+ *
+ */
+ RDFParser source(String iri) throws IllegalArgumentException;
+
+ /**
+ * 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>
+ * A target method (e.g. {@link #target(Consumer)},
+ * {@link #target(Dataset)}, {@link #target(Graph)} or an equivalent
+ * subclass method) MUST have been called before calling parse(), otherwise
+ * an {@link IllegalStateException} will be thrown.
+ * <p>
+ * It is undefined if this method is thread-safe, however the
+ * {@link RDFParser} may be reused (e.g. setting a different source) as soon
+ * as the {@link Future} has been returned from this method.
+ * <p>
+ * The RDFParser 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>
+ * The returned {@link Future} contains a {@link ParseResult}.
+ * Implementations may subclass this interface to provide any parser
+ * details, e.g. list of warnings. <code>null</code> is a possible return
+ * value if no details are available, but parsing succeeded.
+ * <p>
+ * If an exception occurs during parsing, (e.g. {@link IOException} or
+ * <code>org.apache.commons.rdf.simple.experimental.RDFParseException</code>),
+ * it should be indicated as the
+ * {@link java.util.concurrent.ExecutionException#getCause()} in the
+ * {@link java.util.concurrent.ExecutionException} thrown on
+ * {@link Future#get()}.
+ *
+ * @return A Future that will return the populated {@link Graph} when the
+ * parsing has finished.
+ * @throws IOException
+ * If an error occurred while starting to read the source (e.g.
+ * file not found, unsupported IRI protocol). Note that IO
+ * errors during parsing would instead be the
+ * {@link java.util.concurrent.ExecutionException#getCause()} of
+ * the {@link java.util.concurrent.ExecutionException} thrown on
+ * {@link Future#get()}.
+ * @throws IllegalStateException
+ * If the builder is in an invalid state, e.g. a
+ * <code>source</code> has not been set.
+ */
+ Future<? extends ParseResult> parse() throws IOException, IllegalStateException;
}
http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/413dd09a/api/src/test/java/org/apache/commons/rdf/api/AbstractBlankNodeTest.java
----------------------------------------------------------------------
diff --git a/api/src/test/java/org/apache/commons/rdf/api/AbstractBlankNodeTest.java b/api/src/test/java/org/apache/commons/rdf/api/AbstractBlankNodeTest.java
index b61c64a..31593c5 100644
--- a/api/src/test/java/org/apache/commons/rdf/api/AbstractBlankNodeTest.java
+++ b/api/src/test/java/org/apache/commons/rdf/api/AbstractBlankNodeTest.java
@@ -28,8 +28,8 @@ import static org.junit.Assert.assertNotEquals;
public abstract class AbstractBlankNodeTest {
/**
- * This method must be overridden by the implementing test to
- * create a {@link BlankNode} to be tested.
+ * This method must be overridden by the implementing test to create a
+ * {@link BlankNode} to be tested.
* <p>
* Each call to this method must provide a new, unique BlankNode.
*
@@ -46,15 +46,15 @@ public abstract class AbstractBlankNodeTest {
* test may be the same object, or they may be different objects.
* </p>
*
- * @param identifier The identifier to use as the reference for creating the blank
- * node that is returned.
+ * @param identifier
+ * The identifier to use as the reference for creating the blank
+ * node that is returned.
* @return A new blank node based on the
*/
protected abstract BlankNode getBlankNode(String identifier);
/**
- * Test method for
- * {@link BlankNode#uniqueReference()}.
+ * Test method for {@link BlankNode#uniqueReference()}.
*/
@Test
public final void testInternalIdentifier() {
@@ -76,35 +76,23 @@ public abstract class AbstractBlankNodeTest {
BlankNode testManual4 = getBlankNode("4");
// Test against our fake stub
- assertNotEquals(testNull.uniqueReference(),
- testAutomatic1.uniqueReference());
- assertNotEquals(testAutomatic1.uniqueReference(),
- testNull.uniqueReference());
- assertNotEquals(testNull.uniqueReference(),
- testManual3a.uniqueReference());
- assertNotEquals(testManual3a.uniqueReference(),
- testNull.uniqueReference());
+ assertNotEquals(testNull.uniqueReference(), testAutomatic1.uniqueReference());
+ assertNotEquals(testAutomatic1.uniqueReference(), testNull.uniqueReference());
+ assertNotEquals(testNull.uniqueReference(), testManual3a.uniqueReference());
+ assertNotEquals(testManual3a.uniqueReference(), testNull.uniqueReference());
// Test the two imported instances against each other
- assertEquals(testAutomatic1.uniqueReference(),
- testAutomatic1.uniqueReference());
- assertEquals(testAutomatic2.uniqueReference(),
- testAutomatic2.uniqueReference());
- assertNotEquals(testAutomatic1.uniqueReference(),
- testAutomatic2.uniqueReference());
- assertNotEquals(testAutomatic2.uniqueReference(),
- testAutomatic1.uniqueReference());
- assertNotEquals(testAutomatic1.uniqueReference(),
- testManual3a.uniqueReference());
- assertEquals(testManual3b.uniqueReference(),
- testManual3a.uniqueReference());
- assertNotEquals(testManual3a.uniqueReference(),
- testManual4.uniqueReference());
+ assertEquals(testAutomatic1.uniqueReference(), testAutomatic1.uniqueReference());
+ assertEquals(testAutomatic2.uniqueReference(), testAutomatic2.uniqueReference());
+ assertNotEquals(testAutomatic1.uniqueReference(), testAutomatic2.uniqueReference());
+ assertNotEquals(testAutomatic2.uniqueReference(), testAutomatic1.uniqueReference());
+ assertNotEquals(testAutomatic1.uniqueReference(), testManual3a.uniqueReference());
+ assertEquals(testManual3b.uniqueReference(), testManual3a.uniqueReference());
+ assertNotEquals(testManual3a.uniqueReference(), testManual4.uniqueReference());
}
/**
- * Test method for
- * {@link BlankNode#equals(java.lang.Object)}.
+ * Test method for {@link BlankNode#equals(java.lang.Object)}.
*/
@Test
public final void testEquals() {
@@ -180,8 +168,7 @@ public abstract class AbstractBlankNodeTest {
}
/**
- * Test method for
- * {@link RDFTerm#ntriplesString()}.
+ * Test method for {@link RDFTerm#ntriplesString()}.
*/
@Test
public final void testNtriplesString() {
@@ -203,30 +190,19 @@ public abstract class AbstractBlankNodeTest {
BlankNode testManual4 = getBlankNode("4");
// Test against our fake stub
- assertNotEquals(testNull.ntriplesString(),
- testAutomatic1.ntriplesString());
- assertNotEquals(testAutomatic1.ntriplesString(),
- testNull.ntriplesString());
- assertNotEquals(testNull.ntriplesString(),
- testManual3a.ntriplesString());
- assertNotEquals(testManual3a.ntriplesString(),
- testNull.ntriplesString());
+ assertNotEquals(testNull.ntriplesString(), testAutomatic1.ntriplesString());
+ assertNotEquals(testAutomatic1.ntriplesString(), testNull.ntriplesString());
+ assertNotEquals(testNull.ntriplesString(), testManual3a.ntriplesString());
+ assertNotEquals(testManual3a.ntriplesString(), testNull.ntriplesString());
// Test the two imported instances against each other
- assertEquals(testAutomatic1.ntriplesString(),
- testAutomatic1.ntriplesString());
- assertEquals(testAutomatic2.ntriplesString(),
- testAutomatic2.ntriplesString());
- assertNotEquals(testAutomatic1.ntriplesString(),
- testAutomatic2.ntriplesString());
- assertNotEquals(testAutomatic2.ntriplesString(),
- testAutomatic1.ntriplesString());
- assertNotEquals(testAutomatic1.ntriplesString(),
- testManual3a.ntriplesString());
- assertEquals(testManual3b.ntriplesString(),
- testManual3a.ntriplesString());
- assertNotEquals(testManual3a.ntriplesString(),
- testManual4.ntriplesString());
+ assertEquals(testAutomatic1.ntriplesString(), testAutomatic1.ntriplesString());
+ assertEquals(testAutomatic2.ntriplesString(), testAutomatic2.ntriplesString());
+ assertNotEquals(testAutomatic1.ntriplesString(), testAutomatic2.ntriplesString());
+ assertNotEquals(testAutomatic2.ntriplesString(), testAutomatic1.ntriplesString());
+ assertNotEquals(testAutomatic1.ntriplesString(), testManual3a.ntriplesString());
+ assertEquals(testManual3b.ntriplesString(), testManual3a.ntriplesString());
+ assertNotEquals(testManual3a.ntriplesString(), testManual4.ntriplesString());
}
}