Module org.firebirdsql.jaybird
Package org.firebirdsql.management

Interface FBManagerMBean

All Superinterfaces:
AutoCloseable
All Known Implementing Classes:
FBManager
public interface FBManagerMBean extends 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 Details

    • start

      void start() throws 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:
      IllegalStateException - If this manager is not started
      Exception - For failures to start or create the database

    • stop

      void stop() throws 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:
      Exception - For failures to drop the database.

    • close

      void close() throws Exception
      Alias for stop()
      Specified by:
      close in interface AutoCloseable
      Throws:
      Exception

    • getName

      String getName()
      Returns:
      Descriptive name of this manager

    • getState

      String getState()
      Returns:
      Current state ("Stopped" or "Started"

    • setServer

      void setServer(String host)
      Set the host name of the Firebird server.
      Parameters:
      host - Hostname

    • getServer

      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

      String getFileName()
      Returns:
      File name or alias of the database

    • setFileName

      void setFileName(String fileName)
      Set the file name or alias of the database.
      Parameters:
      fileName - File name or alias of the database

    • getType

      String getType()
      Returns:
      GDS plugin type name (default is GDSFactory.getDefaultGDSType())

    • setType

      void setType(String type)
      Set the GDS plugin type to use.
      Parameters:
      type - GDS plugin type name (PURE_JAVA, NATIVE, EMBEDDED)

    • getUserName

      String getUserName()
      Returns:
      User name

    • setUserName

      void setUserName(String userName)
      Set the username.
      Parameters:
      userName - Username

    • getPassword

      String getPassword()
      Returns:
      password

    • setPassword

      void setPassword(String password)
      Set the password.
      Parameters:
      password - Password

    • getRoleName

      String getRoleName()
      Returns:
      SQL role to use.

    • setRoleName

      void setRoleName(String roleName)
      Parameters:
      roleName - SQL role to use.

    • getEnableProtocol

      String getEnableProtocol()
      Returns:
      enable protocol value (see also AttachmentProperties.getEnableProtocol().
      Since:
      6

    • setEnableProtocol

      void setEnableProtocol(String enableProtocol)
      Sets the enable protocol value.
      Parameters:
      enableProtocol - enable protocol value
      Since:
      6

    • setDialect

      void setDialect(int dialect)
      Set the database dialect to use when creating a new database.
      Parameters:
      dialect - Database dialect (1 or 3)
      Throws:
      IllegalArgumentException - if value is not 1 or 3
      See Also:

    • 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:

    • 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(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

      String getDefaultCharacterSet()
      Returns:
      The default character set name, null means not set.
      See Also:

    • setForceWrite

      void setForceWrite(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

      Boolean getForceWrite()
      Returns:
      The forced writes configuration
      See Also:

    • 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(String fileName, String user, String password) throws 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:
      IllegalStateException - If this manager is not started
      Exception - If database creation fails.

    • createDatabase

      void createDatabase(String fileName, String user, String password, String roleName) throws 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:
      IllegalStateException - If this manager is not started
      Exception - If database creation fails.

    • dropDatabase

      void dropDatabase(String fileName, String user, String password) throws 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:
      Exception - If this manager is not started or database drop fails.

    • dropDatabase

      void dropDatabase(String fileName, String user, String password, String roleName) throws 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:
      Exception - If this manager is not started or database drop fails.

    • isDatabaseExists

      boolean isDatabaseExists(String fileName, String user, String password) throws 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:
      Exception - Currently no other exception is thrown, this may change in the future