You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commonsrdf.apache.org by wi...@apache.org on 2015/03/27 19:15:08 UTC
[10/50] [abbrv] incubator-commonsrdf git commit: Merge branch
'ISSUE-45-equals' of https://github.com/stain/commons-rdf into
stain-ISSUE-45-equals
Merge branch 'ISSUE-45-equals' of https://github.com/stain/commons-rdf into stain-ISSUE-45-equals
Project: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/commit/3b2bebb6
Tree: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/tree/3b2bebb6
Diff: http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/diff/3b2bebb6
Branch: refs/heads/master
Commit: 3b2bebb64cf90441e45195b0e1149e404721b0a1
Parents: 5ac1bbb dbe8d13
Author: Peter Ansell <p_...@yahoo.com>
Authored: Mon Jan 26 15:55:26 2015 +1100
Committer: Peter Ansell <p_...@yahoo.com>
Committed: Mon Jan 26 15:55:26 2015 +1100
----------------------------------------------------------------------
.../com/github/commonsrdf/api/BlankNode.java | 52 +++++++++++++++++++-
.../java/com/github/commonsrdf/api/IRI.java | 41 ++++++++++++++-
.../java/com/github/commonsrdf/api/Literal.java | 41 ++++++++++++++-
.../java/com/github/commonsrdf/api/Triple.java | 36 ++++++++++++++
4 files changed, 167 insertions(+), 3 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/3b2bebb6/api/src/main/java/com/github/commonsrdf/api/BlankNode.java
----------------------------------------------------------------------
diff --cc api/src/main/java/com/github/commonsrdf/api/BlankNode.java
index 399381a,0000000..780cc15
mode 100644,000000..100644
--- a/api/src/main/java/com/github/commonsrdf/api/BlankNode.java
+++ b/api/src/main/java/com/github/commonsrdf/api/BlankNode.java
@@@ -1,80 -1,0 +1,130 @@@
+/**
+ * Licensed 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 com.github.commonsrdf.api;
+
+/**
- * An <a href= "http://www.w3.org/TR/rdf11-concepts/#dfn-blank-node" >RDF-1.1
++ * A <a href= "http://www.w3.org/TR/rdf11-concepts/#dfn-blank-node" >RDF-1.1
+ * Blank Node</a>, as defined by <a href=
+ * "http://www.w3.org/TR/rdf11-concepts/#section-blank-nodes" >RDF-1.1 Concepts
+ * and Abstract Syntax</a>, a W3C Recommendation published on 25 February 2014.<br>
+ *
+ * Note that: Blank nodes are disjoint from IRIs and literals. Otherwise,
+ * the set of possible blank nodes is arbitrary. RDF makes no reference to any
+ * internal structure of blank nodes.
+ *
+ * Also note that: Blank node identifiers are local identifiers that are
+ * used in some concrete RDF syntaxes or RDF store implementations. They are
+ * always locally scoped to the file or RDF store, and are not persistent or
+ * portable identifiers for blank nodes. Blank node identifiers are not part of
+ * the RDF abstract syntax, but are entirely dependent on the concrete syntax or
+ * implementation. The syntactic restrictions on blank node identifiers, if any,
+ * therefore also depend on the concrete RDF syntax or implementation.
+ * Implementations that handle blank node identifiers in concrete syntaxes need
+ * to be careful not to create the same blank node from multiple occurrences of
+ * the same blank node identifier except in situations where this is supported
+ * by the syntax.
+ *
+ * @see <a href= "http://www.w3.org/TR/rdf11-concepts/#dfn-blank-node">RDF-1.1
+ * Blank Node</a>
+ */
+public interface BlankNode extends BlankNodeOrIRI {
+
+ /**
+ * Return a <a href=
+ * "http://www.w3.org/TR/rdf11-concepts/#dfn-blank-node-identifier">label</a>
+ * for the blank node. This is not a serialization/syntax label. It should
+ * be uniquely identifying within the local scope it is created in but has
+ * no uniqueness guarantees other than that.
+ *
+ * In particular, the existence of two objects of type {@link BlankNode}
+ * with the same value returned from {@link #internalIdentifier()} are not
+ * equivalent unless they are known to have been created in the same local
+ * scope.
+ *
+ * An example of a local scope may be an instance of a Java Virtual Machine
+ * (JVM). In the context of a JVM instance, an implementor may support
+ * insertion and removal of {@link Triple} objects containing Blank Nodes
+ * without modifying the blank node labels.
+ *
+ * Another example of a local scope may be a <a
+ * href="http://www.w3.org/TR/rdf11-concepts/#section-rdf-graph">Graph</a>
+ * or <a
+ * href="http://www.w3.org/TR/rdf11-concepts/#section-dataset">Dataset</a>
+ * created from a single document. In this context, an implementor should
+ * reasonably guarantee that the label returned by getLabel only maps to
+ * equivalent blank nodes in the same Graph or Dataset, but they may not
+ * guarantee that it is unique for the JVM instance. In this case, the
+ * implementor may support a mechanism to provide a mapping for blank nodes
+ * between Graph or Dataset instances to guarantee their uniqueness.
+ *
+ * If implementors support <a
+ * href="http://www.w3.org/TR/rdf11-concepts/#section-skolemization"
+ * >Skolemisation</a>, they may map instances of {@link BlankNode} objects
+ * to {@link IRI} objects to reduce scoping issues.
+ *
+ * @return An internal, system identifier for the {@link BlankNode}.
+ */
+ String internalIdentifier();
++
++
++ /**
++ * Check it this BlankNode is equal to another BlankNode.
++ * <p>
++ * <blockquote cite="http://www.w3.org/TR/rdf11-concepts/#dfn-blank-node-identifier">
++ * <a href="http://www.w3.org/TR/rdf11-concepts/#dfn-blank-node-identifier">Blank
++ * node identifiers</a> are local identifiers that are used in some concrete
++ * RDF syntaxes or RDF store implementations. They are always locally scoped
++ * to the file or RDF store, and are <em>not</em> persistent or portable
++ * identifiers for blank nodes. Blank node identifiers are <em>not</em> part
++ * of the RDF abstract syntax, but are entirely dependent on the concrete
++ * syntax or implementation. The syntactic restrictions on blank node
++ * identifiers, if any, therefore also depend on the concrete RDF syntax or
++ * implementation. Implementations that handle blank node identifiers in
++ * concrete syntaxes need to be careful not to create the same blank node
++ * from multiple occurrences of the same blank node identifier except in
++ * situations where this is supported by the syntax.
++ * </blockquote>
++ * <p>
++ * Implementations MUST check the local scope, as two BlankNode in different
++ * Graphs MUST differ. On the other hand, two BlankNodes found in triples
++ * of the same Graph instance MUST equal if and only if they have the same
++ * {@link #internalIdentifier()}.
++ * <p>
++ * Implementations MUST also override {@link #hashCode()} so that two equal
++ * Literals produce the same hash code.
++ *
++ * @see Object#equals(Object)
++ *
++ * @param other
++ * @return true if other is a BlankNode, is in the same local scope and is
++ * equal to this BlankNode
++ */
++ @Override
++ public boolean equals(Object other);
++
++
++ /**
++ * Calculate a hash code for this BlankNode.
++ * <p>
++ * This method MUST be implemented when implementing {@link #equals(Object)}
++ * so that two equal BlankNodes produce the same hash code.
++ *
++ * @see Object#hashCode()
++ *
++ * @return a hash code value for this BlankNode.
++ */
++ @Override
++ public int hashCode();
+
+}
http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/3b2bebb6/api/src/main/java/com/github/commonsrdf/api/IRI.java
----------------------------------------------------------------------
diff --cc api/src/main/java/com/github/commonsrdf/api/IRI.java
index 7f9e35c,0000000..a2600f7
mode 100644,000000..100644
--- a/api/src/main/java/com/github/commonsrdf/api/IRI.java
+++ b/api/src/main/java/com/github/commonsrdf/api/IRI.java
@@@ -1,33 -1,0 +1,72 @@@
+/**
+ * Licensed 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 com.github.commonsrdf.api;
+
+/**
+ * An <a href= "http://www.w3.org/TR/rdf11-concepts/#dfn-iri"
+ * >RDF-1.1 IRI</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>
+ */
+public interface IRI extends BlankNodeOrIRI {
+
+ /**
- * Returns the IRI encoded as a native Unicode String.<br>
++ * Return the IRI encoded as a native Unicode String.<br>
+ *
+ * The returned string must not include URL-encoding to escape
+ * non-ASCII characters.
+ *
+ * @return The IRI encoded as a native Unicode String.
+ */
+ String getIRIString();
++
++ /**
++ * Check it this IRI is equal to another IRI.
++ * <p>
++ * <blockquote cite="http://www.w3.org/TR/rdf11-concepts/#dfn-iri-equality"> <a
++ * href="http://www.w3.org/TR/rdf11-concepts/#section-IRIs">IRI
++ * equality</a>: Two IRIs are equal if and only if they are equivalent under
++ * Simple String Comparison according to section 5.1 of [RFC3987]. Further
++ * normalization MUST NOT be performed when comparing IRIs for equality.
++ * </blockquote>
++ * <p>Two IRIs are equal are in the same local scope and their
++ * {@link #getIRIString()} are equal.
++ * <p>
++ * Implementations MAY check the local scope for IRI comparison.
++ * <p>
++ * Implementations MUST also override {@link #hashCode()} so that two equal
++ * IRIs produce the same hash code.
++ *
++ * @see Object#equals(Object)
++ *
++ * @param other
++ * @return true if other is an IRI and is equal to this
++ */
++ @Override
++ public boolean equals(Object other);
++
++
++ /**
++ * Calculate a hash code for this IRI.
++ * <p>
++ * This method MUST be implemented when implementing {@link #equals(Object)}
++ * so that two equal IRIs produce the same hash code.
++ *
++ * @see Object#hashCode()
++ *
++ * @return a hash code value for this IRI.
++ */
++ @Override
++ public int hashCode();
+}
http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/3b2bebb6/api/src/main/java/com/github/commonsrdf/api/Literal.java
----------------------------------------------------------------------
diff --cc api/src/main/java/com/github/commonsrdf/api/Literal.java
index 91485d9,0000000..bb93aee
mode 100644,000000..100644
--- a/api/src/main/java/com/github/commonsrdf/api/Literal.java
+++ b/api/src/main/java/com/github/commonsrdf/api/Literal.java
@@@ -1,69 -1,0 +1,108 @@@
+/**
+ * Licensed 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 com.github.commonsrdf.api;
+
+import java.util.Optional;
+
+/**
- * An RDF-1.1 Literal, as defined by <a href=
++ * A RDF-1.1 Literal, as defined by <a href=
+ * "http://www.w3.org/TR/rdf11-concepts/#section-Graph-Literal" >RDF-1.1
+ * Concepts and Abstract Syntax</a>, a W3C Recommendation published on 25
+ * February 2014
+ */
+public interface Literal extends RDFTerm {
+
+ /**
+ * The lexical form of this literal, represented by a <a
+ * href="http://www.unicode.org/versions/latest/">Unicode string</a>.
+ *
+ * @return The lexical form of this literal.
+ * @see <a
+ * href="http://www.w3.org/TR/rdf11-concepts/#dfn-lexical-form">RDF-1.1
+ * Literal lexical form</a>
+ */
+ String getLexicalForm();
+
+ /**
+ * The IRI identifying the datatype that determines how the lexical form
+ * maps to a literal value.
+ *
+ * @return The datatype IRI for this literal.
+ * @see <a
+ * href="http://www.w3.org/TR/rdf11-concepts/#dfn-datatype-iri">RDF-1.1
+ * Literal datatype IRI</a>
+ */
+ IRI getDatatype();
+
+ /**
+ * If and only if the datatype IRI is <a
+ * href="http://www.w3.org/1999/02/22-rdf-syntax-ns#langString"
+ * >http://www.w3.org/1999/02/22-rdf-syntax-ns#langString</a>, the language
+ * tag for this Literal is a non-empty language tag as defined by <a
+ * href="http://tools.ietf.org/html/bcp47">BCP47</a>.<br>
+ * If the datatype IRI is not <a
+ * href="http://www.w3.org/1999/02/22-rdf-syntax-ns#langString"
+ * >http://www.w3.org/1999/02/22-rdf-syntax-ns#langString</a>, this method
+ * must return {@link Optional#empty()}.
+ *
+ * @return The {@link Optional} language tag for this literal. If
+ * {@link Optional#isPresent()} returns true, the value returned by
+ * {@link Optional#get()} must be a non-empty string conforming to
+ * BCP47.
+ * @see <a
+ * href="http://www.w3.org/TR/rdf11-concepts/#dfn-language-tag">RDF-1.1
+ * Literal language tag</a>
+ */
+ Optional<String> getLanguageTag();
++
++ /**
++ * Check it this Literal is equal to another Literal.
++ * <p>
++ * <blockquote cite="http://www.w3.org/TR/rdf11-concepts/#dfn-literal-term">
++ * <a href="http://www.w3.org/TR/rdf11-concepts/#dfn-literal-term">Literal
++ * term equality</a>: Two literals are term-equal (the same RDF literal) if
++ * and only if the two lexical forms, the two datatype IRIs, and the two
++ * language tags (if any) compare equal, character by character. Thus, two
++ * literals can have the same value without being the same RDF term.
++ * </blockquote>
++ * <p>
++ * Implementations MAY check the local scope for Literal
++ * comparison.
++ * <p>
++ * Implementations MUST also override {@link #hashCode()} so that two equal
++ * Literals produce the same hash code.
++ *
++ * @see Object#equals(Object)
++ *
++ * @param other
++ * @return true if other is a Literal and is equal to this
++ */
++ @Override
++ public boolean equals(Object other);
++
++
++ /**
++ * Calculate a hash code for this Literal.
++ * <p>
++ * This method MUST be implemented when implementing {@link #equals(Object)}
++ * so that two equal Literals produce the same hash code.
++ *
++ * @see Object#hashCode()
++ *
++ * @return a hash code value for this Literal.
++ */
++ @Override
++ public int hashCode();
+
+}
http://git-wip-us.apache.org/repos/asf/incubator-commonsrdf/blob/3b2bebb6/api/src/main/java/com/github/commonsrdf/api/Triple.java
----------------------------------------------------------------------
diff --cc api/src/main/java/com/github/commonsrdf/api/Triple.java
index 4997aec,0000000..3badb30
mode 100644,000000..100644
--- a/api/src/main/java/com/github/commonsrdf/api/Triple.java
+++ b/api/src/main/java/com/github/commonsrdf/api/Triple.java
@@@ -1,58 -1,0 +1,94 @@@
+/**
+ * Licensed 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 com.github.commonsrdf.api;
+
+/**
+ * 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>
+ *
+ * @see <a href= "http://www.w3.org/TR/rdf11-concepts/#dfn-rdf-triple" >RDF-1.1
+ * Triple</a>
+ */
+public interface Triple {
+
+ /**
+ * The subject of this triple, 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.
+ * @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();
+
++ /**
++ * Check it this Triple is equal to another Triple.
++ * <p>
++ * <p>Two Triples are equal if and only if their
++ * {@link #getSubject()}, {@link #getPredicate()} and {@link #getObject()}
++ * are equal.
++ * <p>
++ * Implementations MUST check the local scope for Triple comparison
++ * if either the subject or object is a BlankNode, and MAY check the local
++ * scope in other cases.
++ * <p>
++ * Implementations MUST also override {@link #hashCode()} so that two equal
++ * Triples produce the same hash code.
++ *
++ * @see Object#equals(Object)
++ *
++ * @param other
++ * @return true if other is a Triple and is equal to this
++ */
++ @Override
++ public boolean equals(Object other);
++
++
++ /**
++ * Calculate a hash code for this Triple.
++ * <p>
++ * This method MUST be implemented when implementing {@link #equals(Object)}
++ * so that two equal IRIs produce the same hash code.
++ *
++ * @see Object#hashCode()
++ *
++ * @return a hash code value for this Triple.
++ */
++ @Override
++ public int hashCode();
++
+}