Package com.complexible.stardog.api.admin

# Class DelegatingAdminConnection

java.lang.Object
com.google.common.collect.ForwardingObject
com.complexible.stardog.api.admin.DelegatingAdminConnection

All Implemented Interfaces:
  `AdminConnection`, `AutoCloseable`

public class DelegatingAdminConnection extends com.google.common.collect.ForwardingObject implements AdminConnection

Since:
  2.2
Version:
  5.0.2
Author:
  Michael Grove

- ## Nested Class Summary

  ## Nested classes/interfaces inherited from interface com.complexible.stardog.api.admin.AdminConnection

  `AdminConnection.StreamConsumer, AdminConnection.TxLogRange`

- ## Field Summary

  ### Fields inherited from interface com.complexible.stardog.api.admin.AdminConnection

  `NO_TIMEOUT`

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `DelegatingAdminConnection(AdminConnection theConnection)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `<T extends AdminConnection>
  T`
  `as(Class<T> theView)`
  Return this admin connection viewed as a different type of admin connection.
  `String`
  `backup(String theDatabase, Optional<String> theBackupUrl, Options theOptions)`
  Create a backup of the given database in the specified location.
  `String`
  `backupAll(Options theOptions)`
  Create a backup of the server in the specified location.
  `DatabaseBuilder`
  `builder(Metadata theOptions)`
  Deprecated.
  `Collection<String>`
  `checkpoint(String theDatabase, Options theOptions)`
  Perform a checkpoint operation (list, create, restore) against selected database.
  `void`
  `close()`
  Close this connection.
  `Map<String,Object>`
  `currentStatus(Options theOptions)`
  Return the server status information, including Server/Protocols running, Stardog Home path, OS, etc.
  `protected AdminConnection`
  `delegate()`
  `DatabaseBuilder`
  `disk(String theName)`
  Deprecated.
  `String`
  `drop(String theName)`
  Drop the database with the given name.
  `File`
  `generateDiagnosticReport(com.complexible.stardog.util.report.DiagnosticsReport theDiagnosticsReport)`
  `<T> T`
  `get(String theName, MetaProperty<T> theOption)`
  Gets the value of the specified option in the given database.
  `Metadata`
  `get(String theName, Iterable<? extends MetaProperty<?>> theOptions)`
  Gets the values of the specified options in the given database.
  `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(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.
  `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.
  `Collection<String>`
  `list()`
  List all 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
  `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`
  `renameDatabase(String theOldName, String theNewName)`
  Rename an existing database to a new one
  `String`
  `repair(String theName)`
  Repairs the specified database if it is corrupted.
  `String`
  `replayTransactionLog(String theDb, Path theInputLog, boolean validateLog)`
  Replays the transaction log from the specified file into the given database.
  `String`
  `restore(File theBackup, boolean theOverwrite, String theName)`
  Restore the database backed up to the given location
  `String`
  `restore(String theBackup, 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.
  `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.
  `void`
  `transactionLog(String theDb, AdminConnection.TxLogRange range, AdminConnection.StreamConsumer theStreamConsumer)`
  Streams the transaction log for the specified database and range to the provided consumer.
  `String`
  `verify(String theName)`
  Verify the integrity of specified database's index.
  `String`
  `whoami()`
  Returns the username associated with this connection.

  ### Methods inherited from class com.google.common.collect.ForwardingObject

  `toString`

  ### Methods inherited from class java.lang.Object

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

  ### Methods inherited from interface com.complexible.stardog.api.admin.AdminConnection

  `backup, backup, backup, currentStatus, optimize`

- ## Constructor Details

  - ### DelegatingAdminConnection

    protected DelegatingAdminConnection(AdminConnection theConnection)

- ## Method Details

  - ### builder

    @Deprecated public DatabaseBuilder builder(Metadata theOptions) throws StardogException
    Deprecated.
    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.
    Specified by:
      `builder` in interface `AdminConnection`
    Returns:
      a builder for a database
    Throws:
      `StardogException` - if there was an error while creating the db

  - ### disk

    @Deprecated public DatabaseBuilder disk(String theName) throws StardogException
    Deprecated.
    Create a new builder for creating disk databases
    Specified by:
      `disk` in interface `AdminConnection`
    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

  - ### delegate

    protected AdminConnection delegate()
    Specified by:
      `delegate` in class `com.google.common.collect.ForwardingObject`

  - ### as

    public <T extends AdminConnection> T as(Class<T> theView) throws StardogException
    Return this admin connection viewed as a different type of admin connection.
    Specified by:
      `as` in interface `AdminConnection`
    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

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

  - ### isOpen

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

  - ### newDatabase

    public DatabaseBuilder newDatabase(String theName) throws StardogException
    Create a builder for creating a new database.
    Specified by:
      `newDatabase` in interface `AdminConnection`
    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

    public void renameDatabase(String theOldName, String theNewName) throws StardogException
    Description copied from interface: `AdminConnection`
    Rename an existing database to a new one
    Specified by:
      `renameDatabase` in interface `AdminConnection`
    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

    public 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.
    Specified by:
      `get` in interface `AdminConnection`
    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

    public <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, `AdminConnection.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.
    Specified by:
      `get` in interface `AdminConnection`
    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

    public <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`.
    Specified by:
      `set` in interface `AdminConnection`
    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

    public 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.
    Specified by:
      `getProperty` in interface `AdminConnection`
    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

    public 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.
    Specified by:
      `setProperty` in interface `AdminConnection`
    Parameters:
      `thePropertyName` -
      `theNewValue` -
    Returns:
    Throws:
      `StardogException`

  - ### offline

    public 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.

    Specified by:
      `offline` in interface `AdminConnection`
    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

    public 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.
    Specified by:
      `offline` in interface `AdminConnection`
    Returns:
      the server output of offline
    Throws:
      `StardogException`

  - ### online

    public String online(String theName) throws StardogException
    Makes the database online according to the default strategy
    Specified by:
      `online` in interface `AdminConnection`
    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

    public 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.

    Specified by:
      `optimize` in interface `AdminConnection`
    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

    public Collection<String> list() throws StardogException
    List all the databases in the Stardog server
    Specified by:
      `list` in interface `AdminConnection`
    Returns:
      the list of databases
    Throws:
      `StardogException` - if there was an error getting the list

  - ### repair

    public String repair(String theName) throws StardogException
    Repairs the specified database if it is corrupted. If the database is not corrupted, nothing will be repaired.
    Specified by:
      `repair` in interface `AdminConnection`
    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

  - ### verify

    public String verify(String theName) throws StardogException
    Verify the integrity of specified database's index.
    Specified by:
      `verify` in interface `AdminConnection`
    Parameters:
      `theName` - 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

    public String whoami()
    Description copied from interface: `AdminConnection`
    Returns the username associated with this connection. Useful when API tokens are used to establish the connection.
    Specified by:
      `whoami` in interface `AdminConnection`
    Returns:
      username

  - ### generateDiagnosticReport

    public File generateDiagnosticReport(com.complexible.stardog.util.report.DiagnosticsReport theDiagnosticsReport)
    Specified by:
      `generateDiagnosticReport` in interface `AdminConnection`

  - ### getLogs

    public Path getLogs(Options options)
    Generates a zip file containing the server logs.
    Specified by:
      `getLogs` in interface `AdminConnection`
    Parameters:
      `options` - the `log options`
    Returns:
      a zip file containing the server logs

  - ### shutdown

    public void shutdown() throws com.complexible.stardog.security.StardogSecurityException
    Shutdown the remote Stardog server. You must be connected to the server as a super-user.
    Specified by:
      `shutdown` in interface `AdminConnection`
    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

    public String drop(String theName) throws StardogException
    Drop the database with the given name.
    Specified by:
      `drop` in interface `AdminConnection`
    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

  - ### backupAll

    public String backupAll(Options theOptions) throws StardogException
    Create a backup of the server in the specified location.
    Specified by:
      `backupAll` in interface `AdminConnection`
    Parameters:
      `theOptions` - Collection of BackupOptions
    Returns:
      the output of the backup process
    Throws:
      `StardogException` - if there is an error performing the backup.

  - ### backup

    public 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.
    Specified by:
      `backup` in interface `AdminConnection`
    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`

  - ### restore

    public String restore(File theBackup, boolean theOverwrite, String theName) throws StardogException
    Restore the database backed up to the given location
    Specified by:
      `restore` in interface `AdminConnection`
    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

    public String restore(String theBackup, boolean theOverwrite, String theName) throws StardogException
    Specified by:
      `restore` in interface `AdminConnection`
    Throws:
      `StardogException`

  - ### checkpoint

    public Collection<String> checkpoint(String theDatabase, Options theOptions) throws StardogException
    Perform a checkpoint operation (list, create, restore) against selected database.
    Specified by:
      `checkpoint` in interface `AdminConnection`
    Parameters:
      `theDatabase` - the name of the database for checkpoint operation
      `theOptions` - configuration options for the checkpoint
    Returns:
    Throws:
      `StardogException`

  - ### getUserManager

    public UserManager getUserManager()
    Return the `UserManager` to be used for user-centric security changes
    Specified by:
      `getUserManager` in interface `AdminConnection`
    Returns:
      the UserManager

  - ### getRoleManager

    public RoleManager getRoleManager()
    Return the `RoleManager` to be used for role-centric security changes
    Specified by:
      `getRoleManager` in interface `AdminConnection`
    Returns:
      the RoleManager

  - ### getPermissionManager

    public PermissionManager getPermissionManager()
    Return the `PermissionManager` for changing user & role permissions
    Specified by:
      `getPermissionManager` in interface `AdminConnection`
    Returns:
      the PermissionManager

  - ### getQueryManager

    public QueryManager getQueryManager()
    Return the `QueryManager` for managing running queries
    Specified by:
      `getQueryManager` in interface `AdminConnection`

  - ### getProcessManager

    public com.complexible.stardog.process.ProcessManager getProcessManager()
    Specified by:
      `getProcessManager` in interface `AdminConnection`
    Returns:
      The `ProcessManager` for managing running queries

  - ### getTokenManager

    public com.complexible.stardog.security.TokenManager getTokenManager()
    Return a link to the object that will allow clients to interact with JWT bearer tokens
    Specified by:
      `getTokenManager` in interface `AdminConnection`
    Returns:
      the TokenManager

  - ### currentStatus

    public Map<String,Object> currentStatus(Options theOptions) throws StardogException
    Description copied from interface: `AdminConnection`
    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.
    Specified by:
      `currentStatus` in interface `AdminConnection`
    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

    public StoredQueries getStoredQueries()
    Description copied from interface: `AdminConnection`
    Returns the stored queries in this server. Returned object can be used to add and remove stored queries.
    Specified by:
      `getStoredQueries` in interface `AdminConnection`
    Returns:
      the stored queries

  - ### getStoredFunctions

    public com.complexible.stardog.StoredFunctions getStoredFunctions()
    Description copied from interface: `AdminConnection`
    Returns the stored functions in this server. Returned object can be used to add and remove stored functions.
    Specified by:
      `getStoredFunctions` in interface `AdminConnection`
    Returns:
      the stored functions

  - ### transactionLog

    public void transactionLog(String theDb, AdminConnection.TxLogRange range, AdminConnection.StreamConsumer theStreamConsumer) throws com.complexible.stardog.server.UnknownTransactionException
    Description copied from interface: `AdminConnection`
    Streams the transaction log for the specified database and range to the provided consumer.
    Specified by:
      `transactionLog` in interface `AdminConnection`
    Parameters:
      `theDb` - the database name
      `range` - the range of transaction logs to retrieve
      `theStreamConsumer` - the consumer that will process the transaction log stream
    Throws:
      `com.complexible.stardog.server.UnknownTransactionException`

  - ### replayTransactionLog

    public String replayTransactionLog(String theDb, Path theInputLog, boolean validateLog)
    Description copied from interface: `AdminConnection`
    Replays the transaction log from the specified file into the given database.
    Specified by:
      `replayTransactionLog` in interface `AdminConnection`
    Parameters:
      `theDb` - the database name
      `theInputLog` - the input log file path
      `validateLog` - Validates that the first transaction in the log matches the last transaction in the database before replaying.
    Returns:
      The output of the tx replay operation