1 /**
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements. See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership. The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the
7 * "License"); you may not use this file except in compliance
8 * with the License. You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing, software
13 * distributed under the License is distributed on an "AS IS" BASIS,
14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 * See the License for the specific language governing permissions and
16 * limitations under the License.
17 */
18 package org.apache.commons.rdf.api;
19
20 import java.io.Serializable;
21 import java.util.Locale;
22
23 /**
24 * A RDF implementation.
25 * <p>
26 * A <code>RDF</code> implementation can create instances of the {@link RDFTerm}
27 * types {@link IRI}, {@link BlankNode} and {@link Literal}, as well as creating
28 * instances of the types {@link Triple}, {@link Quad}, {@link Graph} or
29 * {@link Dataset}.
30 * <p>
31 * A <em>partial RDF implementation</em> should be clearly documented as such,
32 * and may throw {@link UnsupportedOperationException} where applicable, e.g. if
33 * it does not support creating {@link Dataset}s or {@link Quad}s.
34 * <p>
35 * Instances of <code>RDF</code> work like a factory for creating Commons RDF
36 * instances. spezializations of this interface may also provide methods for
37 * conversions from/to their underlying RDF framework.
38 * <p>
39 * If a factory method of a particular implementation does not allow or support
40 * a provided parameter, e.g. because an IRI is considered invalid, then it
41 * SHOULD throw {@link IllegalArgumentException}.
42 *
43 * @since 0.3.0-incubating
44 * @see RDFTerm
45 * @see Graph
46 * @see Quad
47 */
48 public interface RDF {
49
50 /**
51 * Create a new blank node.
52 * <p>
53 * The returned blank node MUST NOT be equal to any existing
54 * {@link BlankNode} instances according to
55 * {@link BlankNode#equals(Object)}.
56 *
57 * @return A new, unique {@link BlankNode}
58 */
59 BlankNode createBlankNode();
60
61 /**
62 * Create a blank node based on the given name.
63 * <p>
64 * All {@link BlankNode}s created with the given <code>name</code> <em>on a
65 * particular instance</em> of <code>RDF</code> MUST be equivalent according
66 * to {@link BlankNode#equals(Object)},
67 * <p>
68 * The returned BlankNode MUST NOT be equal to <code>BlankNode</code>
69 * instances returned for any other <code>name</code> or those returned from
70 * {@link #createBlankNode()}.
71 * <p>
72 * The returned BlankNode SHOULD NOT be equivalent to any BlankNodes created
73 * on a <em>different</em> <code>RDF</code> instance, e.g. different
74 * instances of <code>RDF</code> should produce different blank nodes for
75 * the same <code>name</code> unless they purposely are intending to create
76 * equivalent {@link BlankNode} instances (e.g. a reinstated
77 * {@link Serializable} factory).
78 *
79 * @param name
80 * A non-empty, non-null, String that is unique to this blank
81 * node in the context of this {@link RDF}.
82 * @return A BlankNode for the given name
83 */
84 BlankNode createBlankNode(String name);
85
86 /**
87 * Create a new graph.
88 *
89 * It is undefined if the graph will be persisted by any underlying storage
90 * mechanism.
91 *
92 * @return A new Graph
93 */
94 Graph createGraph();
95
96 /**
97 * Create a new dataset.
98 *
99 * It is undefined if the dataset will be persisted by any underlying
100 * storage mechanism.
101 *
102 * @return A new Dataset
103 */
104 Dataset createDataset();
105
106 /**
107 * Create an IRI from a (possibly escaped) String.
108 *
109 * The provided iri string MUST be valid according to the
110 * <a href="http://www.w3.org/TR/rdf11-concepts/#dfn-iri">W3C RDF-1.1
111 * IRI</a> definition.
112 *
113 * @param iri
114 * Internationalized Resource Identifier
115 * @return A new IRI
116 * @throws IllegalArgumentException
117 * If the provided string is not acceptable, e.g. does not
118 * conform to the RFC3987 syntax.
119 */
120 IRI createIRI(String iri) throws IllegalArgumentException;
121
122 /**
123 * Create a simple literal.
124 *
125 * The provided lexical form should not be escaped in any sense, e.g. should
126 * not include "quotes" unless those are part of the literal value.
127 *
128 * The returned Literal MUST have a {@link Literal#getLexicalForm()} that is
129 * equal to the provided lexical form, MUST NOT have a
130 * {@link Literal#getLanguageTag()} present, and SHOULD return a
131 * {@link Literal#getDatatype()} that is equal to the IRI
132 * <code>http://www.w3.org/2001/XMLSchema#string</code>.
133 *
134 * @param lexicalForm
135 * The literal value in plain text
136 * @return The created Literal
137 * @throws IllegalArgumentException
138 * If the provided lexicalForm is not acceptable, e.g. because
139 * it is too large for an underlying storage.
140 */
141 Literal createLiteral(String lexicalForm) throws IllegalArgumentException;
142
143 /**
144 * Create a literal with the specified data type.
145 *
146 * The provided lexical form should not be escaped in any sense, e.g. should
147 * not include "quotes" unless those are part of the literal value.
148 *
149 * It is RECOMMENDED that the provided dataType is one of the <a href=
150 * "http://www.w3.org/TR/rdf11-concepts/#xsd-datatypes">RDF-compatible XSD
151 * types</a>.
152 *
153 * The provided lexical form SHOULD be in the
154 * <a href="http://www.w3.org/TR/rdf11-concepts/#dfn-lexical-space">lexical
155 * space</a> of the provided dataType.
156 *
157 * The returned Literal SHOULD have a {@link Literal#getLexicalForm()} that
158 * is equal to the provided lexicalForm, MUST NOT have a
159 * {@link Literal#getLanguageTag()} present, and MUST return a
160 * {@link Literal#getDatatype()} that is equivalent to the provided dataType
161 * IRI.
162 *
163 * @param lexicalForm
164 * The literal value
165 * @param dataType
166 * The data type IRI for the literal value, e.g.
167 * <code>http://www.w3.org/2001/XMLSchema#integer</code>
168 * @return The created Literal
169 * @throws IllegalArgumentException
170 * If any of the provided arguments are not acceptable, e.g.
171 * because the provided dataType is not permitted.
172 */
173 Literal createLiteral(String lexicalForm, IRI dataType) throws IllegalArgumentException;
174
175 /**
176 * Create a language-tagged literal.
177 *
178 * The provided lexical form should not be escaped in any sense, e.g. should
179 * not include "quotes" unless those are part of the literal value.
180 *
181 * The provided language tag MUST be valid according to
182 * <a href="http://tools.ietf.org/html/bcp47">BCP47</a>, e.g.
183 * <code>en</code>.
184 *
185 * The provided language tag
186 * <a href="http://www.w3.org/TR/rdf11-concepts/#dfn-language-tagged-string"
187 * >MAY be converted to lower case</a>.
188 *
189 * The returned Literal SHOULD have a {@link Literal#getLexicalForm()} which
190 * is equal to the provided lexicalForm, MUST return a
191 * {@link Literal#getDatatype()} that is equal to the IRI
192 * <code>http://www.w3.org/1999/02/22-rdf-syntax-ns#langString</code>, and
193 * MUST have a {@link Literal#getLanguageTag()} present which SHOULD be
194 * equal to the provided language tag (compared as
195 * {@link String#toLowerCase(Locale)} using {@link Locale#ENGLISH}).
196 *
197 * @param lexicalForm
198 * The literal value
199 * @param languageTag
200 * The non-empty language tag as defined by
201 * <a href="http://tools.ietf.org/html/bcp47">BCP47</a>
202 * @return The created Literal
203 * @throws IllegalArgumentException
204 * If the provided values are not acceptable, e.g. because the
205 * languageTag was syntactically invalid.
206 */
207 Literal createLiteral(String lexicalForm, String languageTag) throws IllegalArgumentException;
208
209 /**
210 * Create a triple.
211 *
212 * The returned Triple SHOULD have a {@link Triple#getSubject()} that is
213 * equal to the provided subject, a {@link Triple#getPredicate()} that is
214 * equal to the provided predicate, and a {@link Triple#getObject()} that is
215 * equal to the provided object.
216 *
217 * @param subject
218 * The IRI or BlankNode that is the subject of the triple
219 * @param predicate
220 * The IRI that is the predicate of the triple
221 * @param object
222 * The IRI, BlankNode or Literal that is the object of the triple
223 * @return The created Triple
224 * @throws IllegalArgumentException
225 * If any of the provided arguments are not acceptable, e.g.
226 * because a Literal has a lexicalForm that is too large for an
227 * underlying storage.
228 */
229 Triple createTriple(BlankNodeOrIRI subject, IRI predicate, RDFTerm object) throws IllegalArgumentException;
230
231 /**
232 * Create a quad.
233 * <p>
234 * The returned Quad SHOULD have a {@link Quad#getGraphName()} that is equal
235 * to the provided graphName, a {@link Quad#getSubject()} that is equal to
236 * the provided subject, a {@link Quad#getPredicate()} that is equal to the
237 * provided predicate, and a {@link Quad#getObject()} that is equal to the
238 * provided object.
239 *
240 * @param graphName
241 * The IRI or BlankNode that this quad belongs to, or
242 * <code>null</code> for the public graph
243 * @param subject
244 * The IRI or BlankNode that is the subject of the quad
245 * @param predicate
246 * The IRI that is the predicate of the quad
247 * @param object
248 * The IRI, BlankNode or Literal that is the object of the quad
249 * @return The created Quad
250 * @throws IllegalArgumentException
251 * If any of the provided arguments are not acceptable, e.g.
252 * because a Literal has a lexicalForm that is too large for an
253 * underlying storage.
254 */
255 Quad createQuad(BlankNodeOrIRI graphName, BlankNodeOrIRI subject, IRI predicate, RDFTerm object)
256 throws IllegalArgumentException;
257
258 }