com.complexible.stardog.api.admin

Interface AdminConnection

All Superinterfaces:

AutoCloseable

All Known Subinterfaces:

ClusterAdminConnection, VirtualGraphAdminConnection

All Known Implementing Classes:

AbstractAdminConnection, DelegatingAdminConnection, KernelAdminConnection

public interface AdminConnection
extends AutoCloseable

A connection to the Stardog DBMS allowing access to the administrative functions provided by Stardog.

Any methods which return Strings are the information output returned from the server as a result of the invocation.

Since:

2.0

Version:

5.0.2

Author:

Michael Grove

Field Summary

Fields

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

Method Summary

Modifier and Type	Method and Description
<T extends AdminConnection> T	as(Class<T> theView) Return this admin connection viewed as a different type of admin connection.
default String	backup(String theDatabase) Deprecated.
default String	backup(String theDatabase, File theLocation) Deprecated. Use backup(String, Optional, Options) instead
String	backup(String theDatabase, Optional<String> theBackupUrl, Options theOptions) Create a backup of the given database in the specified location.
default String	backup(String theDatabase, String theBackupUrl) Deprecated. Use backup(String, Optional, Options) instead
String	backupAll() Create a backup of the server to the default location.
String	backupAll(File theLocation) Create a backup of the server in the specified location.
String	backupAll(String theLocation) Create a backup of the server in the specified location.
DatabaseBuilder	builder(Metadata theOptions) Deprecated. To be removed in 5.1
void	changeEncryptionPassword(String theOldPassword, String theNewPassword) Change the user managed encryption password.
void	close() Close this connection.
void	createNewEncryptionKey(String thePassPhrase, String keyName) Add a new key for encrypting data.
default Map<String,Object>	currentStatus(boolean theIncludeDbStatus) Deprecated. Use currentStatus(Options) instead
Map<String,Object>	currentStatus(Options theOptions) Return the server status information, including Server/Protocols running, Stardog Home path, OS, etc.
void	disableEncryption(String thePassPhrase) Stop the server from using data encryption on all future data.
DatabaseBuilder	disk(String theName) Deprecated. Use newDatabase(String) instead
String	drop(String theName) Drop the database with the given name.
Collection<String>	fileKeyList(String thePassPhrase) Return the list of keys which have been used for encryption.
Metadata	get(String theName, Iterable<? extends MetaProperty<?>> theOptions) Gets the values of the specified options in the given database.
<T> T	get(String theName, MetaProperty<T> theOption) Gets the value of the specified option in the given database.
PermissionManager	getPermissionManager() Return the PermissionManager for changing user & role permissions
Metadata	getProperty(Collection<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.
UserManager	getUserManager() Return the UserManager to be used for user-centric security changes
boolean	isOpen() Return whether or not this connection is open.
Collection<String>	list() List all of the databases in the Stardog server
DatabaseBuilder	newDatabase(String theName) Create a builder for creating a new database.
String	offline(String theName) Makes the database offline according to the default strategy and default timeout.
String	offline(String theName, long theTime, TimeUnit theTimeUnit) Take the database offline waiting up to the specified timeout before performing a hard off-line.
String	online(String theName) Makes the database online according to the default strategy
default String	optimize(String theName) Optimizes the database with default options.
String	optimize(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	removeEncryptionPassword(String thePassword) Remove the user managed password for the encryption of data.
String	repair(String theName) Repairs the specified database if it is corrupted.
String	restore(File theBackup, boolean theOverwrite, String theName) Restore the database backed up to the given location
String	restore(String theBackupUrl, boolean theOverwrite, String theName)
<T> String	set(String theName, MetaProperty<T> theOption, T theValue) Sets the value of the specified option for the database with the given name.
void	setEncryptionPassword(String thePassword) Encrypt all data keys against the given password.
String	setProperty(String thePropertyName, String theNewValue) Requests that the specified server configuration option value be changed to the new value.
void	shutdown() Shutdown the remote Stardog server.
String	verify(String theDb) Verify the integrity of specified database's index.

Field Detail

NO_TIMEOUT

static final long NO_TIMEOUT

Constant for specifying no timeout when offlining a database.

See Also:

Constant Field Values

Method Detail

as

<T extends AdminConnection> T as(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 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(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(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

get

Metadata get(String theName,
             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(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> String set(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(Collection<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 -

Returns:

Throws:

StardogException

setProperty

String setProperty(String thePropertyName,
                   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

String offline(String theName,
               long theTime,
               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

String offline(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

String online(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 String optimize(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

String optimize(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

Collection<String> list()
                 throws StardogException

List all of the databases in the Stardog server

Returns:

the list of databases

Throws:

StardogException - if there was an error getting the list

repair

String repair(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

String drop(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

setEncryptionPassword

void setEncryptionPassword(String thePassword)

Encrypt all data keys against the given password. This will issue a command to Stardog which will set a user managed password for the encryption of data. If this is not set Stardog will fully manage the encryption keys and all secrets that access them.

Parameters:

thePassword - the password that will protect the encryption keys

Throws:

StardogException

changeEncryptionPassword

void changeEncryptionPassword(String theOldPassword,
                              String theNewPassword)

Change the user managed encryption password.

Parameters:

theOldPassword - the current password

theNewPassword - the new password

Throws:

StardogException

removeEncryptionPassword

void removeEncryptionPassword(String thePassword)

Remove the user managed password for the encryption of data. Once this is removed Stardog will maintain the unencrypted keys which are used to encrypt the data.

Parameters:

thePassword - the current password

Throws:

StardogException

createNewEncryptionKey

void createNewEncryptionKey(String thePassPhrase,
                            String keyName)

Add a new key for encrypting data. This will create a new Stardog managed encryption key. All data added after this new key is created will be encrypted with it. Any previously added data will not be affected by it. If a user managed password has been set then it must be passed in.

Parameters:

thePassPhrase - the current encryption password. If no password is in use this can be an empty string

keyName - the name of the key. This must be unique to the system

Throws:

StardogException

disableEncryption

void disableEncryption(String thePassPhrase)

Stop the server from using data encryption on all future data. Currently encrypted data will be left encrypted. To re-enable encryption createNewEncryptionKey can be called again.

Parameters:

thePassPhrase - the current encryption password. If no password is in use this can be an empty string

Throws:

StardogException

fileKeyList

Collection<String> fileKeyList(String thePassPhrase)

Return the list of keys which have been used for encryption.

Parameters:

thePassPhrase - the current encryption password. If no password is in use this can be an empty string

Returns:

- the Result of the invocation;

Throws:

StardogException - if there is an error performing the backup.

backup

@Deprecated
default String backup(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 String backup(String theDatabase,
                                  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 String backup(String theDatabase,
                                  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

String backup(String theDatabase,
              Optional<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

String backupAll()
          throws StardogException

Create a backup of the server to the default location.

Returns:

the output of the backup process

Throws:

StardogException - if there is an error performing the backup.

backupAll

String backupAll(String theLocation)
          throws StardogException

Create a backup of the server in the specified location.

Parameters:

theLocation - where to store the backup

Returns:

the output of the backup process

Throws:

StardogException - if there is an error performing the backup.

backupAll

String backupAll(File theLocation)
          throws StardogException

Create a backup of the server in the specified location.

Parameters:

theLocation - where to store the backup

Returns:

the output of the backup process

Throws:

StardogException - if there is an error performing the backup.

restore

String restore(File theBackup,
               boolean theOverwrite,
               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

String restore(String theBackupUrl,
               boolean theOverwrite,
               String theName)
        throws StardogException

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

getPermissionManager

PermissionManager getPermissionManager()

Return the PermissionManager for changing user & role permissions

Returns:

the PermissionManager

getQueryManager

QueryManager getQueryManager()

Return the QueryManager for managing running queries

currentStatus

@Deprecated
default Map<String,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

Map<String,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. The embedded connections do not support any options other than MetricOptions.DATABASES.

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

String verify(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