001/**
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements. See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership. The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License.  You may obtain a copy of the License at
009 *
010 *     http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS,
014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 * See the License for the specific language governing permissions and
016 * limitations under the License.
017 */
018package org.apache.commons.rdf.api;
019
020/**
021 * An <a href= "http://www.w3.org/TR/rdf11-concepts/#dfn-rdf-term" >RDF-1.1
022 * Term</a>, as defined by
023 * <a href= "http://www.w3.org/TR/rdf11-concepts/" >RDF-1.1 Concepts and
024 * Abstract Syntax</a>, a W3C Recommendation published on 25 February 2014.
025 * <p>
026 * A {@link RDFTerm} object in Commons RDF is considered
027 * <strong>immutable</strong>, that is, over its life time it will have
028 * consistent behaviour for its {@link #equals(Object)} and {@link #hashCode()},
029 * and objects returned from its getter methods (e.g. {@link IRI#getIRIString()}
030 * and {@link Literal#getLanguageTag()}) will have consistent
031 * {@link #equals(Object)} behaviour.
032 * <p>
033 * Note that methods in <code>RDFTerm</code> and its Commons RDF specialisations
034 * {@link IRI}, {@link BlankNode} and {@link Literal} are not required to return
035 * object identical (<code>==</code>) instances as long as they are equivalent
036 * according to their {@link Object#equals(Object)}. Further specialisations may
037 * provide additional methods that are documented to be mutable.
038 * <p>
039 * Methods in <code>RDFTerm</code> and its Commons RDF specialisations
040 * {@link IRI}, {@link BlankNode} and {@link Literal} are
041 * <strong>thread-safe</strong>, however further specialisations may add
042 * additional methods that are documented to not be thread-safe.
043 * <p>
044 * <code>RDFTerm</code>s can be safely used in hashing collections like
045 * {@link java.util.HashSet} and {@link java.util.HashMap}.
046 * <p>
047 * Any <code>RDFTerm</code> can be used interchangeably across Commons RDF
048 * implementations.
049 *
050 * @see <a href= "http://www.w3.org/TR/rdf11-concepts/#dfn-rdf-term" >RDF-1.1
051 *      Term</a>
052 */
053public interface RDFTerm {
054
055    /**
056     * Return the term serialised as specified by the RDF-1.1 N-Triples
057     * Canonical form.
058     *
059     * @return The term serialised as RDF-1.1 N-Triples.
060     * @see <a href="http://www.w3.org/TR/n-triples/#canonical-ntriples">
061     *      RDF-1.1 N-Triples Canonical form</a>
062     */
063    String ntriplesString();
064
065        /**
066         * Check it this RDFTerm is equal to another RDFTerm.
067         * <p>
068         * If this object is an {@link IRI}, equality is checked using
069         * {@link IRI#equals(Object)}, or if this object is a {@link BlankNode},
070         * equality is checked using {@link BlankNode#equals(Object)}, or if this
071         * object is a {@link Literal}, equality is checked using
072         * {@link Literal#equals(Object)}.
073         * <p>
074         * Implementations MUST also override {@link #hashCode()} so that two equal
075         * Literals produce the same hash code.
076         *
077         * @see IRI#equals(Object)
078         * @see BlankNode#equals(Object)
079         * @see Literal#equals(Object)
080         *
081         * @param other
082         *            Another object
083         * @return true if other is a RDFTerm and is equal to this
084         */
085    @Override
086    boolean equals(Object other);
087
088        /**
089         * Calculate a hash code for this RDFTerm.
090         * <p>
091         * As an {@link RDFTerm} is <em>immutable</em>, this method will always
092         * return the same hashCode over the lifetime of this object.
093         * <p>
094         * This method MUST be implemented in conjunction with
095         * {@link #equals(Object)} so that two equal RDFTerm produce the same hash
096         * code.
097         *
098         * @see IRI#hashCode()
099         * @see Literal#hashCode()
100         * @see BlankNode#hashCode()
101         *
102         * @return a hash code value for this RDFTerm.
103         */
104    @Override
105    int hashCode();
106
107}