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

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