Package com.complexible.stardog.virtual.api.admin

Interface VirtualGraphAdminConnection

  • All Superinterfaces:
    AdminConnection, java.lang.AutoCloseable
    public interface VirtualGraphAdminConnection
extends AdminConnection
    Connection to manage data sources and virtual graphs

    • Method Summary

      All Methods Instance Methods Abstract Methods Default Methods Deprecated Methods 
      Modifier and Type Method Description
      void addDataSource​(java.lang.String theName, java.util.Properties theOptions)
      Add a data source with the given properties
      void addGraph​(java.lang.String theName, java.lang.String theDataSource, java.lang.String theDatabase, java.util.Properties theOptions, java.lang.Iterable<Statement> theMappings)
      Registers a new virtual graph against a named data source
      default void addGraph​(java.lang.String theName, java.lang.String theDataSource, java.lang.String theDatabase, java.util.Properties theOptions, java.lang.String theMappings)
      Registers a new virtual graph using a data source.
      void addGraph​(java.lang.String theName, java.lang.String theDatabase, java.util.Properties theOptions, java.lang.Iterable<Statement> theMappings)
      Registers a new virtual graph.
      void addGraph​(java.lang.String theName, java.lang.String theDatabase, java.util.Properties theOptions, java.lang.String theMappings)
      Deprecated.
      Use addGraph(String, String, String, Properties, String) with null dataSource
      void addGraph​(java.lang.String theName, java.lang.String theDataSourceName, java.util.Set<Statement> theMetadata, java.lang.String theDatabase, java.util.Properties theOptions, java.lang.String theMappings)
      Deprecated.
      For Stardog internal use only
      default void addGraph​(java.lang.String theName, java.util.Properties theOptions, java.lang.Iterable<Statement> theMappings)
      Registers a new virtual graph to be associated with all databases.
      default void addGraph​(java.lang.String theName, java.util.Properties theOptions, java.lang.String theMappings)
      Registers a new virtual graph for access from all databases
      void applyMetadataDiff​(java.lang.String theDataSourceName, java.util.Set<Statement> theAdded, java.util.Set<Statement> theRemoved, int theCrc, java.util.Map<java.lang.String,​java.lang.Boolean> theVgAvailability)
      Deprecated.
      For Stardog internal use only
      DataSourceInfo getDataSourceInfo​(java.lang.String theName)
      Retrieve the data source details for the named data source
      default DataSourceInfo getDataSourceInfoOrNull​(java.lang.String theName)
      Retrieve the data source details for the named data source or null if it doesn't exist
      java.util.Collection<DataSourceInfo> getDataSourceInfos()
      Returns information on all registered data sources.
      java.util.Set<Statement> getDataSourceMetadata​(java.lang.String theName)
      Retrieve all the metadata that a DataSource has cached for its connection.
      java.util.Properties getDataSourceOptions​(java.lang.String theName)
      Get the data source options
      com.google.gson.JsonArray getDataSourceTables​(java.lang.String dsName)
      Retrieve all the tables that a DataSource has access to.
      java.lang.String getDbTypeOptionsDescription()
      Describes options for configuring data sources and virtual graphs.
      VirtualGraph getGraph​(java.lang.String theName)
      Deprecated.
      Use getVirtualGraphInfo or the other methods
      default java.lang.String getMappings​(java.lang.String vgName)
      Get mappings for the named virtual graph in R2RML format
      java.lang.String getMappingsString​(java.lang.String theName, java.lang.String theSyntax)
      Get the serialized mappings
      java.util.Set<Statement> getMatchingSuggestions​(java.util.Set<Statement> theInput)
      Aligns data source and targets based on their lexical, data type, word sense similarity and returns those alignments as statements
      java.util.Properties getOptions​(java.lang.String theName)
      Get the virtual graph options
      com.google.gson.JsonObject getTableMetadataJson​(java.lang.String dsName, java.lang.String catalog, java.lang.String schema, java.lang.String tableName, java.lang.String tableType)
      Retrieve the datasource metadata for only the table provided.
      java.util.Set<Statement> getTableMetadataRdf​(java.lang.String dsName, java.lang.String catalog, java.lang.String schema, java.lang.String tableName, java.lang.String tableType)
      Retrieve the datasource metadata for only the table provided.
      VirtualGraphInfo getVirtualGraphInfo​(java.lang.String theName)
      Return a VirtualGraphInfo for the supplied graph
      VirtualGraphInfo getVirtualGraphInfoOrNull​(java.lang.String theName)
      Return a VirtualGraphInfo for the supplied graph or null if it does not exist
      java.util.Collection<VirtualGraphInfo> getVirtualGraphInfos()
      Returns information on all registered virtual graphs.
      void importFile​(java.lang.String theMappings, java.util.Properties theOptions, java.lang.String theDb, IRI theNg, java.io.File theFile, VirtualGraphAdminConnection.InputFileType theFormat)
      Import a file (CSV/JSON) in a single transaction.
      void importFile​(java.lang.String theMappings, java.util.Properties theOptions, java.lang.String theDb, IRI theNg, java.io.InputStream theData, VirtualGraphAdminConnection.InputFileType theFormat)
      Import a stream (CSV/JSON) in a single transaction
      void importGraph​(java.lang.String theDatabase, java.lang.String theDataSource, java.util.Properties theOptions, java.lang.String theMappings, java.lang.String theNamedGraph, boolean theRemoveAll)
      Import a DB by copy/add a temporary VG.
      default void importGraph​(java.lang.String theDatabase, java.util.Properties theOptions, java.lang.String theMappings, java.lang.String theNamedGraph, boolean theRemoveAll)
      Deprecated.
      use importGraph(String, String, Properties, String, String, boolean) with a null DataSource
      void modifyDataSource​(java.lang.String theName, java.util.Properties theOptionUpdates)
      Update a data source with a set of modifications to its existing options.
      void onlineDataSource​(java.lang.String theName)
      Brings online the registered data source with the given name, as well as its dependent virtual graphs.
      void onlineGraph​(java.lang.String theName)
      Brings online the registered virtual graph with the given name.
      DataSourceQueryResult queryDataSource​(java.lang.String theName, java.lang.String theQuery, java.lang.String theTimeout, java.util.Properties theOptions)
      Query a DataSource with its native query language.
      void refreshCounts​(java.lang.String theDataSourceName, java.lang.String theTableName)
      Update the cardinality (row count) estimates for the supplied data source and table.
      void refreshMetadata​(java.lang.String theDataSourceName, java.lang.String theTableName)
      Refresh the metadata for the supplied data source and table.
      boolean removeDataSource​(java.lang.String theName, boolean theForce)
      Remove a data source, and optionally all virtual graphs associated with it if you use theForce
      boolean removeGraph​(java.lang.String theName)
      Removes the registered virtual graph with the given name.
      void replaceDataSourceMetadata​(java.lang.String theName, java.util.Collection<Statement> theStatements)
      Replaces the metadata for a DataSource with the supplied RDF.
      void shareDataSource​(java.lang.String theName)
      Share a private data source so it can be used by other virtual graphs and will endure after its dependent virtual graph is removed.
      void testDataSource​(java.lang.String theName)
      Test an existing data source connection.
      default void testNewConnection​(java.util.Properties theOptions)
      Test the connection for a new data source.
      default void updateDataSource​(java.lang.String theName, java.util.Properties theOptions)
      Update a data source with the given options.
      default void updateDataSource​(java.lang.String theName, java.util.Properties theOptions, boolean theForce)
      Update a data source with the given options, refreshing dependent virtual graphs
      void updateDataSource​(java.lang.String theName, java.util.Set<Statement> theMetadata, java.util.Properties theOptions, boolean theForce, boolean theShareable)
      Deprecated.
      For Stardog internal use only
      default void updateGraph​(java.lang.String theName, java.lang.String theDataSource, java.lang.String theDatabase, java.util.Properties theOptions, java.lang.String theMappings)
      Registers a new virtual graph using a data source and overwriting a previous version if it exists.
      void updateGraph​(java.lang.String theName, java.lang.String theDatabase, java.util.Properties theOptions, java.lang.Iterable<Statement> theMappings)
      Registers a new virtual graph overwriting a previous version if it exists.
      void updateGraph​(java.lang.String theName, java.lang.String theDatabase, java.util.Properties theOptions, java.lang.String theMappings)
      Deprecated.
      Use updateGraph(String, String, String, Properties, String) with null dataSource
      void updateGraph​(java.lang.String theName, java.lang.String theDataSourceName, java.util.Set<Statement> theMetadata, java.lang.String theDatabase, java.util.Properties theOptions, java.lang.String theMappings)
      Deprecated.
      For Stardog internal use only
      default void updateGraph​(java.lang.String theName, java.util.Properties theOptions, java.lang.Iterable<Statement> theMappings)
      Registers a new virtual graph to be associated with all databases, overwriting a previous version if it exists.
      default void updateGraph​(java.lang.String theName, java.util.Properties theOptions, java.lang.String theMappings)
      Registers a new virtual graph for access from all databases, overwriting a previous version if it exists.

    • Method Detail

      • getVirtualGraphInfos

        java.util.Collection<VirtualGraphInfo> getVirtualGraphInfos()
        Returns information on all registered virtual graphs.

      • getGraph

        VirtualGraph getGraph​(java.lang.String theName)
        Deprecated.
        Use getVirtualGraphInfo or the other methods
        Returns the registered virtual graph with the given name.
        Throws:
        StardogException - if the graph does not exist or there is an error getting the graph

      • getVirtualGraphInfo

        VirtualGraphInfo getVirtualGraphInfo​(java.lang.String theName)
        Return a VirtualGraphInfo for the supplied graph
        Parameters:
        theName - the (local) name of the virtual graph (without the virtual:// prefix)

      • getVirtualGraphInfoOrNull

        VirtualGraphInfo getVirtualGraphInfoOrNull​(java.lang.String theName)
        Return a VirtualGraphInfo for the supplied graph or null if it does not exist

      • getOptions

        java.util.Properties getOptions​(java.lang.String theName)
        Get the virtual graph options

      • getMappings

        default java.lang.String getMappings​(java.lang.String vgName)
        Get mappings for the named virtual graph in R2RML format

      • getMappingsString

        java.lang.String getMappingsString​(java.lang.String theName,
                                   java.lang.String theSyntax)
        Get the serialized mappings

      • removeGraph

        boolean removeGraph​(java.lang.String theName)
        Removes the registered virtual graph with the given name. return true if the virtual graph exists and was removed, false if the virtual graph does not exist
        Throws:
        StardogException - if there is an error removing the graph

      • onlineGraph

        void onlineGraph​(java.lang.String theName)
        Brings online the registered virtual graph with the given name.
        Throws:
        StardogException - if there is an error reloading the graph

      • addGraph

        default void addGraph​(java.lang.String theName,
                      java.util.Properties theOptions,
                      java.lang.Iterable<Statement> theMappings)
        Registers a new virtual graph to be associated with all databases.
        Throws:
        StardogException - if there is already a registered virtual graph with the given name or if there is an error adding the graph

      • addGraph

        void addGraph​(java.lang.String theName,
              java.lang.String theDatabase,
              java.util.Properties theOptions,
              java.lang.Iterable<Statement> theMappings)
        Registers a new virtual graph.
        Throws:
        StardogException - if there is already a registered virtual graph with the given name or if there is an error adding the graph

      • addGraph

        void addGraph​(java.lang.String theName,
              java.lang.String theDataSource,
              java.lang.String theDatabase,
              java.util.Properties theOptions,
              java.lang.Iterable<Statement> theMappings)
        Registers a new virtual graph against a named data source

      • addGraph

        default void addGraph​(java.lang.String theName,
                      java.util.Properties theOptions,
                      java.lang.String theMappings)
        Registers a new virtual graph for access from all databases

      • addGraph

        void addGraph​(java.lang.String theName,
              java.lang.String theDatabase,
              java.util.Properties theOptions,
              java.lang.String theMappings)
        Deprecated.
        Use addGraph(String, String, String, Properties, String) with null dataSource
        Registers a new virtual graph. TODO : another arg for mappings format? We can detect from CLI and require it here
        Throws:
        StardogException - if there is already a registered virtual graph with the given name or if there is an error adding the graph

      • addGraph

        default void addGraph​(java.lang.String theName,
                      java.lang.String theDataSource,
                      java.lang.String theDatabase,
                      java.util.Properties theOptions,
                      java.lang.String theMappings)
        Registers a new virtual graph using a data source.
        Throws:
        StardogException - if there is already a registered virtual graph with the given name or if there is an error adding the graph

      • addGraph

        void addGraph​(java.lang.String theName,
              @Nullable
              java.lang.String theDataSourceName,
              @Nullable
              java.util.Set<Statement> theMetadata,
              java.lang.String theDatabase,
              java.util.Properties theOptions,
              java.lang.String theMappings)
        Deprecated.
        For Stardog internal use only
        Registers a new virtual graph using a data source and, if theMetadata is not null, initializing the metadata cache with the supplied statements.
        Throws:
        StardogException - if there is already a registered virtual graph with the given name or if there is an error adding the graph

      • updateGraph

        default void updateGraph​(java.lang.String theName,
                         java.util.Properties theOptions,
                         java.lang.Iterable<Statement> theMappings)
        Registers a new virtual graph to be associated with all databases, overwriting a previous version if it exists.
        Throws:
        StardogException - if there is an error updating the graph

      • updateGraph

        void updateGraph​(java.lang.String theName,
                 java.lang.String theDatabase,
                 java.util.Properties theOptions,
                 java.lang.Iterable<Statement> theMappings)
        Registers a new virtual graph overwriting a previous version if it exists.
        Throws:
        StardogException - if there is an error updating the graph

      • updateGraph

        default void updateGraph​(java.lang.String theName,
                         java.util.Properties theOptions,
                         java.lang.String theMappings)
        Registers a new virtual graph for access from all databases, overwriting a previous version if it exists.

      • updateGraph

        void updateGraph​(java.lang.String theName,
                 java.lang.String theDatabase,
                 java.util.Properties theOptions,
                 java.lang.String theMappings)
        Deprecated.
        Use updateGraph(String, String, String, Properties, String) with null dataSource
        Registers a new virtual graph overwriting a previous version if it exists. TODO : another arg for mappings format? We can detect from CLI and require it here
        Throws:
        StardogException - if there is an error updating the graph

      • updateGraph

        default void updateGraph​(java.lang.String theName,
                         java.lang.String theDataSource,
                         java.lang.String theDatabase,
                         java.util.Properties theOptions,
                         java.lang.String theMappings)
        Registers a new virtual graph using a data source and overwriting a previous version if it exists.
        Throws:
        StardogException - if there is an error updating the graph

      • updateGraph

        void updateGraph​(java.lang.String theName,
                 @Nullable
                 java.lang.String theDataSourceName,
                 @Nullable
                 java.util.Set<Statement> theMetadata,
                 java.lang.String theDatabase,
                 java.util.Properties theOptions,
                 java.lang.String theMappings)
        Deprecated.
        For Stardog internal use only
        Registers a new virtual graph using a data source, overwriting a previous version if it exists and, if theMetadata is not null, initializing the metadata cache with the supplied statements.

      • importGraph

        default void importGraph​(java.lang.String theDatabase,
                         java.util.Properties theOptions,
                         java.lang.String theMappings,
                         java.lang.String theNamedGraph,
                         boolean theRemoveAll)
        Deprecated.
        use importGraph(String, String, Properties, String, String, boolean) with a null DataSource
        Import a DB by copy/add a temporary VG.

      • importGraph

        void importGraph​(java.lang.String theDatabase,
                 @Nullable
                 java.lang.String theDataSource,
                 java.util.Properties theOptions,
                 java.lang.String theMappings,
                 java.lang.String theNamedGraph,
                 boolean theRemoveAll)
        Import a DB by copy/add a temporary VG.

      • importFile

        void importFile​(java.lang.String theMappings,
                java.util.Properties theOptions,
                java.lang.String theDb,
                IRI theNg,
                java.io.File theFile,
                VirtualGraphAdminConnection.InputFileType theFormat)
        Import a file (CSV/JSON) in a single transaction. Using a file has the advantage of being a repeatable source when negotiating a Kerberos connection.

      • importFile

        void importFile​(java.lang.String theMappings,
                java.util.Properties theOptions,
                java.lang.String theDb,
                IRI theNg,
                java.io.InputStream theData,
                VirtualGraphAdminConnection.InputFileType theFormat)
        Import a stream (CSV/JSON) in a single transaction

      • addDataSource

        void addDataSource​(java.lang.String theName,
                   java.util.Properties theOptions)
        Add a data source with the given properties

      • updateDataSource

        default void updateDataSource​(java.lang.String theName,
                              java.util.Properties theOptions)
        Update a data source with the given options.

      • updateDataSource

        default void updateDataSource​(java.lang.String theName,
                              java.util.Properties theOptions,
                              boolean theForce)
        Update a data source with the given options, refreshing dependent virtual graphs

      • updateDataSource

        void updateDataSource​(java.lang.String theName,
                      @Nullable
                      java.util.Set<Statement> theMetadata,
                      java.util.Properties theOptions,
                      boolean theForce,
                      boolean theShareable)
        Deprecated.
        For Stardog internal use only
        Update a data source with the given options, refreshing dependent virtual graphs. If theMetadata is not null, initializes the metadata cache with the supplied statements.

      • modifyDataSource

        void modifyDataSource​(java.lang.String theName,
                      java.util.Properties theOptionUpdates)
        Update a data source with a set of modifications to its existing options. Options the already exist in the data source but are not included in the updates will be retained. To remove an option, supply the property with an empty ("") value.
        Parameters:
        theName - The local name of the data source
        theOptionUpdates - The options to add or remove from the existing configuration

      • removeDataSource

        boolean removeDataSource​(java.lang.String theName,
                         boolean theForce)
        Remove a data source, and optionally all virtual graphs associated with it if you use theForce

      • shareDataSource

        void shareDataSource​(java.lang.String theName)
        Share a private data source so it can be used by other virtual graphs and will endure after its dependent virtual graph is removed.
        Parameters:
        theName - the (local) name of the data source
        Throws:
        StardogException - if the data source is not found or there is an error making the data source sharable

      • getDataSourceInfos

        java.util.Collection<DataSourceInfo> getDataSourceInfos()
        Returns information on all registered data sources.

      • onlineDataSource

        void onlineDataSource​(java.lang.String theName)
        Brings online the registered data source with the given name, as well as its dependent virtual graphs.
        Throws:
        StardogException - if there is an error reloading the data source

      • testDataSource

        void testDataSource​(java.lang.String theName)
        Test an existing data source connection.
        Throws:
        StardogException - if there is an error testing the data source

      • testNewConnection

        default void testNewConnection​(java.util.Properties theOptions)
        Test the connection for a new data source.

      • getDataSourceInfo

        DataSourceInfo getDataSourceInfo​(java.lang.String theName)
        Retrieve the data source details for the named data source
        Throws:
        java.lang.IllegalArgumentException - if DataSource is not found

      • getDataSourceInfoOrNull

        default DataSourceInfo getDataSourceInfoOrNull​(java.lang.String theName)
        Retrieve the data source details for the named data source or null if it doesn't exist

      • getDataSourceOptions

        java.util.Properties getDataSourceOptions​(java.lang.String theName)
        Get the data source options

      • getDataSourceMetadata

        @Beta
java.util.Set<Statement> getDataSourceMetadata​(java.lang.String theName)
        Retrieve all the metadata that a DataSource has cached for its connection. NOTE: The schema of the metadata may change with new releases.
        Returns:
        the metadata in RDF format

      • getDataSourceTables

        @Beta
com.google.gson.JsonArray getDataSourceTables​(java.lang.String dsName)
        Retrieve all the tables that a DataSource has access to.
        Returns:
        Array of Objects containing catalog, schema, table name and table type

      • getTableMetadataRdf

        @Beta
java.util.Set<Statement> getTableMetadataRdf​(java.lang.String dsName,
                                             @Nullable
                                             java.lang.String catalog,
                                             @Nullable
                                             java.lang.String schema,
                                             java.lang.String tableName,
                                             java.lang.String tableType)
        Retrieve the datasource metadata for only the table provided.
        Returns:
        the metadata in RDF format

      • getTableMetadataJson

        @Beta
com.google.gson.JsonObject getTableMetadataJson​(java.lang.String dsName,
                                                @Nullable
                                                java.lang.String catalog,
                                                @Nullable
                                                java.lang.String schema,
                                                java.lang.String tableName,
                                                java.lang.String tableType)
        Retrieve the datasource metadata for only the table provided.
        Returns:
        the metadata in JSON format

      • refreshMetadata

        void refreshMetadata​(java.lang.String theDataSourceName,
                     @Nullable
                     java.lang.String theTableName)
        Refresh the metadata for the supplied data source and table. If theTableName is null, refresh metadata for all tables that have been loaded through the data source.

        Call this if the schema (column names or data types) has changed for tables accessed by the data source, or if tables were created or dropped since the data source was created or refreshed.

        Parameters:
        theDataSourceName - local name of the data source
        theTableName - name of the table (eg. myschema.mytable or mytable)
        Throws:
        java.lang.IllegalArgumentException - if table was provided but not found

      • applyMetadataDiff

        void applyMetadataDiff​(java.lang.String theDataSourceName,
                       java.util.Set<Statement> theAdded,
                       java.util.Set<Statement> theRemoved,
                       int theCrc,
                       java.util.Map<java.lang.String,​java.lang.Boolean> theVgAvailability)
        Deprecated.
        For Stardog internal use only
        Refresh the metadata for the supplied data source by applying the supplied metadata diffs. Similar to replaceDataSourceMetadata(java.lang.String, java.util.Collection<com.stardog.stark.Statement>) but also reloads dependent virtual graphs.

        This is intended for use in a cluster replication context only.

      • refreshCounts

        void refreshCounts​(java.lang.String theDataSourceName,
                   @Nullable
                   java.lang.String theTableName)
        Update the cardinality (row count) estimates for the supplied data source and table. If theTableName is null, refresh counts for all tables that have been loaded through the data source.
        Parameters:
        theDataSourceName - local name of the data source
        theTableName - name of the table (eg. myschema.mytable or mytable)
        Throws:
        java.lang.IllegalArgumentException - if table was provided but has not been loaded by a virtual graph

      • replaceDataSourceMetadata

        @Beta
void replaceDataSourceMetadata​(java.lang.String theName,
                               java.util.Collection<Statement> theStatements)
        Replaces the metadata for a DataSource with the supplied RDF. NOTE: The schema of the metadata may change with new releases.

      • queryDataSource

        DataSourceQueryResult queryDataSource​(java.lang.String theName,
                                      java.lang.String theQuery,
                                      java.lang.String theTimeout,
                                      java.util.Properties theOptions)
        Query a DataSource with its native query language.

      • getDbTypeOptionsDescription

        java.lang.String getDbTypeOptionsDescription()
        Describes options for configuring data sources and virtual graphs. Includes DB-type families, available options, data types, defaults and whether required. For use with data-driven UIs such as Studio.
        Returns:
        a JSON option detailing DB types and their options

      • getMatchingSuggestions

        java.util.Set<Statement> getMatchingSuggestions​(java.util.Set<Statement> theInput)
        Aligns data source and targets based on their lexical, data type, word sense similarity and returns those alignments as statements
        Parameters:
        theInput - data source and target metadata, optionally with unpublished ontology in designer via a named graph
        Returns:
        alignments