| /** |
| * 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"); |
| } |
| |
| } |
