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

      All Methods Instance Methods Abstract Methods 
      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

      • 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