Package com.complexible.stardog.virtual.api

Class DriverFiles

java.lang.Object
com.complexible.stardog.virtual.api.DriverFiles
public final class DriverFiles extends Object
Parsing and validation of the driver.file. data source options.

Some JDBC drivers — the CData drivers in particular — take configuration through properties whose value is a path on the machine running the driver rather than the configuration itself. The CData REST driver's Location (a directory of .rsd schema files) and OAuthJWTCert (a certificate file) are typical. Passing those through as ext.-prefixed options requires the client to have filesystem access to the Stardog server, which a client of a hosted Stardog does not have, and makes the data source definition node-local rather than something that replicates with the rest of the registry.

The driver.file. options let a client supply the contents instead. Stardog writes them into a directory of its own and sets the driver property to the path of what it wrote there, a file or a directory depending on the form the option takes, so the definition stays portable: 

 # a single file: the driver property is set to the path of a file holding this content
 driver.file.OAuthJWTCert          = -----BEGIN PRIVATE KEY----- ...

 # a directory: the part after '/' is the entry's path within the materialized directory, and the
 # driver property is set to the path of the directory itself
 driver.file.Location/people.rsd   = <rsd content>
 driver.file.Location/cars.rsd     = <rsd content>

 # binary content, base64-encoded
 driver.file.base64.SSLClientCert  = MIIKuAIBAzCCCnQGCS ...
A driver.file. option takes precedence over the ext. option for the same driver property, which continues to work for deployments where server-side paths are available.
See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static final record 
    DriverFiles.Entry
    One file supplied by the client, destined for a single driver property.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final String
    BASE64_MARKER
    Marker following PREFIX indicating the value is base64-encoded rather than UTF-8 text.
    static final char
    ENTRY_SEPARATOR
    Separates the driver property name from an entry's path within a directory-valued property.
    static final Set<String>
    LOCAL_OR_REMOTE_PROPERTIES
    Driver properties that take a local target as readily as a remote one, so that neither the name nor the shape of the value alone says whether the driver will go to the network or to the disk.
    static final int
    MAX_TOTAL_BYTES
    Cap on the total decoded content one data source may supply.
    static final Set<String>
    NESTED_PROPERTIES
    Driver properties whose value is itself a list of driver properties, so that setting one is a way to set any of the others without naming them where rejectServerPaths(java.util.Map<?, ?>) would look.
    static final Set<String>
    PATH_VALUED_PROPERTIES
    Driver properties whose value is a path to a file or directory on the machine running the driver, and which therefore have to be supplied as content when the server's filesystem is not available to the client.
    static final String
    PREFIX
    Prefix identifying an option whose value is the content of a file the driver expects a path to.
    static final Set<String>
    WRITE_TARGET_PROPERTIES
    Driver properties naming a file the driver writes, rather than one it reads.

  • Method Summary

    Modifier and Type
    Method
    Description
    static String
    contentHash(String dataSourceName, SortedMap<String,List<DriverFiles.Entry>> files)
    A hash of a data source's parsed content, stable across servers and restarts, used to name the directory the content is materialized into.
    static boolean
    hasDriverFiles(Map<?,?> dsOptions)
    Whether any of the supplied data source options is a driver.file. option.
    static boolean
    isDirectory(List<DriverFiles.Entry> entries)
    Whether the property was supplied as a directory of entries rather than as a single file.
    static boolean
    isDriverFileKey(Object key)
    Whether the option is a driver.file. option.
    static SortedMap<String,List<DriverFiles.Entry>>
    parse(Map<?,?> dsOptions)
    Parses the driver.file. options into the files to materialize, grouped by driver property.
    static void
    rejectServerPaths(Map<?,?> dsOptions)
    Rejects the data source options that would have a JDBC driver read from or write to the Stardog server's filesystem, for deployments where that filesystem is not the client's.

    Methods inherited from class java.lang.Object

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

  • Field Details

    • PREFIX

      public static final String PREFIX
      Prefix identifying an option whose value is the content of a file the driver expects a path to.
      See Also:

    • BASE64_MARKER

      public static final String BASE64_MARKER
      Marker following PREFIX indicating the value is base64-encoded rather than UTF-8 text. No driver property may be named base64.<something>; the token is reserved.
      See Also:

    • ENTRY_SEPARATOR

      public static final char ENTRY_SEPARATOR
      Separates the driver property name from an entry's path within a directory-valued property.
      See Also:

    • MAX_TOTAL_BYTES

      public static final int MAX_TOTAL_BYTES
      Cap on the total decoded content one data source may supply. The content is stored — encrypted — as a single literal in the system database and replicated to every node in the cluster, so it is not a place for bulk data.
      See Also:

    • PATH_VALUED_PROPERTIES

      public static final Set<String> PATH_VALUED_PROPERTIES
      Driver properties whose value is a path to a file or directory on the machine running the driver, and which therefore have to be supplied as content when the server's filesystem is not available to the client.

      Compiled from the connection properties of the CData drivers Stardog bundles, which share property names, plus the file-valued properties of the other drivers Stardog is commonly configured with. Matched ignoring case, as the drivers themselves treat property names. Best effort: a driver property not listed here is not restricted, so keep this in step with the drivers as they add properties.

    • WRITE_TARGET_PROPERTIES

      public static final Set<String> WRITE_TARGET_PROPERTIES
      Driver properties naming a file the driver writes, rather than one it reads.

      Refused outright while server file paths are disabled, in every form, because none of them has an answer here. A path on the server is what the policy exists to prevent. And supplying the contents, which is what the other path-valued properties are told to do, makes no sense for a file whose contents the driver produces: the driver would write its log into the materialized directory, where nothing reads it, nothing bounds its size, and whatever the driver's verbosity puts in it, connection strings and tokens among it, stays until the data source is removed.

    • NESTED_PROPERTIES

      public static final Set<String> NESTED_PROPERTIES
      Driver properties whose value is itself a list of driver properties, so that setting one is a way to set any of the others without naming them where rejectServerPaths(java.util.Map<?, ?>) would look.

      The CData drivers' Other is the one Stardog is used with: the driver documents it as "additional hidden properties for specific use cases", and Other=RecordToFile=/var/opt/stardog/x writes the socket trace to a file of the client's choosing. Rejected outright rather than picked apart, which would mean parsing the driver's own escaping, and no deployment that has just declared the server filesystem off limits has a use for it.

    • LOCAL_OR_REMOTE_PROPERTIES

      public static final Set<String> LOCAL_OR_REMOTE_PROPERTIES
      Driver properties that take a local target as readily as a remote one, so that neither the name nor the shape of the value alone says whether the driver will go to the network or to the disk.

      The CData REST driver's URI is the one Stardog is used with: it reads /etc/shadow off the disk as readily as it fetches an http:// URL, and it does so while generating the mappings, before any query is run. It cannot go in PATH_VALUED_PROPERTIES, which would forbid the remote use it is normally put to, so its value is what gets looked at.

  • Method Details

    • rejectServerPaths

      public static void rejectServerPaths(Map<?,?> dsOptions)
      Rejects the data source options that would have a JDBC driver read from or write to the Stardog server's filesystem, for deployments where that filesystem is not the client's. What those options configured has to be supplied as content, with the corresponding PREFIX option, instead.

      A driver property reaches the driver three ways, and all three are checked: an ext. option, a passthrough. option, which OAuthPassthroughDataSource hands to the driver with the prefix stripped, and the JDBC URL, which for the CData drivers carries the same properties inline — jdbc:rest:Location=/srv/schemas;Format=JSON sets the property ext.Location would.

      Two rules, because neither covers the other. A property in PATH_VALUED_PROPERTIES may not be set at all, whatever its value. And no value reaching the driver may be a file: URL, whichever property carries it: a property that usually names something remote often takes a local file just as happily, as the CData REST driver's URI does, so it cannot be listed but must not be pointed at the server.

      Best effort, like PATH_VALUED_PROPERTIES itself. In particular a JDBC URL that takes a path positionally rather than as a named property, as jdbc:h2:/var/data/db does, is not recognized here; restricting that means restricting which drivers a deployment offers at all.

      Throws:
      StardogException - if an option configures the driver with a path on this server

    • isDriverFileKey

      public static boolean isDriverFileKey(Object key)
      Whether the option is a driver.file. option. Such options are consumed by DriverFileStore and never reach the driver.

    • hasDriverFiles

      public static boolean hasDriverFiles(Map<?,?> dsOptions)
      Whether any of the supplied data source options is a driver.file. option.

    • parse

      public static SortedMap<String,List<DriverFiles.Entry>> parse(Map<?,?> dsOptions)
      Parses the driver.file. options into the files to materialize, grouped by driver property. Properties and the entries within each are ordered by name so that the result is a canonical representation of the content, suitable for contentHash(java.lang.String, java.util.SortedMap<java.lang.String, java.util.List<com.complexible.stardog.virtual.api.DriverFiles.Entry>>).
      Throws:
      StardogException - if an option is malformed, if a property mixes the single-file and directory forms, or if the total content exceeds MAX_TOTAL_BYTES

    • isDirectory

      public static boolean isDirectory(List<DriverFiles.Entry> entries)
      Whether the property was supplied as a directory of entries rather than as a single file. Only valid for a list that has been through validateProperty(java.lang.String, java.util.List<com.complexible.stardog.virtual.api.DriverFiles.Entry>).

    • contentHash

      public static String contentHash(String dataSourceName, SortedMap<String,List<DriverFiles.Entry>> files)
      A hash of a data source's parsed content, stable across servers and restarts, used to name the directory the content is materialized into. Changing any property, path or byte changes the hash and so the directory, which keeps an updated data source from disturbing the files a previous version is still using.

      The data source name is part of the hash so that a directory belongs to exactly one data source, even when two names are indistinguishable once reduced to something a directory can be named after. That is what lets the files be removed along with the data source that supplied them.