Package org.firebirdsql.management

Interface FBManagerMBean

All Superinterfaces:

java.lang.AutoCloseable

All Known Implementing Classes:

FBManager

public interface FBManagerMBean
extends java.lang.AutoCloseable

API for FBManager, for creating and dropping databases.

The class FBManager provides an API to create and drop databases, including options to limit the lifetime of a database

 // Use try-with-resources to automatically stop (close) FBManager
 try (FBManager manager = new FBManager()) {
     manager.setServer("localhost");
     manager.setUser("sysdba");
     manager.setPassword("masterkey");
     manager.setFileName("path/to/database.fdb");
     manager.setPageSize(PageSizeConstants.SIZE_16K);
     manager.setDefaultCharacterSet("UTF8");

     // Create database when manager is started
     manager.setCreateOnStart(true);
     // Drop database on creation if it already exists
     manager.setForceCreate(true);
     // Drop database when manager is stopped
     manager.setDropOnStop(true);
     manager.start();

     // Use database...
 }
 // After end of try-with-resources, the database will be dropped
 

Author:

David Jencks

Method Summary

Modifier and Type	Method	Description
void	close()	Alias for stop()
void	createDatabase(java.lang.String fileName, java.lang.String user, java.lang.String password)	Create a database with the specified file name, username and password on the specified server and port.
void	createDatabase(java.lang.String fileName, java.lang.String user, java.lang.String password, java.lang.String roleName)	Create a database with the specified file name, username, password and role on the specified server and port.
void	dropDatabase(java.lang.String fileName, java.lang.String user, java.lang.String password)	Drop a database with the specified file name, username and password on the specified server and port.
void	dropDatabase(java.lang.String fileName, java.lang.String user, java.lang.String password, java.lang.String roleName)	Drop a database with the specified file name, username, password and role on the specified server and port.
java.lang.String	getDefaultCharacterSet()
int	getDialect()
java.lang.String	getFileName()
java.lang.Boolean	getForceWrite()
java.lang.String	getName()
int	getPageSize()
java.lang.String	getPassword()
int	getPort()
java.lang.String	getRoleName()
java.lang.String	getServer()
java.lang.String	getState()
java.lang.String	getType()
java.lang.String	getUserName()
boolean	isCreateOnStart()	Get if the database will be created when calling start().
boolean	isDatabaseExists(java.lang.String fileName, java.lang.String user, java.lang.String password)	Check if a database exists with the specified file name, username and password on the specified server and port.
boolean	isDropOnStop()	Get if the database will be created when calling stop().
boolean	isForceCreate()	Get if the database will be dropped if exists when creating a database.
void	setCreateOnStart(boolean createOnStart)	Set if the database will be created when calling start().
void	setDefaultCharacterSet(java.lang.String firebirdCharsetName)	Set the default database character set to use when creating a new database.
void	setDialect(int dialect)	Set the database dialect to use when creating a new database.
void	setDropOnStop(boolean dropOnStop)	Set if the database will be created when calling stop().
void	setFileName(java.lang.String fileName)	Set the file name or alias of the database.
void	setForceCreate(boolean forceCreate)	Set if the database will be dropped if exists when creating a database.
void	setForceWrite(java.lang.Boolean forceWrite)	Control force write behaviour of the created database.
void	setPageSize(int pageSize)	Set the page size to use when creating a new database.
void	setPassword(java.lang.String password)	Set the password.
void	setPort(int port)	Set the port of the Firebird server.
void	setRoleName(java.lang.String roleName)
void	setServer(java.lang.String host)	Set the host name of the Firebird server.
void	setType(java.lang.String type)	Set the GDS plugin type to use.
void	setUserName(java.lang.String userName)	Set the username.
void	start()	Start this manager.
void	stop()	Stop this manager.

Method Detail

start

void start()
    throws java.lang.Exception

Start this manager.

If isCreateOnStart() is true, will attempt to create a new database specified using the server, port, fileName and related properties. If the specified already exists, nothing will be created unless isForceCreate() is true. When forceCreate is true an attempt will be made to drop the database.

Throws:

java.lang.IllegalStateException - If this manager is not started

java.lang.Exception - For failures to start or create the database

stop

void stop()
   throws java.lang.Exception

Stop this manager.

If isDropOnStop() is true, will attempt to drop the database specified using the server, port, fileName and related properties,

If the manager is currently stopped, this method will do nothing.

Throws:

java.lang.Exception - For failures to drop the database.

close

void close()
    throws java.lang.Exception

Alias for stop()

Specified by:

close in interface java.lang.AutoCloseable

Throws:

java.lang.Exception

getName

java.lang.String getName()

Returns:

Descriptive name of this manager

getState

java.lang.String getState()

Returns:

Current state ("Stopped" or "Started"

setServer

void setServer(java.lang.String host)

Set the host name of the Firebird server.

Parameters:

host - Hostname

getServer

java.lang.String getServer()

Returns:

The host name of the Firebird server (default is "localhost")

setPort

void setPort(int port)

Set the port of the Firebird server.

Parameters:

port - Port of the Firebird server

getPort

int getPort()

Returns:

The port of the Firebird server (default is 3050)

getFileName

java.lang.String getFileName()

Returns:

File name or alias of the database

setFileName

void setFileName(java.lang.String fileName)

Set the file name or alias of the database.

Parameters:

fileName - File name or alias of the database

getType

java.lang.String getType()

Returns:

GDS plugin type name (default is GDSFactory.getDefaultGDSType())

setType

void setType(java.lang.String type)

Set the GDS plugin type to use.

Parameters:

type - GDS plugin type name (PURE_JAVA, NATIVE, EMBEDDED)

getUserName

java.lang.String getUserName()

Returns:

User name

setUserName

void setUserName(java.lang.String userName)

Set the username.

Parameters:

userName - Username

getPassword

java.lang.String getPassword()

Returns:

password

setPassword

void setPassword(java.lang.String password)

Set the password.

Parameters:

password - Password

getRoleName

java.lang.String getRoleName()

Returns:

SQL role to use.

setRoleName

void setRoleName(java.lang.String roleName)

Parameters:

roleName - SQL role to use.

setDialect

void setDialect(int dialect)

Set the database dialect to use when creating a new database.

Parameters:

dialect - Database dialect (1 or 3)

Throws:

java.lang.IllegalArgumentException - if value is not 1 or 3

See Also:

getDialect()

getDialect

int getDialect()

Returns:

Database dialect (either 1 or 3), default is 3.

setPageSize

void setPageSize(int pageSize)

Set the page size to use when creating a new database.

The value for pageSize must be one of PageSizeConstants. The default value depends on the Firebird version.

Some values are not valid on all Firebird versions.

Parameters:

pageSize - The page size to be used in the created database, see PageSizeConstants

See Also:

PageSizeConstants

getPageSize

int getPageSize()

Returns:

The page size to be used when creating a database, or -1 if the database default is used.

setDefaultCharacterSet

void setDefaultCharacterSet(java.lang.String firebirdCharsetName)

Set the default database character set to use when creating a new database.

Parameters:

firebirdCharsetName - Character set name, use Firebird names only; null will use Firebird default (NONE). Specifying an invalid name will result in an exception during database creation.

getDefaultCharacterSet

java.lang.String getDefaultCharacterSet()

Returns:

The default character set name, null means not set.

See Also:

setDefaultCharacterSet(String)

setForceWrite

void setForceWrite(java.lang.Boolean forceWrite)

Control force write behaviour of the created database.

Only use this method if you know what you're doing, and if you can live with data loss and database corruption. In general it is advisable to use the Firebird default (null for this method).

Parameters:

forceWrite - null - default behaviour (force write enabled after database creation and initialization), true - enable force write at database creation, false - disable force write

getForceWrite

java.lang.Boolean getForceWrite()

Returns:

The forced writes configuration

See Also:

setForceWrite(Boolean)

isCreateOnStart

boolean isCreateOnStart()

Get if the database will be created when calling start().

Returns:

true when the database will be created on start, false otherwise.

setCreateOnStart

void setCreateOnStart(boolean createOnStart)

Set if the database will be created when calling start().

Parameters:

createOnStart - true to create the database on start, false to not create on start (default)

isDropOnStop

boolean isDropOnStop()

Get if the database will be created when calling stop().

Returns:

true to drop the database on stop, false otherwise

setDropOnStop

void setDropOnStop(boolean dropOnStop)

Set if the database will be created when calling stop().

Parameters:

dropOnStop - true to drop the database on stop, false to not drop on stop (default)

isForceCreate

boolean isForceCreate()

Get if the database will be dropped if exists when creating a database.

Returns:

true to drop existing database on create, false to not create a database if it exists.

setForceCreate

void setForceCreate(boolean forceCreate)

Set if the database will be dropped if exists when creating a database.

Parameters:

forceCreate - true to drop existing database on create, false to not create a database if it exists.

createDatabase

void createDatabase(java.lang.String fileName,
                    java.lang.String user,
                    java.lang.String password)
             throws java.lang.Exception

Create a database with the specified file name, username and password on the specified server and port.

On creation, the following properties will used to configure the database: dialect, pageSize, defaultCharacterSet.

If the database already exists, and forceCreate is true, the database will be dropped. If false, no database will be created.

Parameters:

fileName - Database file name or alias

user - User name

password - Password

Throws:

java.lang.IllegalStateException - If this manager is not started

java.lang.Exception - If database creation fails.

createDatabase

void createDatabase(java.lang.String fileName,
                    java.lang.String user,
                    java.lang.String password,
                    java.lang.String roleName)
             throws java.lang.Exception

Create a database with the specified file name, username, password and role on the specified server and port.

On creation, the following properties will used to configure the database: dialect, pageSize, defaultCharacterSet.

If the database already exists, and forceCreate is true, the database will be dropped. If false, no database will be created.

Parameters:

fileName - Database file name or alias

user - User name

password - Password

roleName - Role name (or null for no role)

Throws:

java.lang.IllegalStateException - If this manager is not started

java.lang.Exception - If database creation fails.

dropDatabase

void dropDatabase(java.lang.String fileName,
                  java.lang.String user,
                  java.lang.String password)
           throws java.lang.Exception

Drop a database with the specified file name, username and password on the specified server and port.

Parameters:

fileName - Database file name or alias

user - User name

password - Password

Throws:

java.lang.Exception - If this manager is not started or database drop fails.

dropDatabase

void dropDatabase(java.lang.String fileName,
                  java.lang.String user,
                  java.lang.String password,
                  java.lang.String roleName)
           throws java.lang.Exception

Drop a database with the specified file name, username, password and role on the specified server and port.

Parameters:

fileName - Database file name or alias

user - User name

password - Password

roleName - Role name (or null for no role)

Throws:

java.lang.Exception - If this manager is not started or database drop fails.

isDatabaseExists

boolean isDatabaseExists(java.lang.String fileName,
                         java.lang.String user,
                         java.lang.String password)
                  throws java.lang.Exception

Check if a database exists with the specified file name, username and password on the specified server and port.

Existence is checked by connecting to the database, so any connection error, including invalid credentials, will report the database as not existing.

Parameters:

fileName - Database file name or alias

user - User name

password - Password

Returns:

true if the database exists and can be connected, false if the database does not exist or any other error occurred.

Throws:

java.lang.Exception - Currently no other exception is thrown, this may change in the future