Java tutorial
/** * 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; /** * Factory for creating RDFTerm and Graph instances. * <p> * It is not specified how an implementation should provide a RDFTermFactory. * <p> * If an implementation does not support a particular method (e.g. it requires * additional parameters or can't create graphs), then it MAY throw * {@link UnsupportedOperationException}, as provided by the <code>default</code> * implementations in this interface. * <p> * If a factory method does not allow or support a provided parameter, e.g. * because an IRI is considered invalid, then it SHOULD throw * {@link IllegalArgumentException}. * * @see RDFTerm * @see Graph */ public interface RDFTermFactory { /** * 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} * @throws UnsupportedOperationException * If the operation is not supported. */ default BlankNode createBlankNode() throws UnsupportedOperationException { throw new UnsupportedOperationException("createBlankNode() not supported"); } /** * 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>RDFTermFactory</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>RDFTermFactory</code> instance, e.g. * different instances of <code>RDFTermFactory</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 RDFTermFactory}. * @return A BlankNode for the given name * @throws UnsupportedOperationException * If the operation is not supported. */ default BlankNode createBlankNode(String name) throws UnsupportedOperationException { throw new UnsupportedOperationException("createBlankNode(String) not supported"); } /** * Create a new graph. * * It is undefined if the graph will be persisted by any underlying storage * mechanism. * * @return A new Graph * @throws UnsupportedOperationException If the operation is not supported. */ default Graph createGraph() throws UnsupportedOperationException { throw new UnsupportedOperationException("createGraph() not supported"); } /** * 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. * @throws UnsupportedOperationException If the operation is not supported. */ default IRI createIRI(String iri) throws IllegalArgumentException, UnsupportedOperationException { throw new UnsupportedOperationException("createIRI(String) not supported"); } /** * 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. * @throws UnsupportedOperationException If the operation is not supported. */ default Literal createLiteral(String lexicalForm) throws IllegalArgumentException, UnsupportedOperationException { throw new UnsupportedOperationException("createLiteral(String) not supported"); } /** * 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. * @throws UnsupportedOperationException If the operation is not supported. */ default Literal createLiteral(String lexicalForm, IRI dataType) throws IllegalArgumentException, UnsupportedOperationException { throw new UnsupportedOperationException("createLiteral(String) not supported"); } /** * 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. * @throws UnsupportedOperationException If the operation is not supported. */ default Literal createLiteral(String lexicalForm, String languageTag) throws IllegalArgumentException, UnsupportedOperationException { throw new UnsupportedOperationException("createLiteral(String,String) not supported"); } /** * 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. * @throws UnsupportedOperationException If the operation is not supported. */ default Triple createTriple(BlankNodeOrIRI subject, IRI predicate, RDFTerm object) throws IllegalArgumentException, UnsupportedOperationException { throw new UnsupportedOperationException("createTriple(BlankNodeOrIRI,IRI,RDFTerm) not supported"); } }