Interface AdminConnection
-
- All Superinterfaces:
java.lang.AutoCloseable
- All Known Subinterfaces:
ClusterAdminConnection
,ComputeAdminConnection
,VirtualGraphAdminConnection
- All Known Implementing Classes:
AbstractAdminConnection
,DelegatingAdminConnection
,KernelAdminConnection
public interface AdminConnection extends java.lang.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 Description static long
NO_TIMEOUT
Constant for specifying no timeout whenofflining
a database.
-
Method Summary
All Methods Instance Methods Abstract Methods Default Methods Deprecated Methods Modifier and Type Method Description <T extends AdminConnection>
Tas(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.Usebackup(String, Optional, Options)
insteaddefault java.lang.String
backup(java.lang.String theDatabase, java.lang.String theBackupUrl)
Deprecated.Usebackup(String, Optional, Options)
insteadjava.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.1void
changeEncryptionPassword(java.lang.String theOldPassword, java.lang.String theNewPassword)
Change the user managed encryption password.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.void
createNewEncryptionKey(java.lang.String thePassPhrase, java.lang.String keyName)
Add a new key for encrypting data.default java.util.Map<java.lang.String,java.lang.Object>
currentStatus(boolean theIncludeDbStatus)
Deprecated.UsecurrentStatus(Options)
insteadjava.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.void
disableEncryption(java.lang.String thePassPhrase)
Stop the server from using data encryption on all future data.DatabaseBuilder
disk(java.lang.String theName)
Deprecated.UsenewDatabase(String)
insteadjava.lang.String
drop(java.lang.String theName)
Drop the database with the given name.java.util.Collection<java.lang.String>
fileKeyList(java.lang.String thePassPhrase)
Return the list of keys which have been used for encryption.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.PermissionManager
getPermissionManager()
Return thePermissionManager
for changing user & role permissionscom.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 theQueryManager
for managing running queriesRoleManager
getRoleManager()
Return theRoleManager
to be used for role-centric security changescom.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 tokensUserManager
getUserManager()
Return theUserManager
to be used for user-centric security changesboolean
isOpen()
Return whether or not this connection is open.java.util.Collection<java.lang.String>
list()
List all the databases in the Stardog serverDatabaseBuilder
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 strategydefault 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
removeEncryptionPassword(java.lang.String thePassword)
Remove the user managed password for the encryption of data.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 locationjava.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.void
setEncryptionPassword(java.lang.String thePassword)
Encrypt all data keys against the given password.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.
-
-
-
Field Detail
-
NO_TIMEOUT
static final long NO_TIMEOUT
Constant for specifying no timeout whenofflining
a database.- See Also:
- Constant Field Values
-
-
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 interfacejava.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.1Convenience 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.UsenewDatabase(String)
insteadCreate 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
-
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 tocontain
all the specified options. Only the values forknown Stardog options
that are should bereadable
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 nametheOptions
- 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 returnnull
if the option is NOT aknown Stardog options
, or if it is NOTreadable
. The function may also returnnull
if the option is set tonull
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 databasetheOption
- 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 aknown Stardog option
, the provided value should bevalid
, and either the option should bewritable online
or it should bewritable
and the database should NOT beonline
.- Type Parameters:
T
- type of the option value- Parameters:
theName
- name of the databasetheOption
- option to settheValue
- 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 databasetheTime
- timeout duration, must be a positive numbertheTimeUnit
- 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 optimizetheOptions
- 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
-
setEncryptionPassword
void setEncryptionPassword(java.lang.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(java.lang.String theOldPassword, java.lang.String theNewPassword)
Change the user managed encryption password.- Parameters:
theOldPassword
- the current passwordtheNewPassword
- the new password- Throws:
StardogException
-
removeEncryptionPassword
void removeEncryptionPassword(java.lang.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(java.lang.String thePassPhrase, java.lang.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 stringkeyName
- the name of the key. This must be unique to the system- Throws:
StardogException
-
disableEncryption
void disableEncryption(java.lang.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
java.util.Collection<java.lang.String> fileKeyList(java.lang.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 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.Usebackup(String, Optional, Options)
insteadCreate a backup of the given database in the specified location.- Parameters:
theDatabase
- the name of the database to back uptheLocation
- 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.Usebackup(String, Optional, Options)
insteadCreate a backup of the given database in the specified location.- Parameters:
theDatabase
- the name of the database to back uptheBackupUrl
- 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 uptheBackupUrl
- where to store the backup or empty if the default location should be usedtheOptions
- 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 backuptheOverwrite
- whether or not to overwrite any existing databasetheName
- 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 operationtheOptions
- configuration options for the checkpoint- Returns:
- Throws:
StardogException
-
getUserManager
UserManager getUserManager()
Return theUserManager
to be used for user-centric security changes- Returns:
- the UserManager
-
getRoleManager
RoleManager getRoleManager()
Return theRoleManager
to be used for role-centric security changes- Returns:
- the RoleManager
-
getPermissionManager
PermissionManager getPermissionManager()
Return thePermissionManager
for changing user & role permissions- Returns:
- the PermissionManager
-
getQueryManager
QueryManager getQueryManager()
Return theQueryManager
for managing running queries
-
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.UsecurrentStatus(Options)
insteadReturn the server status information, including Server/Protocols running, Stardog Home path, OS, etc- Parameters:
theIncludeDbStatus
- if true thedatabase 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. Theoptions
can be used to configure which metrics will be included in the results. The embedded connections do not support any options other thanMetricOptions.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
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
-
generateDiagnosticReport
java.io.File generateDiagnosticReport(com.complexible.stardog.util.report.DiagnosticsReport theDiagnosticsReport)
-
-