Package com.complexible.stardog.api.admin

Interface AdminConnection

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static long NO_TIMEOUT
      Constant for specifying no timeout when offlining a database.

    • Method Summary

      All Methods Instance Methods Abstract Methods Default Methods Deprecated Methods 
      Modifier and Type Method Description
      <T extends AdminConnection>
      T      		 as​(java.lang.Class<T> theView)
      Return this admin connection viewed as a different type of admin connection.
      default java.lang.String backup​(java.lang.String theDatabase)
      Deprecated.
      default java.lang.String backup​(java.lang.String theDatabase, java.io.File theLocation)
      Deprecated.
      Use backup(String, Optional, Options) instead
      default java.lang.String backup​(java.lang.String theDatabase, java.lang.String theBackupUrl)
      Deprecated.
      Use backup(String, Optional, Options) instead
      java.lang.String backup​(java.lang.String theDatabase, java.util.Optional<java.lang.String> theBackupUrl, Options theOptions)
      Create a backup of the given database in the specified location.
      java.lang.String backupAll​(Options theOptions)
      Create a backup of the server in the specified location.
      DatabaseBuilder builder​(Metadata theOptions)
      Deprecated.
      To be removed in 5.1
      java.util.Collection<java.lang.String> checkpoint​(java.lang.String theDatabase, Options theOptions)
      Perform a checkpoint operation (list, create, restore) against selected database.
      void close()
      Close this connection.
      default java.util.Map<java.lang.String,​java.lang.Object> currentStatus​(boolean theIncludeDbStatus)
      Deprecated.
      Use currentStatus(Options) instead
      java.util.Map<java.lang.String,​java.lang.Object> currentStatus​(Options theOptions)
      Return the server status information, including Server/Protocols running, Stardog Home path, OS, etc.
      DatabaseBuilder disk​(java.lang.String theName)
      Deprecated.
      Use newDatabase(String) instead
      java.lang.String drop​(java.lang.String theName)
      Drop the database with the given name.
      java.io.File generateDiagnosticReport​(com.complexible.stardog.util.report.DiagnosticsReport theDiagnosticsReport)  
      <T> T get​(java.lang.String theName, MetaProperty<T> theOption)
      Gets the value of the specified option in the given database.
      Metadata get​(java.lang.String theName, java.lang.Iterable<? extends MetaProperty<?>> theOptions)
      Gets the values of the specified options in the given database.
      java.nio.file.Path getLogs​(Options options)
      Generates a zip file containing the server logs.
      PermissionManager getPermissionManager()
      Return the PermissionManager for changing user & role permissions
      com.complexible.stardog.process.ProcessManager getProcessManager()  
      Metadata getProperty​(java.util.Collection<java.lang.String> thePropertyNames)
      Gets the property value for a server configuration option.
      QueryManager getQueryManager()
      Return the QueryManager for managing running queries
      RoleManager getRoleManager()
      Return the RoleManager to be used for role-centric security changes
      com.complexible.stardog.StoredFunctions getStoredFunctions()
      Returns the stored functions in this server.
      StoredQueries getStoredQueries()
      Returns the stored queries in this server.
      com.complexible.stardog.security.TokenManager getTokenManager()
      Return a link to the object that will allow clients to interact with JWT bearer tokens
      UserManager getUserManager()
      Return the UserManager to be used for user-centric security changes
      boolean isOpen()
      Return whether or not this connection is open.
      java.util.Collection<java.lang.String> list()
      List all the databases in the Stardog server
      DatabaseBuilder newDatabase​(java.lang.String theName)
      Create a builder for creating a new database.
      java.lang.String offline​(java.lang.String theName)
      Makes the database offline according to the default strategy and default timeout.
      java.lang.String offline​(java.lang.String theName, long theTime, java.util.concurrent.TimeUnit theTimeUnit)
      Take the database offline waiting up to the specified timeout before performing a hard off-line.
      java.lang.String online​(java.lang.String theName)
      Makes the database online according to the default strategy
      default java.lang.String optimize​(java.lang.String theName)
      Optimizes the database with default options.
      java.lang.String optimize​(java.lang.String theName, Metadata theOptions)
      Optimizes the indexes of a given database for query answering and disk utilization after the database has been heavily modified.
      void renameDatabase​(java.lang.String theOldName, java.lang.String theNewName)
      Rename an existing database to a new one
      java.lang.String repair​(java.lang.String theName)
      Repairs the specified database if it is corrupted.
      java.lang.String restore​(java.io.File theBackup, boolean theOverwrite, java.lang.String theName)
      Restore the database backed up to the given location
      java.lang.String restore​(java.lang.String theBackupUrl, boolean theOverwrite, java.lang.String theName)  
      <T> java.lang.String set​(java.lang.String theName, MetaProperty<T> theOption, T theValue)
      Sets the value of the specified option for the database with the given name.
      java.lang.String setProperty​(java.lang.String thePropertyName, java.lang.String theNewValue)
      Requests that the specified server configuration option value be changed to the new value.
      void shutdown()
      Shutdown the remote Stardog server.
      java.lang.String verify​(java.lang.String theDb)
      Verify the integrity of specified database's index.
      java.lang.String whoami()
      Returns the username associated with this connection.

    • Method Detail

      • as

        <T extends AdminConnection> T as​(java.lang.Class<T> theView)
                          throws StardogException
        Return this admin connection viewed as a different type of admin connection.
        Type Parameters:
        T - the connection view to return
        Parameters:
        theView - the type of connection to view this object as
        Returns:
        the new view of the connection.
        Throws:
        StardogException - if the connection cannot be viewed as the provided type. This could be from the parent connection having been closed or it does not support the provided view.

      • close

        void close()
    throws StardogException
        Close this connection. If the connection is already closed, this will have no effect.
        Specified by:
        close in interface java.lang.AutoCloseable
        Throws:
        StardogException - if there was an error while closing

      • isOpen

        boolean isOpen()
        throws StardogException
        Return whether or not this connection is open.
        Returns:
        true if it is open, false otherwise
        Throws:
        StardogException - if there was an error with the connection

      • builder

        @Deprecated
DatabaseBuilder builder​(Metadata theOptions)
                 throws StardogException
        Deprecated.
        To be removed in 5.1
        Convenience method to create a database builder with the given options. The provided options should include at least two options: the name of the database and the index type.
        Returns:
        a builder for a database
        Throws:
        StardogException - if there was an error while creating the db

      • disk

        @Deprecated
DatabaseBuilder disk​(java.lang.String theName)
              throws StardogException
        Deprecated.
        Use newDatabase(String) instead
        Create a new builder for creating disk databases
        Parameters:
        theName - the name of the disk database to create
        Returns:
        a builder for a disk database
        Throws:
        StardogException - if the name of the database is invalid

      • newDatabase

        DatabaseBuilder newDatabase​(java.lang.String theName)
                     throws StardogException
        Create a builder for creating a new database.
        Parameters:
        theName - the name of the database to create
        Returns:
        a builder for a database
        Throws:
        StardogException - if the name of the database is invalid

      • renameDatabase

        void renameDatabase​(java.lang.String theOldName,
                    java.lang.String theNewName)
             throws StardogException
        Rename an existing database to a new one
        Parameters:
        theOldName - the old database name
        theNewName - the new database name
        Throws:
        StardogException - if the database name is invalid or if the database is not offline.

      • get

        Metadata get​(java.lang.String theName,
             java.lang.Iterable<? extends MetaProperty<?>> theOptions)
      throws StardogException
        Gets the values of the specified options in the given database. The returned map is not guaranteed to contain all the specified options. Only the values for known Stardog options that are should be readable will be contained in the result. This function will throw an exception if the user does not have read access to the database metadata.
        Parameters:
        theName - database name
        theOptions - options for which values will be retrieved
        Returns:
        metadata that contains values for the specified met properties
        Throws:
        StardogException - if an error occurs while retrieving option values

      • get

        <T> T get​(java.lang.String theName,
          MetaProperty<T> theOption)
   throws StardogException
        Gets the value of the specified option in the given database. The function will return null if the option is NOT a known Stardog options, or if it is NOT readable. The function may also return null if the option is set to null value for the database. To differentiate these cases, get(String, Iterable) function can be used instead. This function will throw an exception if the user does not have read access to the database metadata.
        Type Parameters:
        T - type of the option value
        Parameters:
        theName - name of the database
        theOption - the option to get
        Returns:
        current value of the option in the database or null as explained above
        Throws:
        StardogException - if there was an error while getting the value

      • set

        <T> java.lang.String set​(java.lang.String theName,
                         MetaProperty<T> theOption,
                         T theValue)
                  throws StardogException
        Sets the value of the specified option for the database with the given name. For this function to complete without an exception, the logged in user should have write access to the database metadata for the specified database, the option should be a known Stardog option, the provided value should be valid, and either the option should be writable online or it should be writable and the database should NOT be online.
        Type Parameters:
        T - type of the option value
        Parameters:
        theName - name of the database
        theOption - option to set
        theValue - option value
        Throws:
        StardogException - if an error occurs trying to set the option value

      • getProperty

        Metadata getProperty​(java.util.Collection<java.lang.String> thePropertyNames)
              throws StardogException
        Gets the property value for a server configuration option. This value will be the default for the option or the override in the properties file.
        Parameters:
        thePropertyNames - filter for the properties to return. Empty set will match all properties.
        Returns:
        Metadata created with config values "MetaProperty.config(key, value).temporary().build()"
        Throws:
        StardogException

      • setProperty

        java.lang.String setProperty​(java.lang.String thePropertyName,
                             java.lang.String theNewValue)
                      throws StardogException
        Requests that the specified server configuration option value be changed to the new value. This method will notify any listening server modules about the change request. It is not guaranteed that the listening module will update the value.
        Parameters:
        thePropertyName -
        theNewValue -
        Returns:
        Throws:
        StardogException

      • offline

        java.lang.String offline​(java.lang.String theName,
                         long theTime,
                         java.util.concurrent.TimeUnit theTimeUnit)
                  throws StardogException

        Take the database offline waiting up to the specified timeout before performing a hard off-line. A database going offline will allow open connections to complete, but will not accept new, incoming connections.

        Offline databases cannot be queried or updated and will be unaccessible to users.

        Specifying a timeout of 0 will immediately shut down the database severing all open connections, i.e. a hard shutdown.

        Parameters:
        theName - name of the database
        theTime - timeout duration, must be a positive number
        theTimeUnit - the unit of time for the timeout, cannot be null
        Returns:
        the server output of offline
        Throws:
        StardogException - if there was an error while offlining the database

      • offline

        java.lang.String offline​(java.lang.String theName)
                  throws StardogException
        Makes the database offline according to the default strategy and default timeout. Offline databases cannot be queried or updated and will be inaccessible to users.
        Returns:
        the server output of offline
        Throws:
        StardogException

      • online

        java.lang.String online​(java.lang.String theName)
                 throws StardogException
        Makes the database online according to the default strategy
        Parameters:
        theName - the name of the database
        Returns:
        the server output of onlining the database
        Throws:
        StardogException - if there was an error while onlining the database

      • optimize

        default java.lang.String optimize​(java.lang.String theName)
                           throws StardogException
        Optimizes the database with default options.
        Parameters:
        theName - the name of the database to optimize
        Returns:
        the server output of optimize
        Throws:
        StardogException - if an error occurs during optimization

      • optimize

        java.lang.String optimize​(java.lang.String theName,
                          Metadata theOptions)
                   throws StardogException
        Optimizes the indexes of a given database for query answering and disk utilization after the database has been heavily modified. If a database has been modified with a large number of additions or removals, some internal structures may become less optimized for query answering. This utility will perform several operations that will help with query answering performance. Which operations are performed depends on the options given.

        Optimization will NOT modify the database contents. The data layout, indexes and other internal structures might change but the data stored in the database will remain same.

        Parameters:
        theName - the name of the database to optimize
        theOptions - options specifying the specific optimization steps to perform or empty for default optimizations
        Returns:
        the server output of optimize
        Throws:
        StardogException - if an error occurs during optimization

      • list

        java.util.Collection<java.lang.String> list()
                                     throws StardogException
        List all the databases in the Stardog server
        Returns:
        the list of databases
        Throws:
        StardogException - if there was an error getting the list

      • repair

        java.lang.String repair​(java.lang.String theName)
                 throws StardogException
        Repairs the specified database if it is corrupted. If the database is not corrupted, nothing will be repaired.
        Parameters:
        theName - the name of the database to repair
        Returns:
        the server output of the repair
        Throws:
        StardogException - if there was an error while repairing

      • shutdown

        void shutdown()
       throws com.complexible.stardog.security.StardogSecurityException
        Shutdown the remote Stardog server. You must be connected to the server as a super-user.
        Throws:
        com.complexible.stardog.security.StardogSecurityException - if you are attempting to shut down the embedded server or if you are not a super-user and are trying to shut down a remote server.

      • drop

        java.lang.String drop​(java.lang.String theName)
               throws StardogException
        Drop the database with the given name.
        Parameters:
        theName - the name of the database to drop
        Returns:
        the Result of the invocation
        Throws:
        StardogException - if there was an error while dropping the database

      • backup

        @Deprecated
default java.lang.String backup​(java.lang.String theDatabase)
                         throws StardogException
        Deprecated.
        Create a backup of the given database to the default location.
        Parameters:
        theDatabase - the name of the database to back up
        Returns:
        the output of the backup process
        Throws:
        StardogException - if there is an error performing the backup.

      • backup

        @Deprecated
default java.lang.String backup​(java.lang.String theDatabase,
                                java.io.File theLocation)
                         throws StardogException
        Deprecated.
        Use backup(String, Optional, Options) instead
        Create a backup of the given database in the specified location.
        Parameters:
        theDatabase - the name of the database to back up
        theLocation - where to store the backup
        Returns:
        the output of the backup process
        Throws:
        StardogException - if there is an error performing the backup.

      • backup

        @Deprecated
default java.lang.String backup​(java.lang.String theDatabase,
                                java.lang.String theBackupUrl)
                         throws StardogException
        Deprecated.
        Use backup(String, Optional, Options) instead
        Create a backup of the given database in the specified location.
        Parameters:
        theDatabase - the name of the database to back up
        theBackupUrl - where to store the backup
        Returns:
        the output of the backup process
        Throws:
        StardogException - if there is an error performing the backup.

      • backup

        java.lang.String backup​(java.lang.String theDatabase,
                        java.util.Optional<java.lang.String> theBackupUrl,
                        Options theOptions)
                 throws StardogException
        Create a backup of the given database in the specified location. The location can be a file path on the server or a URL pointing to S3 or GCP. Configuration options can be specified for the backup operation.
        Parameters:
        theDatabase - the name of the database to back up
        theBackupUrl - where to store the backup or empty if the default location should be used
        theOptions - configuration options to use for backups
        Returns:
        Throws:
        StardogException

      • backupAll

        java.lang.String backupAll​(Options theOptions)
                    throws StardogException
        Create a backup of the server in the specified location.
        Parameters:
        theOptions - Collection of BackupOptions
        Returns:
        the output of the backup process
        Throws:
        StardogException - if there is an error performing the backup.

      • restore

        java.lang.String restore​(java.io.File theBackup,
                         boolean theOverwrite,
                         java.lang.String theName)
                  throws StardogException
        Restore the database backed up to the given location
        Parameters:
        theBackup - the location of the backup
        theOverwrite - whether or not to overwrite any existing database
        theName - a new name for the restored database
        Returns:
        the output of the restore process
        Throws:
        StardogException - if there was an error restoring the database from a backup

      • restore

        java.lang.String restore​(java.lang.String theBackupUrl,
                         boolean theOverwrite,
                         java.lang.String theName)
                  throws StardogException
        Throws:
        StardogException

      • checkpoint

        java.util.Collection<java.lang.String> checkpoint​(java.lang.String theDatabase,
                                                  Options theOptions)
                                           throws StardogException
        Perform a checkpoint operation (list, create, restore) against selected database.
        Parameters:
        theDatabase - the name of the database for checkpoint operation
        theOptions - configuration options for the checkpoint
        Returns:
        Throws:
        StardogException

      • getUserManager

        UserManager getUserManager()
        Return the UserManager to be used for user-centric security changes
        Returns:
        the UserManager

      • getRoleManager

        RoleManager getRoleManager()
        Return the RoleManager to be used for role-centric security changes
        Returns:
        the RoleManager

      • getProcessManager

        com.complexible.stardog.process.ProcessManager getProcessManager()
        Returns:
        The ProcessManager for managing running queries

      • getTokenManager

        com.complexible.stardog.security.TokenManager getTokenManager()
        Return a link to the object that will allow clients to interact with JWT bearer tokens
        Returns:
        the TokenManager

      • currentStatus

        @Deprecated
default java.util.Map<java.lang.String,​java.lang.Object> currentStatus​(boolean theIncludeDbStatus)
                                                                      throws StardogException
        Deprecated.
        Use currentStatus(Options) instead
        Return the server status information, including Server/Protocols running, Stardog Home path, OS, etc
        Parameters:
        theIncludeDbStatus - if true the database status information about each database is included
        Returns:
        the Metadata with the DBMS information
        Throws:
        StardogException - if there was an error retrieving the DBMS info

      • currentStatus

        java.util.Map<java.lang.String,​java.lang.Object> currentStatus​(Options theOptions)
                                                              throws StardogException
        Return the server status information, including Server/Protocols running, Stardog Home path, OS, etc. The options can be used to configure which metrics will be included in the results.
        Parameters:
        theOptions - the options for customizing the metrics that will be returned
        Returns:
        the metrics showing the server status
        Throws:
        StardogException - if there was an error retrieving the DBMS info
        See Also:
        MetricOptions

      • getStoredQueries

        StoredQueries getStoredQueries()
        Returns the stored queries in this server. Returned object can be used to add and remove stored queries.
        Returns:
        the stored queries
        Since:
        4.2

      • getStoredFunctions

        com.complexible.stardog.StoredFunctions getStoredFunctions()
        Returns the stored functions in this server. Returned object can be used to add and remove stored functions.
        Returns:
        the stored functions
        Since:
        5.1

      • verify

        java.lang.String verify​(java.lang.String theDb)
        Verify the integrity of specified database's index.
        Parameters:
        theDb - the name of the database to verify
        Returns:
        the output of the verify operation
        Throws:
        StardogException - if there was an error while verifying the database

      • whoami

        java.lang.String whoami()
        Returns the username associated with this connection. Useful when API tokens are used to establish the connection.
        Returns:
        username

      • generateDiagnosticReport

        java.io.File generateDiagnosticReport​(com.complexible.stardog.util.report.DiagnosticsReport theDiagnosticsReport)

      • getLogs

        java.nio.file.Path getLogs​(Options options)
        Generates a zip file containing the server logs.
        Parameters:
        options - the log options
        Returns:
        a zip file containing the server logs