/**
 * 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.Collections;
import java.util.Locale;
import java.util.Optional;
import java.util.Set;

/**
 * An RDF syntax, e.g. as used for parsing and writing RDF.
 * <p>
 * An RDF syntax is uniquely identified by its {@link #mediaType()}, and has a
 * suggested {@link #fileExtension()}.
 * <p>
 * Some of the RDF syntaxes may {@link #supportsDataset()}, meaning they can
 * represent {@link Quad}s.
 * <p>
 * An enumeration of the official RDF 1.1 syntaxes is available in
 * {@link W3CRDFSyntax} - for convenience they are also accessible
 * as constants here, e.g. <code>RDFSyntax.JSONLD</code>.
 *
 */
public interface RDFSyntax {

    /**
     * JSON-LD 1.0
     *
     * @see <a href=
     *      "https://www.w3.org/TR/json-ld/">https://www.w3.org/TR/json-ld/</a>
     *
     */
    static RDFSyntax JSONLD = W3CRDFSyntax.JSONLD;

    /**
     * RDF 1.1 Turtle
     *
     * @see <a href=
     *      "https://www.w3.org/TR/turtle/">https://www.w3.org/TR/turtle/</a>
     *
     */
    static RDFSyntax TURTLE = W3CRDFSyntax.TURTLE;

    /**
     * RDF 1.1 N-Quads
     *
     * @see <a href=
     *      "https://www.w3.org/TR/n-quads/">https://www.w3.org/TR/n-quads/</a>
     */
    static RDFSyntax NQUADS = W3CRDFSyntax.NQUADS;

    /**
     * RDF 1.1 N-Triples
     *
     * @see <a href=
     *      "https://www.w3.org/TR/n-triples/">https://www.w3.org/TR/n-triples/</a>
     */
    static RDFSyntax NTRIPLES = W3CRDFSyntax.NTRIPLES;

    /**
     * HTML+RDFa 1.1 and XHTML+RDFa 1.1
     *
     * @see <a href=
     *      "https://www.w3.org/TR/html-rdfa/">https://www.w3.org/TR/html-rdfa/</a>
     * @see <a href=
     *      "https://www.w3.org/TR/xhtml-rdfa/">https://www.w3.org/TR/xhtml-rdfa/</a>
     */
    static RDFSyntax RDFA = W3CRDFSyntax.RDFA;

    /**
     * RDF 1.1 XML Syntax
     *
     * @see <a href=
     *      "https://www.w3.org/TR/rdf-syntax-grammar/">https://www.w3.org/TR/rdf-syntax-grammar/</a>
     */
    static RDFSyntax RDFXML = W3CRDFSyntax.RDFXML;

    /**
     * RDF 1.1 TriG
     *
     * @see <a href=
     *      "https://www.w3.org/TR/trig/">https://www.w3.org/TR/trig/</a>
     */
    static RDFSyntax TRIG = W3CRDFSyntax.TRIG;

    /**
     * A short name of the RDF Syntax e.g. <code>JSONLD</code>.
     * <p>
     * The name is specific to Commons RDF and carries no particular meaning.
     *
     * @return Short name for RDF syntax
     */
    String name();

    /**
     * The title of the RDF Syntax.
     * <p>
     * This is generally the title of the corresponding standard,
     * e.g. <em>RDF 1.1 Turtle</em>.
     *
     * @return Title of RDF Syntax
     */
    String title();

    /**
     * The <a href="https://tools.ietf.org/html/rfc2046">IANA media type</a> for
     * the RDF syntax.
     * <p>
     * The media type can be used as part of <code>Content-Type</code> and
     * <code>Accept</code> for <em>content negotiation</em> in the
     * <a href="https://tools.ietf.org/html/rfc7231#section-3.1.1.1">HTTP
     * protocol</a>.
     *
     * @return The registered media type of the RDF Syntax
     */
    String mediaType();

    /**
     * Set of <a href="https://tools.ietf.org/html/rfc2046">IANA media types</a> that
     * covers this RDF syntax, including any non-official media types.
     * <p>
     * The media type can be used as part of <code>Content-Type</code> and
     * <code>Accept</code> for <em>content negotiation</em> in the
     * <a href="https://tools.ietf.org/html/rfc7231#section-3.1.1.1">HTTP
     * protocol</a>.
     * <p>
     * The returned Set MUST include the value {@link #mediaType()}; this is the
     * behaviour of the default implementation.
     *
     * @return The media types corresponding to the RDF Syntax
     */
    default Set<String> mediaTypes() {
        return Collections.singleton(mediaType());
    }

    /**
     * The <a href="https://tools.ietf.org/html/rfc2046">IANA-registered</a>
     * file extension.
     * <p>
     * The file extension includes the leading period, e.g. <code>.jsonld</code>
     *
     * @return The registered file extension of the RDF Syntax
     */
    String fileExtension();

    /**
     * Set of file extensions for this RDF syntax, including any non-official extensions.
     * <p>
     * The file extension includes the leading period, e.g. <code>.jsonld</code>
     * <p>
     * The returned Set MUST include the value from {@link #fileExtension()}; this is
     * the behaviour of the default implementation.
     *
     * @return The file extensions corresponding to the RDF Syntax
     */
    default Set<String> fileExtensions() {
        return Collections.singleton(fileExtension());
    }

    /**
     * Indicate if this RDF syntax supports
     * <a href="https://www.w3.org/TR/rdf11-concepts/#section-dataset">RDF
     * Datasets</a>.
     *
     * @return true if this RDF Syntax supports datasets; false otherwise
     */
    boolean supportsDataset();

    /**
     * Return the {@link IRI} that <em>identifies</em> the RDF syntax.
     * <p>
     * Note that the identifying IRI is generally distinct from the IRI of the
     * document that <em>specifies</em> the RDF syntax.
     *
     * @return Identifying IRI, e.g.
     *         <code>http://www.w3.org/ns/formats/JSON-LD</code>
     */
    IRI iri();

    /**
     * Compare this RDFSyntax with another object.
     * <p>
     * Two {@link RDFSyntax}es are considered equal if their
     * {@link #mediaType()}s are equal when compared as lower case strings
     * according to {@link String#toLowerCase(Locale)} with the locale
     * {@link Locale#ROOT}.
     *
     * @param obj the object with which to compare
     * @return true if this object is the same as the obj argument; false otherwise
     */
    @Override
    boolean equals(Object obj);

    /**
     * The hash code of an RDFSyntax is equivalent to the hash code
     * of the {@link #mediaType()} in lower case according to
     * {@link String#toLowerCase(Locale)} with the locale
     * {@link Locale#ROOT}.
     *
     * @return Hash code of RDFSyntax
     */
    @Override
    int hashCode();

    /**
     * Return the RDF 1.1 serialization syntaxes.
     * <p>
     * This lists the W3C standardized RDF 1.1 syntaxes like {@link #TURTLE} and
     * {@link #JSONLD}. Note the existence of other RDF syntaxes that are not
     * included here, e.g. <a href="http://www.w3.org/TeamSubmission/n3/">N3</a> and
     * <a href="https://en.wikipedia.org/wiki/TriX_%28syntax%29">TriX</a>.
     * <p>
     * The syntaxes returned only support the {@link #mediaType()}
     * and {@link #fileExtension()} as defined in the corresponding
     * W3C specification.
     *
     * @return
     *      A set of the official RDF 1.1 {@link RDFSyntax}es.
     *
     * @see <a href="https://www.w3.org/TR/rdf11-primer/#section-graph-syntax">RDF
     *      1.1 Primer</a>
     * @see org.apache.commons.rdf.experimental.RDFParser
     */

    static Set<RDFSyntax> w3cSyntaxes() {
        return W3CRDFSyntax.syntaxes;
    }

    /**
     * Return the RDFSyntax with the specified media type.
     * <p>
     * The <code>mediaType</code> is compared in lower case to all media types
     * supported, therefore it might not be equal to the
     * {@link RDFSyntax#mediaType} of the returned RDFSyntax.
     * <p>
     * If the media type specifies parameters, e.g.
     * <code>text/turtle; charset=ascii</code>, only the part of the string to
     * before <code>;</code> is considered.
     * <p>
     * This method support all syntaxes returned by {@link #w3cSyntaxes()}.
     *
     * @param mediaType
     *            The media type to match
     * @return If {@link Optional#isPresent()}, the {@link RDFSyntax} which has
     *         a matching {@link RDFSyntax#mediaType()}, otherwise
     *         {@link Optional#empty()} indicating that no matching syntax was
     *         found.
     */
    static Optional<RDFSyntax> byMediaType(final String mediaType) {
        final String type = mediaType.toLowerCase(Locale.ROOT).split("\\s*;", 2)[0];
        return w3cSyntaxes().stream().filter(t -> t.mediaTypes().contains(type))
                .findAny();
    }

    /**
     * Return the RDFSyntax with the specified file extension.
     * <p>
     * The <code>fileExtension</code> is compared in lower case to all
     * extensions supported, therefore it might not be equal to the
     * {@link RDFSyntax#fileExtension} of the returned RDFSyntax.
     * <p>
     * This method support all syntaxes returned by {@link #w3cSyntaxes()}.
     *
     * @param fileExtension
     *            The fileExtension to match, starting with <code>.</code>
     * @return If {@link Optional#isPresent()}, the {@link RDFSyntax} which has
     *         a matching {@link RDFSyntax#fileExtension()}, otherwise
     *         {@link Optional#empty()} indicating that no matching file
     *         extension was found.
     */
    static Optional<RDFSyntax> byFileExtension(final String fileExtension) {
        final String ext = fileExtension.toLowerCase(Locale.ROOT);
        return w3cSyntaxes().stream().filter(t -> t.fileExtensions().contains(ext))
                .findAny();
    }

    /**
     * Return the RDFSyntax with the specified {@link #name()}.
     * <p>
     * This method support all syntaxes returned by {@link #w3cSyntaxes()}.
     *
     * @param name
     *            The name to match, , e.g. <code>"JSONLD"</code>
     * @return If {@link Optional#isPresent()}, the {@link RDFSyntax} which has
     *         a matching {@link RDFSyntax#name()}, otherwise
     *         {@link Optional#empty()} indicating that no matching name was found.
     */
    static Optional<RDFSyntax> byName(final String name) {
        return w3cSyntaxes().stream().filter(t -> t.name().equals(name)).findAny();
    }


}