org.apache.commons.rdf.api.RDFSyntax Maven / Gradle / Ivy
Show all versions of commons-rdf-api Show documentation
/**
* 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.
*
* An RDF syntax is uniquely identified by its {@link #mediaType()}, and has a
* suggested {@link #fileExtension()}.
*
* Some of the RDF syntaxes may {@link #supportsDataset()}, meaning they can
* represent {@link Quad}s.
*
* 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. RDFSyntax.JSONLD.
*
*/
public interface RDFSyntax {
/**
* JSON-LD 1.0
*
* @see https://www.w3.org/TR/json-ld/
*
*/
public static RDFSyntax JSONLD = W3CRDFSyntax.JSONLD;
/**
* RDF 1.1 Turtle
*
* @see https://www.w3.org/TR/turtle/
*
*/
public static RDFSyntax TURTLE = W3CRDFSyntax.TURTLE;
/**
* RDF 1.1 N-Quads
*
* @see https://www.w3.org/TR/n-quads/
*/
public static RDFSyntax NQUADS = W3CRDFSyntax.NQUADS;
/**
* RDF 1.1 N-Triples
*
* @see https://www.w3.org/TR/n-triples/
*/
public static RDFSyntax NTRIPLES = W3CRDFSyntax.NTRIPLES;
/**
* HTML+RDFa 1.1 and XHTML+RDFa 1.1
*
* @see https://www.w3.org/TR/html-rdfa/
* @see https://www.w3.org/TR/xhtml-rdfa/
*/
public static RDFSyntax RDFA = W3CRDFSyntax.RDFA;
/**
* RDF 1.1 XML Syntax
*
* @see https://www.w3.org/TR/rdf-syntax-grammar/
*/
public static RDFSyntax RDFXML = W3CRDFSyntax.RDFXML;
/**
* RDF 1.1 TriG
*
* @see https://www.w3.org/TR/trig/
*/
public static RDFSyntax TRIG = W3CRDFSyntax.TRIG;
/**
* A short name of the RDF Syntax e.g. JSONLD.
*
* The name is specific to Commons RDF and carries no particular meaning.
*
* @return Short name for RDF syntax
*/
public String name();
/**
* The title of the RDF Syntax.
*
* This is generally the title of the corresponding standard,
* e.g. RDF 1.1 Turtle.
*
* @return Title of RDF Syntax
*/
public String title();
/**
* The IANA media type for
* the RDF syntax.
*
* The media type can be used as part of Content-Type and
* Accept for content negotiation in the
* HTTP
* protocol.
*
* @return The registered media type of the RDF Syntax
*/
public String mediaType();
/**
* Set of IANA media types that
* covers this RDF syntax, including any non-official media types.
*
* The media type can be used as part of Content-Type and
* Accept for content negotiation in the
* HTTP
* protocol.
*
* 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 public Set mediaTypes() {
return Collections.singleton(mediaType());
}
/**
* The IANA-registered
* file extension.
*
* The file extension includes the leading period, e.g. .jsonld
*
* @return The registered file extension of the RDF Syntax
*/
public String fileExtension();
/**
* Set of file extensions for this RDF syntax, including any non-official extensions.
*
* The file extension includes the leading period, e.g. .jsonld
*
* 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 public Set fileExtensions() {
return Collections.singleton(fileExtension());
}
/**
* Indicate if this RDF syntax supports
* RDF
* Datasets.
*
* @return true if this RDF Syntax supports datasets; false otherwise
*/
public boolean supportsDataset();
/**
* Return the {@link IRI} that identifies the RDF syntax.
*
* Note that the identifying IRI is generally distinct from the IRI of the
* document that specifies the RDF syntax.
*
* @return Identifying IRI, e.g.
* http://www.w3.org/ns/formats/JSON-LD
*/
public IRI iri();
/**
* Compare this RDFSyntax with another object.
*
* 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.
*
* 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. N3 and
* TriX.
*
* 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 RDF
* 1.1 Primer
* @see org.apache.commons.rdf.experimental.RDFParser
*/
public static Set w3cSyntaxes() {
return W3CRDFSyntax.syntaxes;
}
/**
* Return the RDFSyntax with the specified media type.
*
* The mediaType 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.
*
* If the media type specifies parameters, e.g.
* text/turtle; charset=ascii, only the part of the string to
* before ; is considered.
*
* 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.
*/
public static Optional 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.
*
* The fileExtension is compared in lower case to all
* extensions supported, therefore it might not be equal to the
* {@link RDFSyntax#fileExtension} of the returned RDFSyntax.
*
* This method support all syntaxes returned by {@link #w3cSyntaxes()}.
*
* @param fileExtension
* The fileExtension to match, starting with .
* @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.
*/
public static Optional 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()}.
*
* This method support all syntaxes returned by {@link #w3cSyntaxes()}.
*
* @param name
* The name to match, , e.g. "JSONLD"
* @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.
*/
public static Optional byName(final String name) {
return w3cSyntaxes().stream().filter(t -> t.name().equals(name)).findAny();
}
}