/**
 * 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.io.Serializable;
import java.util.Locale;

/**
 * A RDF implementation.
 * <p>
 * A <code>RDF</code> implementation can create instances of the {@link RDFTerm}
 * types {@link IRI}, {@link BlankNode} and {@link Literal}, as well as creating
 * instances of the types {@link Triple}, {@link Quad}, {@link Graph} or
 * {@link Dataset}.
 * <p>
 * A <em>partial RDF implementation</em> should be clearly documented as such,
 * and may throw {@link UnsupportedOperationException} where applicable, e.g. if
 * it does not support creating {@link Dataset}s or {@link Quad}s.
 * <p>
 * Instances of <code>RDF</code> work like a factory for creating Commons RDF
 * instances. spezializations of this interface may also provide methods for
 * conversions from/to their underlying RDF framework.
 * <p>
 * If a factory method of a particular implementation does not allow or support
 * a provided parameter, e.g. because an IRI is considered invalid, then it
 * SHOULD throw {@link IllegalArgumentException}.
 *
 * @since 0.3.0-incubating
 * @see RDFTerm
 * @see Graph
 * @see Quad
 */
public interface RDF {

    /**
     * Create a new blank node.
     * <p>
     * The returned blank node MUST NOT be equal to any existing
     * {@link BlankNode} instances according to
     * {@link BlankNode#equals(Object)}.
     *
     * @return A new, unique {@link BlankNode}
     */
    public BlankNode createBlankNode();

    /**
     * Create a blank node based on the given name.
     * <p>
     * All {@link BlankNode}s created with the given <code>name</code> <em>on a
     * particular instance</em> of <code>RDF</code> MUST be equivalent according
     * to {@link BlankNode#equals(Object)},
     * <p>
     * The returned BlankNode MUST NOT be equal to <code>BlankNode</code>
     * instances returned for any other <code>name</code> or those returned from
     * {@link #createBlankNode()}.
     * <p>
     * The returned BlankNode SHOULD NOT be equivalent to any BlankNodes created
     * on a <em>different</em> <code>RDF</code> instance, e.g. different
     * instances of <code>RDF</code> should produce different blank nodes for
     * the same <code>name</code> unless they purposely are intending to create
     * equivalent {@link BlankNode} instances (e.g. a reinstated
     * {@link Serializable} factory).
     *
     * @param name
     *            A non-empty, non-null, String that is unique to this blank
     *            node in the context of this {@link RDF}.
     * @return A BlankNode for the given name
     */
    public BlankNode createBlankNode(String name);

    /**
     * Create a new graph.
     *
     * It is undefined if the graph will be persisted by any underlying storage
     * mechanism.
     *
     * @return A new Graph
     */
    public Graph createGraph();

    /**
     * Create a new dataset.
     *
     * It is undefined if the dataset will be persisted by any underlying
     * storage mechanism.
     *
     * @return A new Dataset
     */
    public Dataset createDataset();

    /**
     * Create an IRI from a (possibly escaped) String.
     *
     * The provided iri string MUST be valid according to the
     * <a href="http://www.w3.org/TR/rdf11-concepts/#dfn-iri">W3C RDF-1.1
     * IRI</a> definition.
     *
     * @param iri
     *            Internationalized Resource Identifier
     * @return A new IRI
     * @throws IllegalArgumentException
     *             If the provided string is not acceptable, e.g. does not
     *             conform to the RFC3987 syntax.
     */
    public IRI createIRI(String iri) throws IllegalArgumentException;

    /**
     * Create a simple literal.
     *
     * The provided lexical form should not be escaped in any sense, e.g. should
     * not include "quotes" unless those are part of the literal value.
     *
     * The returned Literal MUST have a {@link Literal#getLexicalForm()} that is
     * equal to the provided lexical form, MUST NOT have a
     * {@link Literal#getLanguageTag()} present, and SHOULD return a
     * {@link Literal#getDatatype()} that is equal to the IRI
     * <code>http://www.w3.org/2001/XMLSchema#string</code>.
     *
     * @param lexicalForm
     *            The literal value in plain text
     * @return The created Literal
     * @throws IllegalArgumentException
     *             If the provided lexicalForm is not acceptable, e.g. because
     *             it is too large for an underlying storage.
     */
    public Literal createLiteral(String lexicalForm) throws IllegalArgumentException;

    /**
     * Create a literal with the specified data type.
     *
     * The provided lexical form should not be escaped in any sense, e.g. should
     * not include "quotes" unless those are part of the literal value.
     *
     * It is RECOMMENDED that the provided dataType is one of the <a href=
     * "http://www.w3.org/TR/rdf11-concepts/#xsd-datatypes">RDF-compatible XSD
     * types</a>.
     *
     * The provided lexical form SHOULD be in the
     * <a href="http://www.w3.org/TR/rdf11-concepts/#dfn-lexical-space">lexical
     * space</a> of the provided dataType.
     *
     * The returned Literal SHOULD have a {@link Literal#getLexicalForm()} that
     * is equal to the provided lexicalForm, MUST NOT have a
     * {@link Literal#getLanguageTag()} present, and MUST return a
     * {@link Literal#getDatatype()} that is equivalent to the provided dataType
     * IRI.
     *
     * @param lexicalForm
     *            The literal value
     * @param dataType
     *            The data type IRI for the literal value, e.g.
     *            <code>http://www.w3.org/2001/XMLSchema#integer</code>
     * @return The created Literal
     * @throws IllegalArgumentException
     *             If any of the provided arguments are not acceptable, e.g.
     *             because the provided dataType is not permitted.
     */
    public Literal createLiteral(String lexicalForm, IRI dataType) throws IllegalArgumentException;

    /**
     * Create a language-tagged literal.
     *
     * The provided lexical form should not be escaped in any sense, e.g. should
     * not include "quotes" unless those are part of the literal value.
     *
     * The provided language tag MUST be valid according to
     * <a href="http://tools.ietf.org/html/bcp47">BCP47</a>, e.g.
     * <code>en</code>.
     *
     * The provided language tag
     * <a href="http://www.w3.org/TR/rdf11-concepts/#dfn-language-tagged-string"
     * >MAY be converted to lower case</a>.
     *
     * The returned Literal SHOULD have a {@link Literal#getLexicalForm()} which
     * is equal to the provided lexicalForm, MUST return a
     * {@link Literal#getDatatype()} that is equal to the IRI
     * <code>http://www.w3.org/1999/02/22-rdf-syntax-ns#langString</code>, and
     * MUST have a {@link Literal#getLanguageTag()} present which SHOULD be
     * equal to the provided language tag (compared as
     * {@link String#toLowerCase(Locale)} using {@link Locale#ENGLISH}).
     *
     * @param lexicalForm
     *            The literal value
     * @param languageTag
     *            The non-empty language tag as defined by
     *            <a href="http://tools.ietf.org/html/bcp47">BCP47</a>
     * @return The created Literal
     * @throws IllegalArgumentException
     *             If the provided values are not acceptable, e.g. because the
     *             languageTag was syntactically invalid.
     */
    public Literal createLiteral(String lexicalForm, String languageTag) throws IllegalArgumentException;

    /**
     * Create a triple.
     *
     * The returned Triple SHOULD have a {@link Triple#getSubject()} that is
     * equal to the provided subject, a {@link Triple#getPredicate()} that is
     * equal to the provided predicate, and a {@link Triple#getObject()} that is
     * equal to the provided object.
     *
     * @param subject
     *            The IRI or BlankNode that is the subject of the triple
     * @param predicate
     *            The IRI that is the predicate of the triple
     * @param object
     *            The IRI, BlankNode or Literal that is the object of the triple
     * @return The created Triple
     * @throws IllegalArgumentException
     *             If any of the provided arguments are not acceptable, e.g.
     *             because a Literal has a lexicalForm that is too large for an
     *             underlying storage.
     */
    public Triple createTriple(BlankNodeOrIRI subject, IRI predicate, RDFTerm object) throws IllegalArgumentException;

    /**
     * Create a quad.
     * <p>
     * The returned Quad SHOULD have a {@link Quad#getGraphName()} that is equal
     * to the provided graphName, a {@link Quad#getSubject()} that is equal to
     * the provided subject, a {@link Quad#getPredicate()} that is equal to the
     * provided predicate, and a {@link Quad#getObject()} that is equal to the
     * provided object.
     *
     * @param graphName
     *            The IRI or BlankNode that this quad belongs to, or
     *            <code>null</code> for the public graph
     * @param subject
     *            The IRI or BlankNode that is the subject of the quad
     * @param predicate
     *            The IRI that is the predicate of the quad
     * @param object
     *            The IRI, BlankNode or Literal that is the object of the quad
     * @return The created Quad
     * @throws IllegalArgumentException
     *             If any of the provided arguments are not acceptable, e.g.
     *             because a Literal has a lexicalForm that is too large for an
     *             underlying storage.
     */
    public Quad createQuad(BlankNodeOrIRI graphName, BlankNodeOrIRI subject, IRI predicate, RDFTerm object)
            throws IllegalArgumentException;

}