[
https://issues.apache.org/jira/browse/COMMONSRDF-46?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=15613395#comment-15613395
]
ASF GitHub Bot commented on COMMONSRDF-46:
------------------------------------------
Github user ansell commented on a diff in the pull request:
https://github.com/apache/incubator-commonsrdf/pull/25#discussion_r85231233
--- Diff: api/src/main/java/org/apache/commons/rdf/api/RDF.java ---
@@ -0,0 +1,244 @@
+/**
+ * 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;
+
+/**
+ * A RDF implementation.
+ * <p>
+ * A <code>RDF</code> implementation can create instances of
+ * the {@link RDFTerm} types
+ * {@link IRI}, {@link BlankNode} and {@link Literal}, as well as creating
+ * instances of the types {@link Triple}, {@link Quad}, {@link Graph} or
+ * {@link Dataset}.
+ * <p>
+ * A <em>partial RDF implementation</em>
+ * should be clearly documented as such, and may throw
+ * {@link UnsupportedOperationException} where applicable, e.g. if it
+ * does not support creating {@link Dataset}s or {@link Quad}s.
+ * <p>
+ * Instances of <code>RDF</code> work like a factory for
+ * creating Commons RDF instances.
+ * spezializations of this interface may also provide methods
+ * for conversions from/to their underlying RDF framework.
+ * <p>
+ * If a factory method of a particular implementation does not allow or
support
+ * a provided parameter, e.g. because an IRI is considered invalid, then it
+ * SHOULD throw {@link IllegalArgumentException}.
+ *
+ * @since 0.3.0-incubating
+ * @see RDFTerm
+ * @see Graph
+ * @see Quad
+ */
+public interface RDF {
+
+ /**
+ * 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}
+ */
+ public BlankNode createBlankNode();
+
+ /**
+ * 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>RDF</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>RDF</code> instance, e.g.
+ * different instances of <code>RDF</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 RDF}.
+ * @return A BlankNode for the given name
+ */
+ public BlankNode createBlankNode(String name);
+
+ /**
+ * Create a new graph.
+ *
+ * It is undefined if the graph will be persisted by any underlying
storage
+ * mechanism.
+ *
+ * @return A new Graph
+ */
+ public Graph createGraph();
--- End diff --
Indentation, and other similar instances in this class.
> Rename RDFTermFactory to RDF
> ----------------------------
>
> Key: COMMONSRDF-46
> URL: https://issues.apache.org/jira/browse/COMMONSRDF-46
> Project: Apache Commons RDF
> Issue Type: Bug
> Components: api
> Reporter: Stian Soiland-Reyes
> Assignee: Stian Soiland-Reyes
> Fix For: 0.3.0
>
>
> As [mentioned on
> dev@commons|https://lists.apache.org/thread.html/ff9f0eda82a70fea38bd46781a062d182cd7792aee57a4563f854b27@%3Cdev.commonsrdf.apache.org%3E],
> the {{RDFTermFactory}} will grow in 0.3.0 to include {{Dataset}} and
> {{Quad}} creation, which are not {{RDFTerm}} instances.
> As well, the new implementations of RDFTermFactory for Jena and RDF4J also
> include converter methods from/to their underlying types - which feel
> somewhat wrong in a "factory" as they may are free to wrap/unwrap rather than
> make new instances.
> So the suggestion is a radical style change - rename {{RDFTermFactory}} to
> {{RDF}}, and its children to {{SimpleRDF}} {{JenaRDF}}, {{RDF4J}},
> {{JsonLDRDF}}.
> Typical usage then looks pretty neat:
> {code}
> RDF rdf = new JenaRDF();
> IRI iri = rdf.createIRI("http://example.com/";);
> Triple triple = rdf.createTriple(iri, iri, iri);
> Graph graph = rdf.createGraph();
> graph.add(triple);
> {code}
> but works less well as a static constant {{RDF}}:
> {code}
> private static final RDF RDF = new JenaRDF();
> {code}
> (before {{FACTORY}} might have made sense)
> Some style considerations:
> * {{RDF4JRDF}} looks weird, so just {{RDF4J}} there
> * {{SimpleRDF}} looks good (as Simple does not exists outside Commons RDF)
> * Jena already have
> [org.apache.jena](https://jena.apache.org/documentation/javadoc/jena/org/apache/jena/Jena.html),
> so {{JenaRDF}} is better than another {{Jena}}
> * {{JsonLdRDF}}
> * Documentation about just {{RDF}} the interface can be confusing against
> _RDF_ the concept, requiring using {{<code>}}-style typography and expanded
> phrases like "an {{RDF}} implementation" instead of "an {{RDF}}"
> A milder variant is: {{RDFFactory}} with children {{SimpleRDFFactory}},
> {{JenaFactory}}, {{RDF4JFactory}}. {{JsonLDFactory}} -- here we can skip
> {{RDF}} from the children except from the newbie {{Simple}}.
--
This message was sent by Atlassian JIRA
(v6.3.4#6332)
