com.clarkparsia.stardog
Class StardogDBMS

java.lang.Object
  com.clarkparsia.stardog.StardogDBMS

public final class StardogDBMS
extends Object

Administrative management functions for working with the Stardog database system.

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

StardogDBMS should not be used by multiple threads at the same time.

Since:

0.7

Version:

1.2

Author:

Michael Grove

Nested Class Summary

static class

StardogDBMS.LoginConfiguration Simple class to log into StardogDBMS.

Field Summary

static char[]	DEFAULT_PASSWD Constant for username used to create a connection when no username or password is present
static String	DEFAULT_USERNAME Constant for username used to create a connection when no username or password is present
static String	EMBEDDED_SERVER_URL Constant for the embedded server URL
static long	NO_TIMEOUT

Method Summary

DatabaseBuilder	builder(Metadata theOptions) Convenience method to create a database builder with the given options.
String	copy(String theName, String theCopyName) Copy a database under a new name.
ConnectionConfiguration	createMemory(String theName) Convenience method to create a temporary in-memory only database with the given name
DatabaseBuilder.DiskDatabaseBuilder	disk(String theName) Create a new builder for creating disk databases
String	drop(String theName) Drop the database with the given name.
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
com.clarkparsia.stardog.QueryManager	getQueryManager() Return the QueryManager for managing running queries
RoleManager	getRoleManager() Return the RoleManager to be used for role-centric security changes
UserManager	getUserManager() Return the UserManager to be used for user-centric security changes
boolean	isOpen()
Collection<String>	list() List all of the databases in the Stardog server
static StardogDBMS	login(String theUsername, char[] thePassword) Deprecated. Use toEmbeddedServer() instead
static StardogDBMS	login(String theURL, String theUsername, char[] thePassword) Deprecated. Use toServer(String) instead
void	logout() Log out of the Stardog server and close the client.
DatabaseBuilder.MemDatabaseBuilder	memory(String theName) Create a new builder for creating in-memory databases
String	migrate(String theName) Migrate the specified database to the most current on-disk format.
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 befor performing a hard off-line.
String	offline(String theName, com.clarkparsia.stardog.OnlineOfflineStrategyType theStrategyType) Deprecated. will be removed in Stardog 1.3, use offline(String, long, TimeUnit)
String	offline(String theName, com.clarkparsia.stardog.OnlineOfflineStrategyType theStrategyType, long theTimeOutInMs) Deprecated. will be removed in Stardog 1.3, use offline(String, long, TimeUnit)
String	online(String theName) Makes the database online according to the default strategy
String	online(String theName, com.clarkparsia.stardog.OnlineOfflineStrategyType theStrategyType) Deprecated. will be removed in Stardog 1.3, use online(String)
String	optimize(String theName) Optimizes the indexes of a given database for query answering after the database has been modified.
<T> void	set(String theName, ConfigProperty<T> theOption, T theValue) Sets the value of the specified option for the database with the given name.
void	shutdown() Shutdown the remote Stardog server.
static void	startEmbeddedServer() Start the local in-JVM Stardog server.
static void	stopEmbeddedServer() Shut down the local in-JVM Stardog server if it is running.
static StardogDBMS.LoginConfiguration	toEmbeddedServer() Returns a StardogDBMS.LoginConfiguration to log into the local embedded server.
static StardogDBMS.LoginConfiguration	toServer(String theURL) Returns a StardogDBMS.LoginConfiguration to log into the local embedded server.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

EMBEDDED_SERVER_URL

public static final String EMBEDDED_SERVER_URL

Constant for the embedded server URL

See Also:

Constant Field Values

DEFAULT_USERNAME

public static final String DEFAULT_USERNAME

Constant for username used to create a connection when no username or password is present

See Also:

Constant Field Values

DEFAULT_PASSWD

public static final char[] DEFAULT_PASSWD

Constant for username used to create a connection when no username or password is present

NO_TIMEOUT

public static final long NO_TIMEOUT

See Also:

Constant Field Values

Method Detail

startEmbeddedServer

public static void startEmbeddedServer()
                                throws StardogException

Start the local in-JVM Stardog server. This server will be available at the URL "snarl://local/"

Throws:

StardogException - if there was an error while starting the server

stopEmbeddedServer

public static void stopEmbeddedServer()

Shut down the local in-JVM Stardog server if it is running.

See Also:

startEmbeddedServer()

toEmbeddedServer

public static StardogDBMS.LoginConfiguration toEmbeddedServer()

Returns a StardogDBMS.LoginConfiguration to log into the local embedded server.

toServer

public static StardogDBMS.LoginConfiguration toServer(String theURL)

Returns a StardogDBMS.LoginConfiguration to log into the local embedded server.

login

public static StardogDBMS login(String theUsername,
                                char[] thePassword)
                         throws StardogException

Deprecated. Use toEmbeddedServer() instead

Log into the local embedded stardog server.

Parameters:

theUsername - the user to log in as

thePassword - the password for the user

Returns:

a client instance logged into the Stardog DBMS

Throws:

StardogException - if the login failed, or the connection could not be established

login

public static StardogDBMS login(String theURL,
                                String theUsername,
                                char[] thePassword)
                         throws StardogException

Deprecated. Use toServer(String) instead

Logs the user in

Parameters:

theURL - the url of the stardog server. if the url does not contain any port value then the default port Protocol.DEFAULT_PORT will be used

theUsername - the user name to be used to log in

thePassword - the password to be use to authenticate the user

Returns:

a client instance logged into the Stardog DBMS

Throws:

StardogException - if the login failed, or the connection could not be established

getUserManager

public UserManager getUserManager()

Return the UserManager to be used for user-centric security changes

Returns:

the UserManager

getRoleManager

public RoleManager getRoleManager()

Return the RoleManager to be used for role-centric security changes

Returns:

the RoleManager

getPermissionManager

public PermissionManager getPermissionManager()

Return the PermissionManager for changing user & role permissions

Returns:

the PermissionManager

getQueryManager

public com.clarkparsia.stardog.QueryManager getQueryManager()

Return the QueryManager for managing running queries

logout

public void logout()

Log out of the Stardog server and close the client.

isOpen

public boolean isOpen()

builder

public DatabaseBuilder builder(Metadata theOptions)
                        throws StardogException

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

createMemory

public ConnectionConfiguration createMemory(String theName)
                                     throws StardogException

Convenience method to create a temporary in-memory only database with the given name

Parameters:

theName - the name of the database to create

Returns:

a valid ConnectionConfiguration to use to connect to the new database

Throws:

StardogException - if there was an error while creating the db

memory

public DatabaseBuilder.MemDatabaseBuilder memory(String theName)
                                          throws StardogException

Create a new builder for creating in-memory databases

Parameters:

theName - the name of the database to be created

Returns:

a builder for a memory database

Throws:

StardogException - if the name of the database is invalid

disk

public DatabaseBuilder.DiskDatabaseBuilder disk(String theName)
                                         throws StardogException

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

drop

public 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

set

public <T> void set(String theName,
                    ConfigProperty<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

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, 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

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.

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

optimize

public String optimize(String theName)
                throws StardogException

Optimizes the indexes of a given database for query answering after the database has been 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. One optimization is to merge differential indexes of the database to the main indexes. Statistics for the database are recomputed as well. These optimizations are automatically performed by Stardog based on database configuration option. If there is nothing to be done for optimization, this function will return without making any changes. After optimizations, the database contents are guaranteed to remain unchanged.

Parameters:

theName - the name of the database to optimize

Returns:

the server output of optimize

Throws:

StardogException - if an error occurs during optimization

online

public 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

online

@Deprecated
public String online(String theName,
                                com.clarkparsia.stardog.OnlineOfflineStrategyType theStrategyType)
              throws StardogException

Deprecated. will be removed in Stardog 1.3, use online(String)

Makes the database online according to the specified strategy

Parameters:

theName - name of the database

theStrategyType - strategy of how the database should be taken online

Returns:

the server output from onlining the database

Throws:

StardogException - if an error occurs during onlining 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 unaccessible to users.

Returns:

the server output of offline

Throws:

StardogException

offline

@Deprecated
public String offline(String theName,
                                 com.clarkparsia.stardog.OnlineOfflineStrategyType theStrategyType)
               throws StardogException

Deprecated. will be removed in Stardog 1.3, use offline(String, long, TimeUnit)

Makes the database offline according to the specified strategy. Offline databases cannot be queried or updated and will be unaccessible to users.

Returns:

the server output of offline

Throws:

StardogException

offline

@Deprecated
public String offline(String theName,
                                 com.clarkparsia.stardog.OnlineOfflineStrategyType theStrategyType,
                                 long theTimeOutInMs)
               throws StardogException

Deprecated. will be removed in Stardog 1.3, use offline(String, long, TimeUnit)

Makes the database offline according to the specified strategy and timeout. Offline databases cannot be queried or updated and will be unaccessible to users.

Parameters:

theName - name of the database

theStrategyType - offline strategy type

theTimeOutInMs - timeout in milliseconds

Returns:

the server output of offline

Throws:

StardogException - if there was an error while offlining the database

offline

public String offline(String theName,
                      long theTime,
                      TimeUnit theTimeUnit)
               throws StardogException

Take the database offline waiting up to the specified timeout befor 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

copy

public String copy(String theName,
                   String theCopyName)
            throws StardogException

Copy a database under a new name.

Parameters:

theName - name of the database to copy

theCopyName - name of the new database that will be created

Returns:

the output of the copy operation

Throws:

StardogException - if an error occurs during copy

list

public 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

shutdown

public void shutdown()
              throws com.clarkparsia.stardog.security.StardogSecurityException

Shutdown the remote Stardog server. You must be connected to the server as a super-user, and you cannot shutdown the embedded server. In those cases, it's probably more relevant to use stopEmbeddedServer().

Throws:

com.clarkparsia.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.

migrate

public String migrate(String theName)
               throws StardogException

Migrate the specified database to the most current on-disk format. If the database already uses the most recent format, nothing will be migrated.

Parameters:

theName - the name of the database to migrate

Returns:

the server output of the migration

Throws:

StardogException - if there was an error while migrating