org.eclipse.rdf4j.sail.shacl

## Class ShaclSail

- java.lang.Object
- - org.eclipse.rdf4j.sail.helpers.SailWrapper
  - - org.eclipse.rdf4j.sail.helpers.NotifyingSailWrapper
    - - org.eclipse.rdf4j.sail.shacl.ShaclSail

- All Implemented Interfaces:
    FederatedServiceResolverClient, NotifyingSail, Sail, StackableSail

      public class ShaclSail
      extends NotifyingSailWrapper

  A `Sail` implementation that adds support for the Shapes Constraint Language (SHACL).

  The ShaclSail looks for SHACL shape data in a special named graph `RDF4J.SHACL_SHAPE_GRAPH`.

  #### Working example

       import ch.qos.logback.classic.Level;
       import ch.qos.logback.classic.Logger;
       import org.eclipse.rdf4j.model.Model;
       import org.eclipse.rdf4j.model.vocabulary.RDF4J;
       import org.eclipse.rdf4j.repository.RepositoryException;
       import org.eclipse.rdf4j.repository.sail.SailRepository;
       import org.eclipse.rdf4j.repository.sail.SailRepositoryConnection;
       import org.eclipse.rdf4j.rio.RDFFormat;
       import org.eclipse.rdf4j.rio.Rio;
       import org.eclipse.rdf4j.sail.memory.MemoryStore;
       import org.eclipse.rdf4j.sail.shacl.ShaclSail;
       import org.eclipse.rdf4j.sail.shacl.ShaclSailValidationException;
       import org.eclipse.rdf4j.sail.shacl.results.ValidationReport;
       import org.slf4j.LoggerFactory;

       import java.io.IOException;
       import java.io.StringReader;

       public class ShaclSampleCode {

              public static void main(String[] args) throws IOException {

                      ShaclSail shaclSail = new ShaclSail(new MemoryStore());

                      // Logger root = (Logger) LoggerFactory.getLogger(ShaclSail.class.getName());
                      // root.setLevel(Level.INFO);

                      // shaclSail.setLogValidationPlans(true);
                      // shaclSail.setGlobalLogValidationExecution(true);
                      // shaclSail.setLogValidationViolations(true);

                      SailRepository sailRepository = new SailRepository(shaclSail);
                      sailRepository.init();

                      try (SailRepositoryConnection connection = sailRepository.getConnection()) {

                              connection.begin();

                              StringReader shaclRules = new StringReader(String.join("\n", "",
                                              "@prefix ex: <http://example.com/ns#> .", "@prefix sh: <http://www.w3.org/ns/shacl#> .",
                                              "@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .",
                                              "@prefix foaf: <http://xmlns.com/foaf/0.1/>.",

                                              "ex:PersonShape", "      a sh:NodeShape  ;", " sh:targetClass foaf:Person ;",
                                              "  sh:property ex:PersonShapeProperty .",

                                              "ex:PersonShapeProperty ", "     sh:path foaf:age ;", "        sh:datatype xsd:int ;",
                                              "  sh:maxCount 1 ;", "   sh:minCount 1 ."));

                              connection.add(shaclRules, "", RDFFormat.TURTLE, RDF4J.SHACL_SHAPE_GRAPH);
                              connection.commit();

                              connection.begin();

                              StringReader invalidSampleData = new StringReader(String.join("\n", "",
                                              "@prefix ex: <http://example.com/ns#> .", "@prefix foaf: <http://xmlns.com/foaf/0.1/>.",
                                              "@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .",

                                              "ex:peter a foaf:Person ;", "    foaf:age 20, \"30\"^^xsd:int  ."

                              ));

                              connection.add(invalidSampleData, "", RDFFormat.TURTLE);
                              try {
                                      connection.commit();
                              } catch (RepositoryException exception) {
                                      Throwable cause = exception.getCause();
                                      if (cause instanceof ShaclSailValidationException) {
                                              ValidationReport validationReport = ((ShaclSailValidationException) cause).getValidationReport();
                                              Model validationReportModel = ((ShaclSailValidationException) cause).validationReportAsModel();
                                              // use validationReport or validationReportModel to understand validation violations

                                              Rio.write(validationReportModel, System.out, RDFFormat.TURTLE);
                                      }
                                      throw exception;
                              }
                      }
              }
       }

  Author:
    Heshan Jayasinghe, Håvard Ottestad
  See Also:
    SHACL W3C Recommendation

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `ShaclSail()`
    `ShaclSail(NotifyingSail baseSail)`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `disableValidation()` Disable the SHACL validation on commit()
    `void` | `enableValidation()` Enabled the SHACL validation on commit()
    `NotifyingSailConnection` | `getConnection()` Opens a connection on the Sail which can be used to query and update data.
    `static List<IRI>` | `getSupportedShaclPredicates()` Lists the predicates that have been implemented in the ShaclSail.
    `void` | `initialize()` Initializes the Sail.
    `boolean` | `isCacheSelectNodes()` Check if selected nodes caches is enabled.
    `boolean` | `isGlobalLogValidationExecution()` Check if logging of every execution steps is enabled.
    `boolean` | `isIgnoreNoShapesLoadedException()`
    `boolean` | `isLogValidationPlans()` Check if logging of validation plans is enabled.
    `boolean` | `isLogValidationViolations()` Check if logging a list of violations and the triples that caused the violations is enabled.
    `boolean` | `isParallelValidation()` Check if SHACL validation is run in parellel.
    `boolean` | `isRdfsSubClassReasoning()`
    `boolean` | `isUndefinedTargetValidatesAllSubjects()` Check if `NodeShape`s without a defined target are considered wildcards.
    `boolean` | `isValidationEnabled()` Check if SHACL validation on commit() is enabled.
    `void` | `setCacheSelectNodes(boolean cacheSelectNodes)` The ShaclSail retries a lot of its relevant data through running SPARQL Select queries against the underlying sail and against the changes in the transaction.
    `void` | `setGlobalLogValidationExecution(boolean loggingEnabled)` Log (INFO) every execution step of the SHACL validation.
    `void` | `setIgnoreNoShapesLoadedException(boolean ignoreNoShapesLoadedException)` Check if shapes have been loaded into the shapes graph before other data is added
    `void` | `setLogValidationPlans(boolean logValidationPlans)` Log (INFO) the executed validation plans as GraphViz DOT Recommended to disable parallel validation with setParallelValidation(false)
    `void` | `setLogValidationViolations(boolean logValidationViolations)` Log (INFO) a list of violations and the triples that caused the violations (BETA).
    `void` | `setParallelValidation(boolean parallelValidation)` EXPERIMENTAL! Run SHACL validation in parallel.
    `void` | `setRdfsSubClassReasoning(boolean rdfsSubClassReasoning)`
    `void` | `setUndefinedTargetValidatesAllSubjects(boolean undefinedTargetValidatesAllSubjects)` If no target is defined for a NodeShape, that NodeShape will be ignored.
    `void` | `shutDown()` Shuts down the Sail, giving it the opportunity to synchronize any stale data.

    - ### Methods inherited from class org.eclipse.rdf4j.sail.helpers.NotifyingSailWrapper

      `addSailChangedListener, getBaseSail, removeSailChangedListener, setBaseSail`

    - ### Methods inherited from class org.eclipse.rdf4j.sail.helpers.SailWrapper

      `getDataDir, getDefaultIsolationLevel, getSupportedIsolationLevels, getValueFactory, isWritable, setDataDir, setFederatedServiceResolver, verifyBaseSailSet`

    - ### Methods inherited from class java.lang.Object

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

    - ### Methods inherited from interface org.eclipse.rdf4j.sail.Sail

      `getDataDir, getDefaultIsolationLevel, getSupportedIsolationLevels, getValueFactory, init, isWritable, setDataDir`

- - ### Constructor Detail

    - #### ShaclSail

          public ShaclSail(NotifyingSail baseSail)

    - #### ShaclSail

          public ShaclSail()

  - ### Method Detail

    - #### getSupportedShaclPredicates

          public static List<IRI> getSupportedShaclPredicates()

      Lists the predicates that have been implemented in the ShaclSail. All of these, and all combinations, should work, please report any bugs. For sh:path, only single predicate paths are supported.
      Returns:
        List of IRIs (SHACL predicates)

    - #### initialize

          public void initialize()
                          throws SailException

      Description copied from interface: `Sail`
      Initializes the Sail. Care should be taken that required initialization parameters have been set before this method is called. Please consult the specific Sail implementation for information about the relevant parameters.
      Specified by:
        `initialize` in interface `Sail`
      Overrides:
        `initialize` in class `SailWrapper`
      Throws:
        `SailException` - If the Sail could not be initialized.

    - #### shutDown

          public void shutDown()
                        throws SailException

      Description copied from interface: `Sail`
      Shuts down the Sail, giving it the opportunity to synchronize any stale data. Care should be taken that all initialized Sails are being shut down before an application exits to avoid potential loss of data. Once shut down, a Sail can no longer be used until it is re-initialized.
      Specified by:
        `shutDown` in interface `Sail`
      Overrides:
        `shutDown` in class `SailWrapper`
      Throws:
        `SailException` - If the Sail object encountered an error or unexpected situation internally.

    - #### getConnection

          public NotifyingSailConnection getConnection()
                                                throws SailException

      Description copied from interface: `Sail`
      Opens a connection on the Sail which can be used to query and update data. Depending on how the implementation handles concurrent access, a call to this method might block when there is another open connection on this Sail.
      Specified by:
        `getConnection` in interface `NotifyingSail`
      Specified by:
        `getConnection` in interface `Sail`
      Overrides:
        `getConnection` in class `NotifyingSailWrapper`
      Throws:
        `SailException` - If no transaction could be started, for example because the Sail is not writable.

    - #### disableValidation

          public void disableValidation()

      Disable the SHACL validation on commit()

    - #### enableValidation

          public void enableValidation()

      Enabled the SHACL validation on commit()

    - #### isValidationEnabled

          public boolean isValidationEnabled()

      Check if SHACL validation on commit() is enabled.
      Returns:
        `true` if validation is enabled, `false` otherwise.

    - #### isLogValidationPlans

          public boolean isLogValidationPlans()

      Check if logging of validation plans is enabled.
      Returns:
        `true` if validation plan logging is enabled, `false` otherwise.

    - #### isIgnoreNoShapesLoadedException

          public boolean isIgnoreNoShapesLoadedException()

    - #### setIgnoreNoShapesLoadedException

          public void setIgnoreNoShapesLoadedException(boolean ignoreNoShapesLoadedException)

      Check if shapes have been loaded into the shapes graph before other data is added
      Parameters:
        `ignoreNoShapesLoadedException` -

    - #### setLogValidationPlans

          public void setLogValidationPlans(boolean logValidationPlans)

      Log (INFO) the executed validation plans as GraphViz DOT Recommended to disable parallel validation with setParallelValidation(false)
      Parameters:
        `logValidationPlans` -

    - #### setGlobalLogValidationExecution

          public void setGlobalLogValidationExecution(boolean loggingEnabled)

      Log (INFO) every execution step of the SHACL validation. This is fairly costly and should not be used in production. Recommended to disable parallel validation with setParallelValidation(false)
      Parameters:
        `loggingEnabled` -

    - #### isGlobalLogValidationExecution

          public boolean isGlobalLogValidationExecution()

      Check if logging of every execution steps is enabled.
      Returns:
        `true` if enabled, `false` otherwise.
      See Also:
        `setGlobalLogValidationExecution(boolean)`

    - #### isLogValidationViolations

          public boolean isLogValidationViolations()

      Check if logging a list of violations and the triples that caused the violations is enabled. It is recommended to disable parallel validation with `setParallelValidation(boolean)`
      See Also:
        `setLogValidationViolations(boolean)`

    - #### setLogValidationViolations

          public void setLogValidationViolations(boolean logValidationViolations)

      Log (INFO) a list of violations and the triples that caused the violations (BETA). Recommended to disable parallel validation with setParallelValidation(false)
      Parameters:
        `logValidationViolations` -

    - #### setUndefinedTargetValidatesAllSubjects

          public void setUndefinedTargetValidatesAllSubjects(boolean undefinedTargetValidatesAllSubjects)

      If no target is defined for a NodeShape, that NodeShape will be ignored. Calling this method with "true" will make such NodeShapes wildcard shapes and validate all subjects. Equivalent to setting sh:targetClass to owl:Thing or rdfs:Resource in an environment with a reasoner.
      Parameters:
        `undefinedTargetValidatesAllSubjects` - default false

    - #### isUndefinedTargetValidatesAllSubjects

          public boolean isUndefinedTargetValidatesAllSubjects()

      Check if `NodeShape`s without a defined target are considered wildcards.
      Returns:
        `true` if enabled, `false` otherwise
      See Also:
        `setUndefinedTargetValidatesAllSubjects(boolean)`

    - #### isParallelValidation

          public boolean isParallelValidation()

      Check if SHACL validation is run in parellel.
      Returns:
        `true` if enabled, `false` otherwise.

    - #### setParallelValidation

          public void setParallelValidation(boolean parallelValidation)

      EXPERIMENTAL! Run SHACL validation in parallel. Default: false

      May cause deadlock, especially when using NativeStore.

      Parameters:
        `parallelValidation` - default false

    - #### isCacheSelectNodes

          public boolean isCacheSelectNodes()

      Check if selected nodes caches is enabled.
      Returns:
        `true` if enabled, `false` otherwise.
      See Also:
        `setCacheSelectNodes(boolean)`

    - #### setCacheSelectNodes

          public void setCacheSelectNodes(boolean cacheSelectNodes)

      The ShaclSail retries a lot of its relevant data through running SPARQL Select queries against the underlying sail and against the changes in the transaction. This is usually good for performance, but while validating large amounts of data disabling this cache will use less memory. Default: true
      Parameters:
        `cacheSelectNodes` - default true

    - #### isRdfsSubClassReasoning

          public boolean isRdfsSubClassReasoning()

    - #### setRdfsSubClassReasoning

          public void setRdfsSubClassReasoning(boolean rdfsSubClassReasoning)

Copyright © 2015-2020 Eclipse Foundation. All Rights Reserved.