You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commonsrdf.apache.org by st...@apache.org on 2016/09/29 00:16:41 UTC
[05/19] incubator-commonsrdf git commit: conform to -Xdoclint:all
conform to -Xdoclint:all
Project: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/commit/5afd0bd6
Tree: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/tree/5afd0bd6
Diff: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/diff/5afd0bd6
Branch: refs/heads/jena-jsonld-rdf4j-integration
Commit: 5afd0bd686d717c9b16943bd393fcb49cabd5fd6
Parents: e0d3191
Author: Stian Soiland-Reyes <st...@apache.org>
Authored: Wed Sep 28 23:18:45 2016 +0100
Committer: Stian Soiland-Reyes <st...@apache.org>
Committed: Wed Sep 28 23:18:45 2016 +0100
----------------------------------------------------------------------
.../java/org/apache/commons/rdf/api/Graph.java | 5 ++
.../java/org/apache/commons/rdf/api/Quad.java | 4 +-
.../commons/rdf/experimental/RDFParser.java | 8 +--
.../commons/rdf/experimental/package-info.java | 1 -
pom.xml | 4 +-
.../simple/experimental/AbstractRDFParser.java | 54 +++++++++++++-------
.../rdf/simple/experimental/package-info.java | 11 ++--
7 files changed, 53 insertions(+), 34 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/5afd0bd6/api/src/main/java/org/apache/commons/rdf/api/Graph.java
----------------------------------------------------------------------
diff --git a/api/src/main/java/org/apache/commons/rdf/api/Graph.java b/api/src/main/java/org/apache/commons/rdf/api/Graph.java
index 6106bab..7340e86 100644
--- a/api/src/main/java/org/apache/commons/rdf/api/Graph.java
+++ b/api/src/main/java/org/apache/commons/rdf/api/Graph.java
@@ -158,6 +158,7 @@ public interface Graph extends AutoCloseable,GraphLike<Triple, BlankNodeOrIRI, I
* This method is deprecated, use the equivalent method
* {@link #stream()} instead.
*
+ * @return A {@link Stream} over all triples.
*/
@Deprecated
default Stream<? extends Triple> getTriples() {
@@ -168,6 +169,10 @@ public interface Graph extends AutoCloseable,GraphLike<Triple, BlankNodeOrIRI, I
* This method is deprecated, use the equivalent method
* {@link #stream(BlankNodeOrIRI, IRI, RDFTerm)} instead.
*
+ * @param subject The triple subject (null is a wildcard)
+ * @param predicate The triple predicate (null is a wildcard)
+ * @param object The triple object (null is a wildcard)
+ * @return A {@link Stream} over the matched triples.
*/
@Deprecated
default Stream<? extends Triple> getTriples(BlankNodeOrIRI subject, IRI predicate,
http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/5afd0bd6/api/src/main/java/org/apache/commons/rdf/api/Quad.java
----------------------------------------------------------------------
diff --git a/api/src/main/java/org/apache/commons/rdf/api/Quad.java b/api/src/main/java/org/apache/commons/rdf/api/Quad.java
index 951f593..d52a3c3 100644
--- a/api/src/main/java/org/apache/commons/rdf/api/Quad.java
+++ b/api/src/main/java/org/apache/commons/rdf/api/Quad.java
@@ -43,10 +43,10 @@ public interface Quad extends QuadLike<BlankNodeOrIRI,IRI,RDFTerm,BlankNodeOrIRI
* If {@link Optional#isPresent()}, then the {@link Optional#get()} is
* either a {@link BlankNode} or an {@link IRI}, indicating the
* <a href="https://www.w3.org/TR/rdf11-concepts/#dfn-named-graph">graph
- * name of this Quad. If the graph name is not present, e.g. the value is
+ * name</a> of this Quad. If the graph name is not present, e.g. the value is
* {@link Optional#empty()}, it indicates that this Quad is in the
* <a href="https://www.w3.org/TR/rdf11-concepts/#dfn-default-graph">default
- * graph.
+ * graph</a>.
*
* @return If {@link Optional#isPresent()}, the graph name
* {@link BlankNodeOrIRI} of this quad, otherwise
http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/5afd0bd6/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 dd6bcf0..d0b8776 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
@@ -72,7 +72,7 @@ import org.apache.commons.rdf.api.Triple;
* 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
- * {@link org.apache.commons.rdf.simple.AbstractRDFParserBuilder}.
+ * <code>org.apache.commons.rdf.simple.AbstractRDFParser</code>.
* <p>
* Example usage:
* </p>
@@ -128,7 +128,7 @@ public interface RDFParser {
* <p>
* 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
+ * (e.g. {@code <?xml version="1.0" encoding="iso-8859-1"?>} in
* {@link RDFSyntax#RDFXML}).
* <p>
* This method will override any contentType set with
@@ -259,8 +259,10 @@ public interface RDFParser {
* <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
@@ -472,7 +474,7 @@ public interface RDFParser {
* parsing succeeded.
* <p>
* If an exception occurs during parsing, (e.g. {@link IOException} or
- * {@link org.apache.commons.rdf.simple.RDFParseException}),
+ * <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
http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/5afd0bd6/api/src/main/java/org/apache/commons/rdf/experimental/package-info.java
----------------------------------------------------------------------
diff --git a/api/src/main/java/org/apache/commons/rdf/experimental/package-info.java b/api/src/main/java/org/apache/commons/rdf/experimental/package-info.java
index 5f24ddc..5b9e489 100644
--- a/api/src/main/java/org/apache/commons/rdf/experimental/package-info.java
+++ b/api/src/main/java/org/apache/commons/rdf/experimental/package-info.java
@@ -24,7 +24,6 @@
* <p>
* When class/interface has stabilized, it will move to the
* {@link org.apache.commons.rdf.api} package.
- * <p>
* <ul>
* <li>{@link RDFParser} - a builder-like interface for parsing RDF to a
* {@link org.apache.commons.rdf.api.Graph} or
http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/5afd0bd6/pom.xml
----------------------------------------------------------------------
diff --git a/pom.xml b/pom.xml
index f9b85fc..4920284 100644
--- a/pom.xml
+++ b/pom.xml
@@ -281,7 +281,7 @@
</execution>
</executions>
<configuration>
- <additionalparam>-Xdoclint:none</additionalparam>
+ <additionalparam>-Xdoclint:all</additionalparam>
</configuration>
</plugin>
<!--
@@ -448,7 +448,7 @@
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<configuration>
- <additionalparam>-Xdoclint:none</additionalparam>
+ <additionalparam>-Xdoclint:all</additionalparam>
</configuration>
<reportSets>
<reportSet><!-- by default, id = "default" -->
http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/5afd0bd6/simple/src/main/java/org/apache/commons/rdf/simple/experimental/AbstractRDFParser.java
----------------------------------------------------------------------
diff --git a/simple/src/main/java/org/apache/commons/rdf/simple/experimental/AbstractRDFParser.java b/simple/src/main/java/org/apache/commons/rdf/simple/experimental/AbstractRDFParser.java
index 8111f09..9b07699 100644
--- a/simple/src/main/java/org/apache/commons/rdf/simple/experimental/AbstractRDFParser.java
+++ b/simple/src/main/java/org/apache/commons/rdf/simple/experimental/AbstractRDFParser.java
@@ -67,6 +67,9 @@ public abstract class AbstractRDFParser<T extends AbstractRDFParser<T>>
/**
* Get the set {@link RDFTermFactory}, if any.
+ *
+ * @return The {@link RDFTermFactory} to use, or {@link Optional#empty()} if
+ * it has not been set
*/
public Optional<RDFTermFactory> getRdfTermFactory() {
return rdfTermFactory;
@@ -75,9 +78,11 @@ public abstract class AbstractRDFParser<T extends AbstractRDFParser<T>>
/**
* Get the set content-type {@link RDFSyntax}, if any.
* <p>
- * If this is {@link Optional#isPresent()}, then
- * {@link #getContentType()} contains the
- * value of {@link RDFSyntax#mediaType}.
+ * If this is {@link Optional#isPresent()}, then {@link #getContentType()}
+ * contains the value of {@link RDFSyntax#mediaType}.
+ *
+ * @return The {@link RDFSyntax} of the content type, or
+ * {@link Optional#empty()} if it has not been set
*/
public Optional<RDFSyntax> getContentTypeSyntax() {
return contentTypeSyntax;
@@ -86,11 +91,13 @@ public abstract class AbstractRDFParser<T extends AbstractRDFParser<T>>
/**
* Get the set content-type String, if any.
* <p>
- * If this is {@link Optional#isPresent()} and
- * is recognized by {@link RDFSyntax#byMediaType(String)}, then
- * the corresponding {@link RDFSyntax} is set on
- * {@link #getContentType()}, otherwise that is
- * {@link Optional#empty()}.
+ * If this is {@link Optional#isPresent()} and is recognized by
+ * {@link RDFSyntax#byMediaType(String)}, then the corresponding
+ * {@link RDFSyntax} is set on {@link #getContentType()}, otherwise that is
+ * {@link Optional#empty()}.
+ *
+ * @return The Content-Type IANA media type, e.g. <code>text/turtle</code>,
+ * or {@link Optional#empty()} if it has not been set
*/
public final Optional<String> getContentType() {
return contentType;
@@ -99,8 +106,11 @@ public abstract class AbstractRDFParser<T extends AbstractRDFParser<T>>
/**
* Get the target to consume parsed Quads.
* <p>
- * From the call to {@link #parseSynchronusly()}, this
- * method is always {@link Optional#isPresent()}.
+ * From the call to {@link #parseSynchronusly()}, this will be a
+ * non-<code>null</code> value (as a target is a required setting).
+ *
+ * @return The target consumer of {@link Quad}s, or <code>null</code> if it
+ * has not yet been set.
*
*/
public Consumer<Quad> getTarget() {
@@ -143,8 +153,8 @@ public abstract class AbstractRDFParser<T extends AbstractRDFParser<T>>
/**
* Get the set base {@link IRI}, if present.
- * <p>
*
+ * @return The base {@link IRI}, or {@link Optional#empty()} if it has not been set
*/
public Optional<IRI> getBase() {
return base;
@@ -156,6 +166,8 @@ public abstract class AbstractRDFParser<T extends AbstractRDFParser<T>>
* If this is {@link Optional#isPresent()}, then
* {@link #getSourceFile()} and {@link #getSourceIri()}
* are {@link Optional#empty()}.
+ *
+ * @return The source {@link InputStream}, or {@link Optional#empty()} if it has not been set
*/
public Optional<InputStream> getSourceInputStream() {
return sourceInputStream;
@@ -167,6 +179,8 @@ public abstract class AbstractRDFParser<T extends AbstractRDFParser<T>>
* If this is {@link Optional#isPresent()}, then
* {@link #getSourceInputStream()} and {@link #getSourceIri()}
* are {@link Optional#empty()}.
+ *
+ * @return The source {@link Path}, or {@link Optional#empty()} if it has not been set
*/
public Optional<Path> getSourceFile() {
return sourceFile;
@@ -176,8 +190,10 @@ public abstract class AbstractRDFParser<T extends AbstractRDFParser<T>>
* Get the set source {@link Path}.
* <p>
* If this is {@link Optional#isPresent()}, then
- * {@link #getSourceInputStream()} and {@link #getSourceInputStream()()}
+ * {@link #getSourceInputStream()} and {@link #getSourceInputStream()}
* are {@link Optional#empty()}.
+ *
+ * @return The source {@link IRI}, or {@link Optional#empty()} if it has not been set
*/
public Optional<IRI> getSourceIri() {
return sourceIri;
@@ -283,11 +299,12 @@ public abstract class AbstractRDFParser<T extends AbstractRDFParser<T>>
/**
* Check if an iri is absolute.
* <p>
- * Used by {@link #source(String)} and {@link #base(String)}
+ * Used by {@link #source(String)} and {@link #base(String)}.
*
- * @param iri
+ * @param iri IRI to check
+ * @throws IllegalArgumentException If the IRI is not absolute
*/
- protected void checkIsAbsolute(IRI iri) {
+ protected void checkIsAbsolute(IRI iri) throws IllegalArgumentException {
if (!URI.create(iri.getIRIString()).isAbsolute()) {
throw new IllegalArgumentException("IRI is not absolute: " + iri);
}
@@ -327,7 +344,7 @@ public abstract class AbstractRDFParser<T extends AbstractRDFParser<T>>
*
* @throws IllegalStateException if base is required, but not set.
*/
- protected void checkBaseRequired() {
+ protected void checkBaseRequired() throws IllegalStateException {
if (!base.isPresent() && sourceInputStream.isPresent()
&& !contentTypeSyntax.filter(t -> t == RDFSyntax.NQUADS || t == RDFSyntax.NTRIPLES).isPresent()) {
throw new IllegalStateException("base iri required for inputstream source");
@@ -347,12 +364,11 @@ public abstract class AbstractRDFParser<T extends AbstractRDFParser<T>>
sourceFile = Optional.empty();
}
-
/**
- * Reset all optional target* fields to Optional.empty()</code>
+ * Reset all optional target* fields to {@link Optional#empty()}.
* <p>
* Note that the consumer set for {@link #getTarget()} is
- * NOT reset.
+ * <strong>note</strong> reset.
* <p>
* Subclasses should override this and call <code>super.resetTarget()</code>
* if they need to reset any additional target* fields.
http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/5afd0bd6/simple/src/main/java/org/apache/commons/rdf/simple/experimental/package-info.java
----------------------------------------------------------------------
diff --git a/simple/src/main/java/org/apache/commons/rdf/simple/experimental/package-info.java b/simple/src/main/java/org/apache/commons/rdf/simple/experimental/package-info.java
index 5196f42..c5f4a42 100644
--- a/simple/src/main/java/org/apache/commons/rdf/simple/experimental/package-info.java
+++ b/simple/src/main/java/org/apache/commons/rdf/simple/experimental/package-info.java
@@ -18,17 +18,14 @@
/**
* Experimental Commons RDF Simple implementations.
* <p>
- * Classes in this package should be considered <strong>at
- * risk</strong>; they might change or be removed in the next minor update of
- * Commons RDF.
+ * Classes in this package should be considered <strong>at risk</strong>; they
+ * might change or be removed in the next minor update of Commons RDF.
* <p>
* When a class has stabilized, it will move to the
* {@link org.apache.commons.rdf.simple} package.
- * <p>
* <ul>
- * <li>{@link AbstractRDFParser} - an abstract helper class
- * for implementations of
- * {@link org.apache.commons.rdf.api.experimental.RDFParser}.</li>
+ * <li>{@link AbstractRDFParser} - an abstract helper class for implementations
+ * of {@link org.apache.commons.rdf.experimental.RDFParser}.</li>
* </ul>
*/
package org.apache.commons.rdf.simple.experimental;
\ No newline at end of file