Package com.apicatalog.rdf.canon

Class RdfCanon

  • All Implemented Interfaces:
    com.apicatalog.rdf.api.RdfQuadConsumer
    public final class RdfCanon
extends java.lang.Object
implements com.apicatalog.rdf.api.RdfQuadConsumer
    An implementation of the Standard RDF Dataset Canonicalization Algorithm as defined by the W3C.

    This class provides functionality to process and transform an RDF dataset into its canonical form, ensuring a stable and deterministic representation. Canonicalization is a key step in use cases such as digital signatures, data comparison, and RDF graph normalization.

    See Also:
    W3C Standard RDF Dataset Canonicalization Algorithm

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      private class  RdfCanon.HashNDegreeQuads
      The state information for the hash n-degree quads algorithm.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      private static java.lang.String BLANK_A  
      private static java.lang.String BLANK_Z  
      private java.util.Map<java.lang.String,​java.util.Collection<Quad>> blankIdToQuadSet
      Map of blank IDs to all the quads that reference that specific blank ID.
      private java.util.Map<java.lang.String,​Blank> blankNodes
      A map of blank node identifiers to their corresponding Blank nodes, used during RDF canonicalization for efficient relabeling of blank nodes.
      private IdentifierIssuer canonIssuer
      Issuer of canonical IDs to blank nodes.
      private java.security.MessageDigest digest
      An instance of a message digest algorithm (SHA-256, SHA-384, or custom).
      private java.util.Map<java.lang.String,​java.util.Set<java.lang.String>> hashToBlankId
      Hash to associated IRIs.
      private static char[] HEX
      The lower-case hexadecimal alphabet.
      private java.util.Set<java.lang.String> nonNormalized
      A set of non-normalized values.
      private java.util.Set<Quad> quads
      All the n-quads in the dataset to be processed.
      private RdfCanonTicker ticker
      Allows premature termination of the canonicalization process based on criteria defined by the associated RdfCanonTicker instance.

    • Constructor Summary

      Constructors 
      Constructor Description
      RdfCanon​(java.util.Map<java.lang.String,​java.util.Collection<Quad>> blankIdToQuadSet, java.util.Map<java.lang.String,​Blank> resources, java.security.MessageDigest digest, java.util.Set<Quad> nquads, RdfCanonTicker ticker)  

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      static RdfCanon create​(java.lang.String hashAlgorithm)
      Creates a new instance of RdfCanon using the specified hash algorithm.
      static RdfCanon create​(java.lang.String hashAlgorithm, RdfCanonTicker ticker)
      Creates a new instance of RdfCanon using the specified hash algorithm and RdfCanonTicker.
      static RdfCanon create​(java.security.MessageDigest digest)
      Creates a new instance of RdfCanon using the specified MessageDigest.
      static RdfCanon create​(java.security.MessageDigest digest, RdfCanonTicker ticker)
      Creates a new RdfCanon instance configured with the provided MessageDigest and RdfCanonTicker.
      (package private) java.lang.String forBlank​(Quad q0, java.lang.String blankNodeId)  
      (package private) java.lang.String hashFirstDegree​(java.lang.String blankNodeId)  
      (package private) NDegreeResult hashNDegreeQuads​(java.lang.String id, IdentifierIssuer issuer)  
      (package private) static java.lang.String hex​(byte[] data)
      Convert bytes to hexadecimal.
      (package private) void issueNDegreeIds()  
      (package private) void issueSimpleIds()  
      (package private) void makeCanonQuads​(com.apicatalog.rdf.api.RdfQuadConsumer consumer)  
      java.util.Map<java.lang.String,​java.lang.String> mapping()  
      (package private) static RdfCanon newInstance​(java.util.Set<Quad> nquads, java.security.MessageDigest digest, RdfCanonTicker ticker)  
      void provide​(com.apicatalog.rdf.api.RdfQuadConsumer consumer)
      Emits canonical RDF quads to the given consumer.
      com.apicatalog.rdf.api.RdfQuadConsumer quad​(java.lang.String subject, java.lang.String predicate, java.lang.String object, java.lang.String datatype, java.lang.String language, java.lang.String direction, java.lang.String graph)  
      (package private) void setNonNormalized()  
      (package private) void setResource​(Position position, Quad quad, java.lang.String name)  

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Field Detail

      • HEX

        private static final char[] HEX
        The lower-case hexadecimal alphabet.

      • blankIdToQuadSet

        private final java.util.Map<java.lang.String,​java.util.Collection<Quad>> blankIdToQuadSet
        Map of blank IDs to all the quads that reference that specific blank ID.

      • blankNodes

        private final java.util.Map<java.lang.String,​Blank> blankNodes
        A map of blank node identifiers to their corresponding Blank nodes, used during RDF canonicalization for efficient relabeling of blank nodes.

      • canonIssuer

        private final IdentifierIssuer canonIssuer
        Issuer of canonical IDs to blank nodes.

      • ticker

        private final RdfCanonTicker ticker
        Allows premature termination of the canonicalization process based on criteria defined by the associated RdfCanonTicker instance.

        The ticker can be used to monitor progress or enforce timeouts, limits, or custom stopping conditions during RDF dataset canonicalization.

      • hashToBlankId

        private final java.util.Map<java.lang.String,​java.util.Set<java.lang.String>> hashToBlankId
        Hash to associated IRIs.

      • quads

        private final java.util.Set<Quad> quads
        All the n-quads in the dataset to be processed.

      • digest

        private final java.security.MessageDigest digest
        An instance of a message digest algorithm (SHA-256, SHA-384, or custom).

      • nonNormalized

        private java.util.Set<java.lang.String> nonNormalized
        A set of non-normalized values.

    • Constructor Detail

      • RdfCanon

        RdfCanon​(java.util.Map<java.lang.String,​java.util.Collection<Quad>> blankIdToQuadSet,
         java.util.Map<java.lang.String,​Blank> resources,
         java.security.MessageDigest digest,
         java.util.Set<Quad> nquads,
         RdfCanonTicker ticker)

    • Method Detail

      • create

        public static RdfCanon create​(java.lang.String hashAlgorithm)
        Creates a new instance of RdfCanon using the specified hash algorithm.

        The provided algorithm determines the cryptographic hash function used for RDF canonicalization. Supported algorithms are:

        • SHA-256
        • SHA-384
        Parameters:
        hashAlgorithm - the name of the hash algorithm to use; must be either "SHA-256" or "SHA-384". Must not be null.
        Returns:
        a new RdfCanon instance configured with the specified hash algorithm.
        Throws:
        java.lang.IllegalArgumentException - if hashAlgorithm is not supported or null.

      • create

        public static RdfCanon create​(java.lang.String hashAlgorithm,
                              RdfCanonTicker ticker)
        Creates a new instance of RdfCanon using the specified hash algorithm and RdfCanonTicker.

        The provided algorithm determines the cryptographic hash function used for RDF canonicalization. Supported algorithms are:

        • SHA-256
        • SHA-384

        A RdfCanonTicker must also be provided to monitor the progress of the canonicalization process or enforce custom stopping conditions. The ticker's RdfCanonTicker.tick() method will be invoked periodically during canonicalization. If tick() throws an IllegalStateException, the process will be aborted.

        Parameters:
        hashAlgorithm - the name of the hash algorithm to use; must be either "SHA-256" or "SHA-384". Must not be null.
        ticker - a non-null RdfCanonTicker used to monitor or control the canonicalization process.
        Returns:
        a new RdfCanon instance configured with the specified hash algorithm and ticker.
        Throws:
        java.lang.IllegalArgumentException - if hashAlgorithm is not supported or null.
        java.lang.NullPointerException - if ticker is null.

      • create

        public static RdfCanon create​(java.security.MessageDigest digest)
        Creates a new instance of RdfCanon using the specified MessageDigest.

        This factory method allows the caller to provide a pre-configured MessageDigest instance, offering greater flexibility and control over the hashing behavior used during RDF canonicalization.

        The supplied digest instance will be used internally to compute hashes, and it should be properly initialized.

        Parameters:
        digest - a pre-configured MessageDigest instance; must not be null.
        Returns:
        a new RdfCanon instance that uses the specified digest.
        Throws:
        java.lang.NullPointerException - if digest is null.

      • create

        public static RdfCanon create​(java.security.MessageDigest digest,
                              RdfCanonTicker ticker)
        Creates a new RdfCanon instance configured with the provided MessageDigest and RdfCanonTicker.

        This factory method gives callers fine-grained control over the hashing algorithm and behavior used during RDF dataset canonicalization by accepting a pre-configured MessageDigest instance.

        The supplied digest will be used internally to compute hashes for canonicalizing RDF datasets. It must be properly initialized and ready for use.

        A RdfCanonTicker must also be provided to monitor the progress of canonicalization or enforce custom stopping conditions, such as timeouts, iteration limits, or external cancellation signals. The ticker’s RdfCanonTicker.tick() method will be invoked periodically during the canonicalization process. If it throws an IllegalStateException, processing will be interrupted.

        Parameters:
        digest - a pre-configured, non-null MessageDigest instance used for computing hashes.
        ticker - a non-null RdfCanonTicker that controls or monitors the canonicalization process.
        Returns:
        a new RdfCanon instance configured with the specified digest and ticker.
        Throws:
        java.lang.NullPointerException - if digest or ticker is null.

      • provide

        public void provide​(com.apicatalog.rdf.api.RdfQuadConsumer consumer)
             throws com.apicatalog.rdf.api.RdfConsumerException
        Emits canonical RDF quads to the given consumer. This method generates RDF quads in a canonical form and supplies them to the provided RdfQuadConsumer.
        Parameters:
        consumer - the RdfQuadConsumer that will receive the canonical RDF quads
        Throws:
        com.apicatalog.rdf.api.RdfConsumerException - if an error occurs while processing or consuming RDF quads
        java.lang.IllegalStateException - if the computation is terminated prematurely

      • mapping

        public java.util.Map<java.lang.String,​java.lang.String> mapping()

      • quad

        public com.apicatalog.rdf.api.RdfQuadConsumer quad​(java.lang.String subject,
                                                   java.lang.String predicate,
                                                   java.lang.String object,
                                                   java.lang.String datatype,
                                                   java.lang.String language,
                                                   java.lang.String direction,
                                                   java.lang.String graph)
        Specified by:
        quad in interface com.apicatalog.rdf.api.RdfQuadConsumer

      • newInstance

        static RdfCanon newInstance​(java.util.Set<Quad> nquads,
                            java.security.MessageDigest digest,
                            RdfCanonTicker ticker)

      • forBlank

        java.lang.String forBlank​(Quad q0,
                          java.lang.String blankNodeId)

      • setNonNormalized

        void setNonNormalized()

      • hashFirstDegree

        java.lang.String hashFirstDegree​(java.lang.String blankNodeId)

      • issueSimpleIds

        void issueSimpleIds()

      • issueNDegreeIds

        void issueNDegreeIds()

      • makeCanonQuads

        void makeCanonQuads​(com.apicatalog.rdf.api.RdfQuadConsumer consumer)
             throws com.apicatalog.rdf.api.RdfConsumerException
        Throws:
        com.apicatalog.rdf.api.RdfConsumerException

      • hex

        static java.lang.String hex​(byte[] data)
        Convert bytes to hexadecimal.
        Parameters:
        data - the bytes
        Returns:
        the data represented in hexadecimal.

      • setResource

        void setResource​(Position position,
                 Quad quad,
                 java.lang.String name)