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-iri" >RDF-1.1 IRI</a>,
022 * as defined by <a href= "http://www.w3.org/TR/rdf11-concepts/#section-IRIs" >RDF-1.1
023 * Concepts and Abstract Syntax</a>, a W3C Recommendation published on 25
024 * February 2014.
025 *
026 * @see RDF#createIRI(String)
027 */
028public interface IRI extends BlankNodeOrIRI {
029
030    /**
031     * Return the IRI encoded as a native Unicode String.<br>
032     *
033     * The returned string must not include URL-encoding to escape non-ASCII
034     * characters.
035     *
036     * @return The IRI encoded as a native Unicode String.
037     */
038    String getIRIString();
039
040    /**
041     * Check it this IRI is equal to another IRI. <blockquote>
042     * <a href="http://www.w3.org/TR/rdf11-concepts/#section-IRIs">IRI
043     * equality</a>: Two IRIs are equal if and only if they are equivalent under
044     * Simple String Comparison according to section 5.1 of [RFC3987]. Further
045     * normalization MUST NOT be performed when comparing IRIs for equality.
046     * </blockquote>
047     *
048     * Two IRI instances are equal if and only if their {@link #getIRIString()}
049     * are equal.
050     *
051     * Implementations MUST also override {@link #hashCode()} so that two equal
052     * IRIs produce the same hash code.
053     *
054     * @param other
055     *            Another object
056     * @return true if other is an IRI and is equal to this
057     * @see Object#equals(Object)
058     */
059    @Override
060    boolean equals(Object other);
061
062    /**
063     * Calculate a hash code for this IRI.
064     * <p>
065     * The returned hash code MUST be equal to the {@link String#hashCode()} of
066     * the {@link #getIRIString()}.
067     * <p>
068     * This method MUST be implemented in conjunction with
069     * {@link #equals(Object)} so that two equal IRIs produce the same hash
070     * code.
071     *
072     * @return a hash code value for this IRI.
073     * @see Object#hashCode()
074     */
075    @Override
076    int hashCode();
077}