[
https://issues.apache.org/jira/browse/COMMONSRDF-46?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=15614947#comment-15614947
]
ASF GitHub Bot commented on COMMONSRDF-46:
------------------------------------------
Github user stain commented on a diff in the pull request:
https://github.com/apache/incubator-commonsrdf/pull/25#discussion_r85502041
--- Diff: api/src/main/java/org/apache/commons/rdf/api/RDFTermFactory.java
---
@@ -17,262 +17,61 @@
*/
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.
+ * Factory for creating RDFTerm instances..
* <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
- * @see Quad
+ * This interface is <strong>deprecated</strong> in favour of
+ * the richer {@link RDF}.
+ *
+ * @see RDF
*/
+@Deprecated
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 {
--- End diff --
Yes, I removed the notion of `UnsupporetedOperationException` from `RDF` as
all our bundled implementations are complete and callers should not be too
worried about that.
The Javadoc now say that any partial `RDF` implementations should be
_clearly documented as such_:
> * 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.
Is this sufficient? E.g. an `RDF` instance within OWLAPI probably would not
know how to make a `Graph` or `Dataset` - but would be a bit more exotic
factory than the ones bundled within Commons RDF.
> 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)
