You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commonsrdf.apache.org by stain <gi...@git.apache.org> on 2016/10/28 15:47:20 UTC

[GitHub] incubator-commonsrdf pull request #27: COMMONSRDF-47 RDFSyntax as an interfa...

GitHub user stain opened a pull request:

    https://github.com/apache/incubator-commonsrdf/pull/27

    COMMONSRDF-47 RDFSyntax as an interface

    [COMMONSRDF-47](https://issues.apache.org/jira/browse/COMMONSRDF-47)
    
    RDFSyntax  as an interface, with OfficialRDFSyntax is the enum - which implements the interface
    
    basically .mediaType -> .mediaType() etc
    
    One problem is that you can't override `.equals()` on an enum - and presumably it might be useful to compare if two RDFSyntaxes are the same? 
    
    Do we need to add our own `.equals()` and `.hashCode()` contract here as well (using `mediaType()`)  and get rid of the enum?
    
    we will also have to tweak the japicmp config as it (rightfully) complains about `RDFSyntax` changing its signature since 0.2.0, e.g. 
    
    ```
    ***! MODIFIED INTERFACE (<- ENUM) : PUBLIC ABSTRACT (<- NON_ABSTRACT) NON_FINAL (<- FINAL) org.apache.commons.rdf.api.RDFSyntax  (class type modified)
            ---* REMOVED INTERFACE: java.lang.Comparable
            ---* REMOVED INTERFACE: java.io.Serializable
            ***! MODIFIED SUPERCLASS: java.lang.Object (<- java.lang.Enum)
            ***! MODIFIED FIELD: PUBLIC STATIC FINAL org.apache.commons.rdf.api.RDFSyntax$OfficialRDFSyntax (<- org.apache.commons.rdf.api.RDFSyntax) RDFA_XHTML
            ***! MODIFIED FIELD: PUBLIC STATIC FINAL org.apache.commons.rdf.api.RDFSyntax$OfficialRDFSyntax (<- org.apache.commons.rdf.api.RDFSyntax) NQUADS
            ***! MODIFIED FIELD: PUBLIC STATIC FINAL org.apache.commons.rdf.api.RDFSyntax$OfficialRDFSyntax (<- org.apache.commons.rdf.api.RDFSyntax) RDFA_HTML
            ---! REMOVED FIELD: PUBLIC(-) FINAL(-) java.lang.String mediaType
            ---! REMOVED FIELD: PUBLIC(-) FINAL(-) boolean supportsDataset
            ***! MODIFIED FIELD: PUBLIC STATIC FINAL org.apache.commons.rdf.api.RDFSyntax$OfficialRDFSyntax (<- org.apache.commons.rdf.api.RDFSyntax) RDFXML
            ---! REMOVED FIELD: PUBLIC(-) FINAL(-) java.lang.String fileExtension
            ***! MODIFIED FIELD: PUBLIC STATIC FINAL org.apache.commons.rdf.api.RDFSyntax$OfficialRDFSyntax (<- org.apache.commons.rdf.api.RDFSyntax) TURTLE
            ***! MODIFIED FIELD: PUBLIC STATIC FINAL org.apache.commons.rdf.api.RDFSyntax$OfficialRDFSyntax (<- org.apache.commons.rdf.api.RDFSyntax) NTRIPLES
            ***! MODIFIED FIELD: PUBLIC STATIC FINAL org.apache.commons.rdf.api.RDFSyntax$OfficialRDFSyntax (<- org.apache.commons.rdf.api.RDFSyntax) TRIG
            ***! MODIFIED FIELD: PUBLIC STATIC FINAL org.apache.commons.rdf.api.RDFSyntax$OfficialRDFSyntax (<- org.apache.commons.rdf.api.RDFSyntax) JSONLD
            +++* NEW METHOD: PUBLIC(+) ABSTRACT(+) java.lang.String fileExtension()
            +++* NEW METHOD: PUBLIC(+) ABSTRACT(+) java.lang.String mediaType()
            +++* NEW METHOD: PUBLIC(+) ABSTRACT(+) java.lang.String name()
            +++* NEW METHOD: PUBLIC(+) ABSTRACT(+) boolean supportsDataset()
            +++* NEW METHOD: PUBLIC(+) ABSTRACT(+) java.lang.String title()
            ---  REMOVED METHOD: PUBLIC(-) java.lang.String toString()
            ---! REMOVED METHOD: PUBLIC(-) STATIC(-) org.apache.commons.rdf.api.RDFSyntax valueOf(java.lang.String)
            ---! REMOVED METHOD: PUBLIC(-) STATIC(-) org.apache.commons.rdf.api.RDFSyntax[] values()
    ```
    
    My suggestion is to delay this till past 0.3.0, as we're not settling `RDFParser` now anyway.

You can merge this pull request into a Git repository by running:

    $ git pull https://github.com/apache/incubator-commonsrdf COMMONSRDF-47

Alternatively you can review and apply these changes as the patch at:

    https://github.com/apache/incubator-commonsrdf/pull/27.patch

To close this pull request, make a commit to your master/trunk branch
with (at least) the following in the commit message:

    This closes #27
    
----
commit ee725a5aaf5d94c9ab5ff7f355bb5d0cb370bfa7
Author: Stian Soiland-Reyes <st...@apache.org>
Date:   2016-10-28T15:34:49Z

    COMMONSRDF-47 RDFSyntax as an interface
    
    OfficialRDFSyntax is the enum - which implements the interface
    
    basically .mediaType -> .mediaType() etc

----


---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---

[GitHub] incubator-commonsrdf pull request #27: COMMONSRDF-47 RDFSyntax as an interfa...

Posted by ansell <gi...@git.apache.org>.
Github user ansell commented on a diff in the pull request:

    https://github.com/apache/incubator-commonsrdf/pull/27#discussion_r88350737
  
    --- Diff: api/src/main/java/org/apache/commons/rdf/api/RDFSyntax.java ---
    @@ -22,6 +22,124 @@
     import java.util.Optional;
     
     /**
    + * An RDF syntax, e.g. as used for parsing and writing RDF.
    + * <p>
    + * An RDF syntax is uniquely identified by its {@link #mediaType()}, and has a
    + * suggested {@link #fileExtension()}.
    + * <p>
    + * Some of the RDF syntaxes may {@link #supportsDataset()}, meaning they can
    + * represent {@link Quad}s.
    + * <p>
    + * An enumeration of the official RDF 1.1 syntaxes is available in 
    + * {@link OfficialRDFSyntax} - for convenience they are also accessible
    + * as constants here, e.g. <code>RDFSyntax.JSONLD</code>.
    + * 
    + */
    +public interface RDFSyntax {
    + 
    +    public static OfficialRDFSyntax JSONLD = OfficialRDFSyntax.JSONLD;
    +    public static OfficialRDFSyntax TURTLE = OfficialRDFSyntax.TURTLE;
    +    public static OfficialRDFSyntax NQUADS = OfficialRDFSyntax.NQUADS;
    +    public static OfficialRDFSyntax NTRIPLES = OfficialRDFSyntax.NTRIPLES;
    +    public static OfficialRDFSyntax RDFA_HTML = OfficialRDFSyntax.RDFA_HTML;
    +    public static OfficialRDFSyntax RDFA_XHTML = OfficialRDFSyntax.RDFA_XHTML;
    +    public static OfficialRDFSyntax RDFXML = OfficialRDFSyntax.RDFXML;
    +    public static OfficialRDFSyntax TRIG = OfficialRDFSyntax.TRIG;
    +    
    +    /**
    +     * A short name of the RDF Syntax.
    +     * <p>
    +     * The name typically corresponds to the {@link Enum#name()} of for
    +     * {@link OfficialRDFSyntax}, e.g. <code>JSONLD</code>.
    +     * 
    +     * @return Short name for RDF syntax
    +     */
    +    public String name();
    +
    +    /**
    +     * The title of the RDF Syntax.
    +     * <p>
    +     * This is generally the title of the corresponding standard, 
    +     * e.g. <em>RDF 1.1 Turtle</em>.
    +     * 
    +     * @return Title of RDF Syntax
    +     */
    +    public String title();    
    +    
    +    /**
    +     * The <a href="https://tools.ietf.org/html/rfc2046">IANA media type</a> for
    +     * the RDF syntax.
    +     * <p>
    +     * The media type can be used as part of <code>Content-Type</code> and
    +     * <code>Accept</code> for <em>content negotiation</em> in the
    +     * <a href="https://tools.ietf.org/html/rfc7231#section-3.1.1.1">HTTP
    +     * protocol</a>.
    +     */
    +    public String mediaType();
    +
    +    /**
    +     * The <a href="https://tools.ietf.org/html/rfc2046">IANA-registered</a>
    +     * file extension.
    +     * <p>
    +     * The file extension includes the leading period, e.g. <code>.jsonld</code>
    +     */
    +    public String fileExtension();
    --- End diff --
    
    Do you plan on supporting alternative less used file extensions here?


---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---

[GitHub] incubator-commonsrdf pull request #27: COMMONSRDF-47 RDFSyntax as an interfa...

Posted by acoburn <gi...@git.apache.org>.
Github user acoburn commented on a diff in the pull request:

    https://github.com/apache/incubator-commonsrdf/pull/27#discussion_r88735941
  
    --- Diff: api/src/main/java/org/apache/commons/rdf/api/RDFSyntax.java ---
    @@ -22,6 +22,124 @@
     import java.util.Optional;
     
     /**
    + * An RDF syntax, e.g. as used for parsing and writing RDF.
    + * <p>
    + * An RDF syntax is uniquely identified by its {@link #mediaType()}, and has a
    + * suggested {@link #fileExtension()}.
    + * <p>
    + * Some of the RDF syntaxes may {@link #supportsDataset()}, meaning they can
    + * represent {@link Quad}s.
    + * <p>
    + * An enumeration of the official RDF 1.1 syntaxes is available in 
    + * {@link OfficialRDFSyntax} - for convenience they are also accessible
    + * as constants here, e.g. <code>RDFSyntax.JSONLD</code>.
    + * 
    + */
    +public interface RDFSyntax {
    + 
    +    public static OfficialRDFSyntax JSONLD = OfficialRDFSyntax.JSONLD;
    +    public static OfficialRDFSyntax TURTLE = OfficialRDFSyntax.TURTLE;
    +    public static OfficialRDFSyntax NQUADS = OfficialRDFSyntax.NQUADS;
    +    public static OfficialRDFSyntax NTRIPLES = OfficialRDFSyntax.NTRIPLES;
    +    public static OfficialRDFSyntax RDFA_HTML = OfficialRDFSyntax.RDFA_HTML;
    +    public static OfficialRDFSyntax RDFA_XHTML = OfficialRDFSyntax.RDFA_XHTML;
    +    public static OfficialRDFSyntax RDFXML = OfficialRDFSyntax.RDFXML;
    +    public static OfficialRDFSyntax TRIG = OfficialRDFSyntax.TRIG;
    +    
    +    /**
    +     * A short name of the RDF Syntax.
    +     * <p>
    +     * The name typically corresponds to the {@link Enum#name()} of for
    +     * {@link OfficialRDFSyntax}, e.g. <code>JSONLD</code>.
    +     * 
    +     * @return Short name for RDF syntax
    +     */
    +    public String name();
    +
    +    /**
    +     * The title of the RDF Syntax.
    +     * <p>
    +     * This is generally the title of the corresponding standard, 
    +     * e.g. <em>RDF 1.1 Turtle</em>.
    +     * 
    +     * @return Title of RDF Syntax
    +     */
    +    public String title();    
    +    
    +    /**
    +     * The <a href="https://tools.ietf.org/html/rfc2046">IANA media type</a> for
    +     * the RDF syntax.
    +     * <p>
    +     * The media type can be used as part of <code>Content-Type</code> and
    +     * <code>Accept</code> for <em>content negotiation</em> in the
    +     * <a href="https://tools.ietf.org/html/rfc7231#section-3.1.1.1">HTTP
    +     * protocol</a>.
    +     */
    +    public String mediaType();
    +
    +    /**
    +     * The <a href="https://tools.ietf.org/html/rfc2046">IANA-registered</a>
    +     * file extension.
    +     * <p>
    +     * The file extension includes the leading period, e.g. <code>.jsonld</code>
    +     */
    +    public String fileExtension();
    +
    +    /**
    +     * Indicate if this RDF syntax supports
    +     * <a href="https://www.w3.org/TR/rdf11-concepts/#section-dataset">RDF
    +     * Datasets</a>.
    +     */
    +    public boolean supportsDataset();
    +
    +
    +    /**
    +     * Return the RDFSyntax with the specified media type.
    +     * <p>
    +     * The <code>mediaType</code> is compared in lower case, therefore it might
    +     * not be equal to the {@link RDFSyntax#mediaType} of the returned
    +     * RDFSyntax.
    +     * <p>
    +     * For convenience matching of media types used in a
    +     * <code>Content-Type</code> header, if the <code>mediaType</code> contains
    +     * the characters <code>;</code>, <code>,</code> or white space, only the
    +     * part of the string to the left of those characters are considered.
    +     * 
    +     * @param mediaType
    +     *            The media type to match
    +     * @return If {@link Optional#isPresent()}, the {@link RDFSyntax} which has
    +     *         a matching {@link RDFSyntax#mediaType}, otherwise
    +     *         {@link Optional#empty()} indicating that no matching syntax was
    +     *         found.
    +     */
    +    public static Optional<RDFSyntax> byMediaType(String mediaType) {
    +        final String type = mediaType.toLowerCase(Locale.ENGLISH).split("\\s*[;,]", 2)[0];
    --- End diff --
    
    According to https://www.ietf.org/rfc/rfc2045.txt, it seems that splitting on `\\s*;` would be more accurate.


---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---

[GitHub] incubator-commonsrdf pull request #27: COMMONSRDF-47 RDFSyntax as an interfa...

Posted by ansell <gi...@git.apache.org>.
Github user ansell commented on a diff in the pull request:

    https://github.com/apache/incubator-commonsrdf/pull/27#discussion_r88350517
  
    --- Diff: api/src/main/java/org/apache/commons/rdf/api/RDFSyntax.java ---
    @@ -34,7 +152,7 @@
      *      1.1 Primer</a>
      * @see org.apache.commons.rdf.experimental.RDFParser
      */
    -public enum RDFSyntax {
    +  public enum OfficialRDFSyntax implements RDFSyntax {
    --- End diff --
    
    Also add a note that not all syntaxes that have W3C IRIs are listed here.
    
    https://www.w3.org/ns/formats/
    
    Adding support for those URIs would be nice btw, even though media types are still the main basis.


---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---

[GitHub] incubator-commonsrdf pull request #27: COMMONSRDF-47 RDFSyntax as an interfa...

Posted by ansell <gi...@git.apache.org>.
Github user ansell commented on a diff in the pull request:

    https://github.com/apache/incubator-commonsrdf/pull/27#discussion_r88565661
  
    --- Diff: api/src/main/java/org/apache/commons/rdf/api/RDFSyntax.java ---
    @@ -22,6 +22,124 @@
     import java.util.Optional;
     
     /**
    + * An RDF syntax, e.g. as used for parsing and writing RDF.
    + * <p>
    + * An RDF syntax is uniquely identified by its {@link #mediaType()}, and has a
    + * suggested {@link #fileExtension()}.
    + * <p>
    + * Some of the RDF syntaxes may {@link #supportsDataset()}, meaning they can
    + * represent {@link Quad}s.
    + * <p>
    + * An enumeration of the official RDF 1.1 syntaxes is available in 
    + * {@link OfficialRDFSyntax} - for convenience they are also accessible
    + * as constants here, e.g. <code>RDFSyntax.JSONLD</code>.
    + * 
    + */
    +public interface RDFSyntax {
    + 
    +    public static OfficialRDFSyntax JSONLD = OfficialRDFSyntax.JSONLD;
    +    public static OfficialRDFSyntax TURTLE = OfficialRDFSyntax.TURTLE;
    +    public static OfficialRDFSyntax NQUADS = OfficialRDFSyntax.NQUADS;
    +    public static OfficialRDFSyntax NTRIPLES = OfficialRDFSyntax.NTRIPLES;
    +    public static OfficialRDFSyntax RDFA_HTML = OfficialRDFSyntax.RDFA_HTML;
    +    public static OfficialRDFSyntax RDFA_XHTML = OfficialRDFSyntax.RDFA_XHTML;
    +    public static OfficialRDFSyntax RDFXML = OfficialRDFSyntax.RDFXML;
    +    public static OfficialRDFSyntax TRIG = OfficialRDFSyntax.TRIG;
    +    
    +    /**
    +     * A short name of the RDF Syntax.
    +     * <p>
    +     * The name typically corresponds to the {@link Enum#name()} of for
    +     * {@link OfficialRDFSyntax}, e.g. <code>JSONLD</code>.
    +     * 
    +     * @return Short name for RDF syntax
    +     */
    +    public String name();
    +
    +    /**
    +     * The title of the RDF Syntax.
    +     * <p>
    +     * This is generally the title of the corresponding standard, 
    +     * e.g. <em>RDF 1.1 Turtle</em>.
    +     * 
    +     * @return Title of RDF Syntax
    +     */
    +    public String title();    
    +    
    +    /**
    +     * The <a href="https://tools.ietf.org/html/rfc2046">IANA media type</a> for
    +     * the RDF syntax.
    +     * <p>
    +     * The media type can be used as part of <code>Content-Type</code> and
    +     * <code>Accept</code> for <em>content negotiation</em> in the
    +     * <a href="https://tools.ietf.org/html/rfc7231#section-3.1.1.1">HTTP
    +     * protocol</a>.
    +     */
    +    public String mediaType();
    +
    +    /**
    +     * The <a href="https://tools.ietf.org/html/rfc2046">IANA-registered</a>
    +     * file extension.
    +     * <p>
    +     * The file extension includes the leading period, e.g. <code>.jsonld</code>
    +     */
    +    public String fileExtension();
    +
    +    /**
    +     * Indicate if this RDF syntax supports
    +     * <a href="https://www.w3.org/TR/rdf11-concepts/#section-dataset">RDF
    +     * Datasets</a>.
    +     */
    +    public boolean supportsDataset();
    +
    +
    +    /**
    +     * Return the RDFSyntax with the specified media type.
    +     * <p>
    +     * The <code>mediaType</code> is compared in lower case, therefore it might
    +     * not be equal to the {@link RDFSyntax#mediaType} of the returned
    +     * RDFSyntax.
    +     * <p>
    +     * For convenience matching of media types used in a
    +     * <code>Content-Type</code> header, if the <code>mediaType</code> contains
    +     * the characters <code>;</code>, <code>,</code> or white space, only the
    +     * part of the string to the left of those characters are considered.
    +     * 
    +     * @param mediaType
    +     *            The media type to match
    +     * @return If {@link Optional#isPresent()}, the {@link RDFSyntax} which has
    +     *         a matching {@link RDFSyntax#mediaType}, otherwise
    +     *         {@link Optional#empty()} indicating that no matching syntax was
    +     *         found.
    +     */
    +    public static Optional<RDFSyntax> byMediaType(String mediaType) {
    +        final String type = mediaType.toLowerCase(Locale.ENGLISH).split("\\s*[;,]", 2)[0];
    +        return Arrays.stream(OfficialRDFSyntax.values()).filter(t -> t.mediaType().equals(type))
    --- End diff --
    
    If OfficialRDFSyntax was not an enum, then you could redefine the .values() method to return Set<RDFSyntax> and remove the .map call below that would then be performing an unnecessary cast.


---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---

[GitHub] incubator-commonsrdf pull request #27: COMMONSRDF-47 RDFSyntax as an interfa...

Posted by ansell <gi...@git.apache.org>.
Github user ansell commented on a diff in the pull request:

    https://github.com/apache/incubator-commonsrdf/pull/27#discussion_r88351040
  
    --- Diff: api/src/main/java/org/apache/commons/rdf/api/RDFSyntax.java ---
    @@ -22,6 +22,124 @@
     import java.util.Optional;
     
     /**
    + * An RDF syntax, e.g. as used for parsing and writing RDF.
    + * <p>
    + * An RDF syntax is uniquely identified by its {@link #mediaType()}, and has a
    + * suggested {@link #fileExtension()}.
    + * <p>
    + * Some of the RDF syntaxes may {@link #supportsDataset()}, meaning they can
    + * represent {@link Quad}s.
    + * <p>
    + * An enumeration of the official RDF 1.1 syntaxes is available in 
    + * {@link OfficialRDFSyntax} - for convenience they are also accessible
    + * as constants here, e.g. <code>RDFSyntax.JSONLD</code>.
    + * 
    + */
    +public interface RDFSyntax {
    + 
    +    public static OfficialRDFSyntax JSONLD = OfficialRDFSyntax.JSONLD;
    +    public static OfficialRDFSyntax TURTLE = OfficialRDFSyntax.TURTLE;
    +    public static OfficialRDFSyntax NQUADS = OfficialRDFSyntax.NQUADS;
    +    public static OfficialRDFSyntax NTRIPLES = OfficialRDFSyntax.NTRIPLES;
    +    public static OfficialRDFSyntax RDFA_HTML = OfficialRDFSyntax.RDFA_HTML;
    +    public static OfficialRDFSyntax RDFA_XHTML = OfficialRDFSyntax.RDFA_XHTML;
    +    public static OfficialRDFSyntax RDFXML = OfficialRDFSyntax.RDFXML;
    +    public static OfficialRDFSyntax TRIG = OfficialRDFSyntax.TRIG;
    +    
    +    /**
    +     * A short name of the RDF Syntax.
    +     * <p>
    +     * The name typically corresponds to the {@link Enum#name()} of for
    +     * {@link OfficialRDFSyntax}, e.g. <code>JSONLD</code>.
    +     * 
    +     * @return Short name for RDF syntax
    +     */
    +    public String name();
    +
    +    /**
    +     * The title of the RDF Syntax.
    +     * <p>
    +     * This is generally the title of the corresponding standard, 
    +     * e.g. <em>RDF 1.1 Turtle</em>.
    +     * 
    +     * @return Title of RDF Syntax
    +     */
    +    public String title();    
    +    
    +    /**
    +     * The <a href="https://tools.ietf.org/html/rfc2046">IANA media type</a> for
    +     * the RDF syntax.
    +     * <p>
    +     * The media type can be used as part of <code>Content-Type</code> and
    +     * <code>Accept</code> for <em>content negotiation</em> in the
    +     * <a href="https://tools.ietf.org/html/rfc7231#section-3.1.1.1">HTTP
    +     * protocol</a>.
    +     */
    +    public String mediaType();
    +
    +    /**
    +     * The <a href="https://tools.ietf.org/html/rfc2046">IANA-registered</a>
    +     * file extension.
    +     * <p>
    +     * The file extension includes the leading period, e.g. <code>.jsonld</code>
    +     */
    +    public String fileExtension();
    +
    +    /**
    +     * Indicate if this RDF syntax supports
    +     * <a href="https://www.w3.org/TR/rdf11-concepts/#section-dataset">RDF
    +     * Datasets</a>.
    +     */
    +    public boolean supportsDataset();
    +
    +
    --- End diff --
    
    Could also be useful to add a flag indicating whether the format is capable of persisting (even if not in all cases) namespace prefix definitions? In particular, RDF4J uses the supportsNamespaces flag along with the supportsDataset flag to prioritise formats and that may be useful for Commons RDF in the future also.


---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---

[GitHub] incubator-commonsrdf pull request #27: COMMONSRDF-47 RDFSyntax as an interfa...

Posted by ansell <gi...@git.apache.org>.
Github user ansell commented on a diff in the pull request:

    https://github.com/apache/incubator-commonsrdf/pull/27#discussion_r88564593
  
    --- Diff: api/src/main/java/org/apache/commons/rdf/api/RDFSyntax.java ---
    @@ -34,7 +152,7 @@
      *      1.1 Primer</a>
      * @see org.apache.commons.rdf.experimental.RDFParser
      */
    -public enum RDFSyntax {
    +  public enum OfficialRDFSyntax implements RDFSyntax {
    --- End diff --
    
    There is no particular reason that "enum" needs to be used given the interface design is done for flexibility, and given the difficulties with equals and hashCode. I would suggest reimplementing the "values()" method, along with equals and hashCode, and changing this to a "public final class".


---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---

[GitHub] incubator-commonsrdf pull request #27: COMMONSRDF-47 RDFSyntax as an interfa...

Posted by ansell <gi...@git.apache.org>.
Github user ansell commented on a diff in the pull request:

    https://github.com/apache/incubator-commonsrdf/pull/27#discussion_r88349748
  
    --- Diff: api/src/main/java/org/apache/commons/rdf/api/RDFSyntax.java ---
    @@ -34,7 +152,7 @@
      *      1.1 Primer</a>
      * @see org.apache.commons.rdf.experimental.RDFParser
      */
    -public enum RDFSyntax {
    +  public enum OfficialRDFSyntax implements RDFSyntax {
    --- End diff --
    
    This may be better named W3CRDFSyntax rather than Official which doesn't really have a technical meaning.


---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---

[GitHub] incubator-commonsrdf pull request #27: COMMONSRDF-47 RDFSyntax as an interfa...

Posted by ansell <gi...@git.apache.org>.
Github user ansell commented on a diff in the pull request:

    https://github.com/apache/incubator-commonsrdf/pull/27#discussion_r88565854
  
    --- Diff: api/src/main/java/org/apache/commons/rdf/api/RDFSyntax.java ---
    @@ -22,6 +22,124 @@
     import java.util.Optional;
     
     /**
    + * An RDF syntax, e.g. as used for parsing and writing RDF.
    + * <p>
    + * An RDF syntax is uniquely identified by its {@link #mediaType()}, and has a
    + * suggested {@link #fileExtension()}.
    + * <p>
    + * Some of the RDF syntaxes may {@link #supportsDataset()}, meaning they can
    + * represent {@link Quad}s.
    + * <p>
    + * An enumeration of the official RDF 1.1 syntaxes is available in 
    + * {@link OfficialRDFSyntax} - for convenience they are also accessible
    + * as constants here, e.g. <code>RDFSyntax.JSONLD</code>.
    + * 
    + */
    +public interface RDFSyntax {
    + 
    +    public static OfficialRDFSyntax JSONLD = OfficialRDFSyntax.JSONLD;
    +    public static OfficialRDFSyntax TURTLE = OfficialRDFSyntax.TURTLE;
    +    public static OfficialRDFSyntax NQUADS = OfficialRDFSyntax.NQUADS;
    +    public static OfficialRDFSyntax NTRIPLES = OfficialRDFSyntax.NTRIPLES;
    +    public static OfficialRDFSyntax RDFA_HTML = OfficialRDFSyntax.RDFA_HTML;
    +    public static OfficialRDFSyntax RDFA_XHTML = OfficialRDFSyntax.RDFA_XHTML;
    +    public static OfficialRDFSyntax RDFXML = OfficialRDFSyntax.RDFXML;
    +    public static OfficialRDFSyntax TRIG = OfficialRDFSyntax.TRIG;
    +    
    +    /**
    +     * A short name of the RDF Syntax.
    +     * <p>
    +     * The name typically corresponds to the {@link Enum#name()} of for
    +     * {@link OfficialRDFSyntax}, e.g. <code>JSONLD</code>.
    +     * 
    +     * @return Short name for RDF syntax
    +     */
    +    public String name();
    +
    +    /**
    +     * The title of the RDF Syntax.
    +     * <p>
    +     * This is generally the title of the corresponding standard, 
    +     * e.g. <em>RDF 1.1 Turtle</em>.
    +     * 
    +     * @return Title of RDF Syntax
    +     */
    +    public String title();    
    +    
    +    /**
    +     * The <a href="https://tools.ietf.org/html/rfc2046">IANA media type</a> for
    +     * the RDF syntax.
    +     * <p>
    +     * The media type can be used as part of <code>Content-Type</code> and
    +     * <code>Accept</code> for <em>content negotiation</em> in the
    +     * <a href="https://tools.ietf.org/html/rfc7231#section-3.1.1.1">HTTP
    +     * protocol</a>.
    +     */
    +    public String mediaType();
    +
    +    /**
    +     * The <a href="https://tools.ietf.org/html/rfc2046">IANA-registered</a>
    +     * file extension.
    +     * <p>
    +     * The file extension includes the leading period, e.g. <code>.jsonld</code>
    +     */
    +    public String fileExtension();
    +
    +    /**
    +     * Indicate if this RDF syntax supports
    +     * <a href="https://www.w3.org/TR/rdf11-concepts/#section-dataset">RDF
    +     * Datasets</a>.
    +     */
    +    public boolean supportsDataset();
    +
    +
    +    /**
    +     * Return the RDFSyntax with the specified media type.
    +     * <p>
    +     * The <code>mediaType</code> is compared in lower case, therefore it might
    +     * not be equal to the {@link RDFSyntax#mediaType} of the returned
    +     * RDFSyntax.
    +     * <p>
    +     * For convenience matching of media types used in a
    +     * <code>Content-Type</code> header, if the <code>mediaType</code> contains
    +     * the characters <code>;</code>, <code>,</code> or white space, only the
    +     * part of the string to the left of those characters are considered.
    +     * 
    +     * @param mediaType
    +     *            The media type to match
    +     * @return If {@link Optional#isPresent()}, the {@link RDFSyntax} which has
    +     *         a matching {@link RDFSyntax#mediaType}, otherwise
    +     *         {@link Optional#empty()} indicating that no matching syntax was
    +     *         found.
    +     */
    +    public static Optional<RDFSyntax> byMediaType(String mediaType) {
    +        final String type = mediaType.toLowerCase(Locale.ENGLISH).split("\\s*[;,]", 2)[0];
    --- End diff --
    
    Is this an official RFC/standards-based regex for splitting media-types?


---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---

[GitHub] incubator-commonsrdf pull request #27: COMMONSRDF-47 RDFSyntax as an interfa...

Posted by ansell <gi...@git.apache.org>.
Github user ansell commented on a diff in the pull request:

    https://github.com/apache/incubator-commonsrdf/pull/27#discussion_r88565369
  
    --- Diff: simple/src/main/java/org/apache/commons/rdf/simple/experimental/AbstractRDFParser.java ---
    @@ -240,7 +240,7 @@ public T rdfTermFactory(RDF rdfTermFactory) {
         public T contentType(RDFSyntax rdfSyntax) throws IllegalArgumentException {
             AbstractRDFParser<T> c = clone();
    --- End diff --
    
    Is it actually necessary to clone here? The typical builder pattern is much simpler with its reliance on always having "return this" as its last line, and using mutation before the "build()" terminal method to reduce this horrendous complexity related to cloning longterm mutable objects.


---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---

[GitHub] incubator-commonsrdf pull request #27: COMMONSRDF-47 RDFSyntax as an interfa...

Posted by ansell <gi...@git.apache.org>.
Github user ansell commented on a diff in the pull request:

    https://github.com/apache/incubator-commonsrdf/pull/27#discussion_r88350685
  
    --- Diff: api/src/main/java/org/apache/commons/rdf/api/RDFSyntax.java ---
    @@ -22,6 +22,124 @@
     import java.util.Optional;
     
     /**
    + * An RDF syntax, e.g. as used for parsing and writing RDF.
    + * <p>
    + * An RDF syntax is uniquely identified by its {@link #mediaType()}, and has a
    + * suggested {@link #fileExtension()}.
    + * <p>
    + * Some of the RDF syntaxes may {@link #supportsDataset()}, meaning they can
    + * represent {@link Quad}s.
    + * <p>
    + * An enumeration of the official RDF 1.1 syntaxes is available in 
    + * {@link OfficialRDFSyntax} - for convenience they are also accessible
    + * as constants here, e.g. <code>RDFSyntax.JSONLD</code>.
    + * 
    + */
    +public interface RDFSyntax {
    + 
    +    public static OfficialRDFSyntax JSONLD = OfficialRDFSyntax.JSONLD;
    +    public static OfficialRDFSyntax TURTLE = OfficialRDFSyntax.TURTLE;
    +    public static OfficialRDFSyntax NQUADS = OfficialRDFSyntax.NQUADS;
    +    public static OfficialRDFSyntax NTRIPLES = OfficialRDFSyntax.NTRIPLES;
    +    public static OfficialRDFSyntax RDFA_HTML = OfficialRDFSyntax.RDFA_HTML;
    +    public static OfficialRDFSyntax RDFA_XHTML = OfficialRDFSyntax.RDFA_XHTML;
    +    public static OfficialRDFSyntax RDFXML = OfficialRDFSyntax.RDFXML;
    +    public static OfficialRDFSyntax TRIG = OfficialRDFSyntax.TRIG;
    +    
    +    /**
    +     * A short name of the RDF Syntax.
    +     * <p>
    +     * The name typically corresponds to the {@link Enum#name()} of for
    +     * {@link OfficialRDFSyntax}, e.g. <code>JSONLD</code>.
    +     * 
    +     * @return Short name for RDF syntax
    +     */
    +    public String name();
    +
    +    /**
    +     * The title of the RDF Syntax.
    +     * <p>
    +     * This is generally the title of the corresponding standard, 
    +     * e.g. <em>RDF 1.1 Turtle</em>.
    +     * 
    +     * @return Title of RDF Syntax
    +     */
    +    public String title();    
    +    
    +    /**
    +     * The <a href="https://tools.ietf.org/html/rfc2046">IANA media type</a> for
    +     * the RDF syntax.
    +     * <p>
    +     * The media type can be used as part of <code>Content-Type</code> and
    +     * <code>Accept</code> for <em>content negotiation</em> in the
    +     * <a href="https://tools.ietf.org/html/rfc7231#section-3.1.1.1">HTTP
    +     * protocol</a>.
    +     */
    +    public String mediaType();
    --- End diff --
    
    Do you plan on supporting alternative media types here, to either support old media types or other commonly used media types?


---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---

[GitHub] incubator-commonsrdf pull request #27: COMMONSRDF-47 RDFSyntax as an interfa...

Posted by ansell <gi...@git.apache.org>.
Github user ansell commented on a diff in the pull request:

    https://github.com/apache/incubator-commonsrdf/pull/27#discussion_r88565106
  
    --- Diff: simple/src/main/java/org/apache/commons/rdf/simple/experimental/AbstractRDFParser.java ---
    @@ -240,7 +240,7 @@ public T rdfTermFactory(RDF rdfTermFactory) {
         public T contentType(RDFSyntax rdfSyntax) throws IllegalArgumentException {
             AbstractRDFParser<T> c = clone();
             c.contentTypeSyntax = Optional.ofNullable(rdfSyntax);
    -        c.contentType = c.contentTypeSyntax.map(syntax -> syntax.mediaType);
    +        c.contentType = c.contentTypeSyntax.map(syntax -> syntax.mediaType());
             return c.asT();
    --- End diff --
    
    It hurts my head thinking about this, but what is the signature for the generic type "T" designed to do. It seems like a circular definition, which doesn't really make sense but I can't think why T could have been introduced so I am stuck at seeing it as circular.
    
    ```
    AbstractRDFParser<T extends AbstractRDFParser<T>>
    ```


---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---

[GitHub] incubator-commonsrdf pull request #27: COMMONSRDF-47 RDFSyntax as an interfa...

Posted by ansell <gi...@git.apache.org>.
Github user ansell commented on a diff in the pull request:

    https://github.com/apache/incubator-commonsrdf/pull/27#discussion_r88350010
  
    --- Diff: api/src/main/java/org/apache/commons/rdf/api/RDFSyntax.java ---
    @@ -34,7 +152,7 @@
      *      1.1 Primer</a>
      * @see org.apache.commons.rdf.experimental.RDFParser
      */
    -public enum RDFSyntax {
    +  public enum OfficialRDFSyntax implements RDFSyntax {
    --- End diff --
    
    Also, relocating this to its own class would be ideal IMO for maintainability separate from the base interface.


---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---