Repository: incubator-commonsrdf Updated Branches: refs/heads/master 6c673b719 -> fc70462eb
Add Quad and TripleOrQuad Project: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/commit/7639fd7c Tree: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/tree/7639fd7c Diff: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/diff/7639fd7c Branch: refs/heads/master Commit: 7639fd7c9de649361a7eaeeb3c9d8b620dc54afc Parents: 73994db Author: Stian Soiland-Reyes <st...@apache.org> Authored: Fri Apr 8 14:24:11 2016 +0100 Committer: Stian Soiland-Reyes <st...@apache.org> Committed: Fri Apr 8 14:24:11 2016 +0100 ---------------------------------------------------------------------- .../java/org/apache/commons/rdf/api/Quad.java | 209 +++++++++++++++++++ .../java/org/apache/commons/rdf/api/Triple.java | 2 +- .../apache/commons/rdf/api/TripleOrQuad.java | 64 ++++++ 3 files changed, 274 insertions(+), 1 deletion(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/7639fd7c/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 new file mode 100644 index 0000000..088533b --- /dev/null +++ b/api/src/main/java/org/apache/commons/rdf/api/Quad.java @@ -0,0 +1,209 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.apache.commons.rdf.api; + +import java.util.Objects; +import java.util.Optional; + +/** + * A Quad is a statement in a + * <a href= "http://www.w3.org/TR/rdf11-concepts/#section-dataset"; >RDF-1.1 + * Dataset</a>, as defined by + * <a href= "https://www.w3.org/TR/2014/NOTE-rdf11-datasets-20140225/"; >RDF-1.1 + * Concepts and Abstract Syntax</a>, a W3C Working Group Note published on 25 + * February 2014. + * + * @see <a href="http://www.w3.org/TR/2014/NOTE-rdf11-datasets-20140225/";>RDF + * 1.1: On Semantics of RDF Datasets</a> + * @see <a href="http://www.w3.org/TR/rdf11-concepts/#section-dataset";> </a> + */ +public interface Quad extends TripleOrQuad { + + /** + * The graph name (graph label) of this quad, if present. + * + * 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 + * {@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. + * + * @return If {@link Optional#isPresent()}, the graph name + * {@link BlankNodeOrIRI} of this quad, otherwise + * {@link Optional#empty()}, indicating the default graph. + * + * @see <a href="https://www.w3.org/TR/rdf11-concepts/#dfn-rdf-dataset";>RDF- + * 1.1 Dataset</a> + */ + Optional<BlankNodeOrIRI> getGraphName(); + + /** + * The subject of this quad, which may be either a {@link BlankNode} or an + * {@link IRI}, which are represented in Commons RDF by the interface + * {@link BlankNodeOrIRI}. + * + * @return The subject {@link BlankNodeOrIRI} of this quad. + * @see <a href="http://www.w3.org/TR/rdf11-concepts/#dfn-subject";>RDF-1.1 + * Triple subject</a> + */ + BlankNodeOrIRI getSubject(); + + /** + * The predicate {@link IRI} of this triple. + * + * @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> + */ + IRI getPredicate(); + + /** + * The object of this triple, which may be either a {@link BlankNode}, an + * {@link IRI}, or a {@link Literal}, which are represented in Commons RDF + * by the interface {@link RDFTerm}. + * + * @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> + */ + RDFTerm getObject(); + + /** + * Convert this {@link Quad} to a {@link Triple}. + * <p> + * The returned {@link Triple} will have equivalent values returned from the + * methods {@link TripleOrQuad#getSubject()}, + * {@link TripleOrQuad#getPredicate()} and {@link TripleOrQuad#getObject()} + * (their values MUST be {@link RDFTerm#equals(Object)}) - however the + * property values MAY be different instances. + * <p> + * The returned {@link Triple} MUST NOT be {@link #equals(Object)} to this + * {@link Quad}, even if this quad has a default graph + * {@link #getGraphName()} value of {@link Optional#empty()}, but MUST + * follow the {@link Triple#equals(Object)) semantics. This means that the + * following MUST be true: + * + * <pre> + * Quad q1, q2; + * if (q1.equals(q2)) { + * assert(q1.asTriple().equals(q2.asTriple())); + * } else if (q1.asTriple().equals(q2.asTriple())) { + * assert(q1.getSubject().equals(q2.getSubject())); + * assert(q1.getPredicate().equals(q2.getPredicate())); + * assert(q1.getObject().equals(q2.getObject())); + * assert(! q1.getGraphName().equals(q2.getGraphName())); + * } + * </pre> + * + * The <code>default</code> implementation of this method return a proxy + * {@link Triple} instance that keeps a reference to this {@link Quad} to + * calls the underlying {@link TripleOrQuad} methods, but supplies a + * {@link Triple} compatible implementation of {@link Triple#equals(Object)} + * and {@link Triple#hashCode()}. Implementations may override this method, + * e.g. for a more efficient solution. + * + * @return A {@link Triple} that contains the same {@link TripleOrQuad} + * properties as this Quad. + */ + default Triple asTriple() { + return new Triple() { + @Override + public BlankNodeOrIRI getSubject() { + return Quad.this.getSubject(); + } + + @Override + public IRI getPredicate() { + return Quad.this.getPredicate(); + } + + @Override + public RDFTerm getObject() { + return Quad.this.getObject(); + } + + @Override + public boolean equals(Object obj) { + if (!(obj instanceof Triple)) { + return false; + } + Triple other = (Triple) obj; + return Objects.equals(getSubject(), other.getSubject()) + && Objects.equals(getPredicate(), other.getPredicate()) + && Objects.equals(getObject(), other.getObject()); + } + + @Override + public int hashCode() { + return Objects.hash(getSubject(), getPredicate(), getObject()); + } + }; + } + + /** + * Check it this Quad is equal to another Quad. + * <p> + * Two Triples are equal if and only if their {@link #getGraphName()}, + * {@link #getSubject()}, {@link #getPredicate()} and + * {@link #getObject()} are equal. + * </p> + * <p> + * Implementations MUST also override {@link #hashCode()} so that two equal + * Quads produce the same hash code. + * </p> + * <p> + * Note that a {@link Quad} MUST NOT be equal to a + * {@link Triple}, even if this Quad's {@link #getGraphName()} + * is {@link Optional#empty()}. To test triple-like equivalence, + * callers can use: + * </p> + * <pre> + * Quad q1; + * Triple t2; + * q1.asTriple().equals(t2)); + * </pre> + * + * @param other + * Another object + * @return true if other is a Quad and is equal to this + * @see Object#equals(Object) + */ + @Override + public boolean equals(Object other); + + /** + * Calculate a hash code for this Quad. + * <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(), #getGraphName()}. + * <p> + * This method MUST be implemented in conjunction with + * {@link #equals(Object)} so that two equal {@link Quad}s produce the same + * hash code. + * + * @return a hash code value for this Quad. + * @see Object#hashCode() + * @see Objects#hash(Object...) + */ + @Override + public int hashCode(); + +} http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/7639fd7c/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 b52a51d..0725913 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 @@ -28,7 +28,7 @@ import java.util.Objects; * @see <a href= "http://www.w3.org/TR/rdf11-concepts/#dfn-rdf-triple"; >RDF-1.1 * Triple</a> */ -public interface Triple { +public interface Triple extends TripleOrQuad { /** * The subject of this triple, which may be either a {@link BlankNode} or an http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/7639fd7c/api/src/main/java/org/apache/commons/rdf/api/TripleOrQuad.java ---------------------------------------------------------------------- diff --git a/api/src/main/java/org/apache/commons/rdf/api/TripleOrQuad.java b/api/src/main/java/org/apache/commons/rdf/api/TripleOrQuad.java new file mode 100644 index 0000000..755bb99 --- /dev/null +++ b/api/src/main/java/org/apache/commons/rdf/api/TripleOrQuad.java @@ -0,0 +1,64 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.apache.commons.rdf.api; + +/** + * Common "triple-like" interface for {@link Triple} and {@link Quad} + * <p> + * A TripleOrQuad has at least a + * {@link #getSubject()}, {@link #getPredicate()} and + * {@link #getObject()}, but unlike a {@link Triple} does not have a + * formalized {@link Triple#equals(Object)} semantics, and does not + * neccesarily have a {@link Quad#getGraphLabel()} + * <p> + * Implementations of this interface SHOULD also implement {@link Triple} + * or {@link Quad}, but MUST NOT implement both interfaces. + */ +public interface TripleOrQuad { + + /** + * The subject of this triple/quad, which may be either a {@link BlankNode} or an + * {@link IRI}, which are represented in Commons RDF by the interface + * {@link BlankNodeOrIRI}. + * + * @return The subject {@link BlankNodeOrIRI} of this triple/quad. + * @see <a href="http://www.w3.org/TR/rdf11-concepts/#dfn-subject";>RDF-1.1 + * Triple subject</a> + */ + BlankNodeOrIRI getSubject(); + + /** + * The predicate {@link IRI} of this triple/quad. + * + * @return The predicate {@link IRI} of this triple/quad. + * @see <a href="http://www.w3.org/TR/rdf11-concepts/#dfn-predicate";>RDF-1.1 + * Triple predicate</a> + */ + IRI getPredicate(); + + /** + * The object of this triple/quad, which may be either a {@link BlankNode}, an + * {@link IRI}, or a {@link Literal}, which are represented in Commons RDF + * by the interface {@link RDFTerm}. + * + * @return The object {@link RDFTerm} of this triple/quad. + * @see <a href="http://www.w3.org/TR/rdf11-concepts/#dfn-object";>RDF-1.1 + * Triple object</a> + */ + RDFTerm getObject(); +}
