Package org.firebirdsql.management

## Class FBManager

- java.lang.Object
- - org.firebirdsql.management.FBManager

- All Implemented Interfaces:
    `java.lang.AutoCloseable`, `FBManagerMBean`

      public class FBManager
      extends java.lang.Object
      implements FBManagerMBean

  A tool for creating and dropping databases.

  In particular, they can be created and dropped using the jboss service lifecycle operations start and stop.

  See `FBManagerMBean` for documentation.

  Author:
    David Jencks

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `FBManager()` |
    `FBManager​(java.lang.String type)` |
    `FBManager​(GDSType type)` |

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `close()` | Alias for `FBManagerMBean.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 `FBManagerMBean.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 `FBManagerMBean.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 `FBManagerMBean.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 `FBManagerMBean.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.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### FBManager

          public FBManager()

    - #### FBManager

          public FBManager​(GDSType type)

    - #### FBManager

          public FBManager​(java.lang.String type)

  - ### Method Detail

    - #### start

          public void start()
                     throws java.lang.Exception

      Description copied from interface: `FBManagerMBean`
      Start this manager.

      If `FBManagerMBean.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 `FBManagerMBean.isForceCreate()` is `true`. When `forceCreate` is `true` an attempt will be made to drop the database.

      Specified by:
        `start` in interface `FBManagerMBean`
      Throws:
        `java.lang.IllegalStateException` - If this manager is not started
        `java.lang.Exception` - For failures to start or create the database

    - #### stop

          public void stop()
                    throws java.lang.Exception

      Description copied from interface: `FBManagerMBean`
      Stop this manager.

      If `FBManagerMBean.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.

      Specified by:
        `stop` in interface `FBManagerMBean`
      Throws:
        `java.lang.Exception` - For failures to drop the database.

    - #### close

          public void close()
                     throws java.lang.Exception

      Description copied from interface: `FBManagerMBean`
      Alias for `FBManagerMBean.stop()`
      Specified by:
        `close` in interface `java.lang.AutoCloseable`
      Specified by:
        `close` in interface `FBManagerMBean`
      Throws:
        `java.lang.Exception`

    - #### getState

          public java.lang.String getState()

      Specified by:
        `getState` in interface `FBManagerMBean`
      Returns:
        Current state (`"Stopped"` or `"Started"`

    - #### getName

          public java.lang.String getName()

      Specified by:
        `getName` in interface `FBManagerMBean`
      Returns:
        Descriptive name of this manager

    - #### setServer

          public void setServer​(java.lang.String host)

      Description copied from interface: `FBManagerMBean`
      Set the host name of the Firebird server.
      Specified by:
        `setServer` in interface `FBManagerMBean`
      Parameters:
        `host` - Hostname

    - #### getServer

          public java.lang.String getServer()

      Specified by:
        `getServer` in interface `FBManagerMBean`
      Returns:
        The host name of the Firebird server (default is `"localhost"`)

    - #### setPort

          public void setPort​(int port)

      Description copied from interface: `FBManagerMBean`
      Set the port of the Firebird server.
      Specified by:
        `setPort` in interface `FBManagerMBean`
      Parameters:
        `port` - Port of the Firebird server

    - #### getPort

          public int getPort()

      Specified by:
        `getPort` in interface `FBManagerMBean`
      Returns:
        The port of the Firebird server (default is `3050`)

    - #### getFileName

          public java.lang.String getFileName()

      Specified by:
        `getFileName` in interface `FBManagerMBean`
      Returns:
        File name or alias of the database

    - #### setFileName

          public void setFileName​(java.lang.String fileName)

      Description copied from interface: `FBManagerMBean`
      Set the file name or alias of the database.
      Specified by:
        `setFileName` in interface `FBManagerMBean`
      Parameters:
        `fileName` - File name or alias of the database

    - #### getType

          public java.lang.String getType()

      Specified by:
        `getType` in interface `FBManagerMBean`
      Returns:
        GDS plugin type name (default is `GDSFactory.getDefaultGDSType()`)

    - #### setType

          public void setType​(java.lang.String type)

      Description copied from interface: `FBManagerMBean`
      Set the GDS plugin type to use.
      Specified by:
        `setType` in interface `FBManagerMBean`
      Parameters:
        `type` - GDS plugin type name (`PURE_JAVA`, `NATIVE`, `EMBEDDED`)

    - #### getUserName

          public java.lang.String getUserName()

      Specified by:
        `getUserName` in interface `FBManagerMBean`
      Returns:
        User name

    - #### setUserName

          public void setUserName​(java.lang.String userName)

      Description copied from interface: `FBManagerMBean`
      Set the username.
      Specified by:
        `setUserName` in interface `FBManagerMBean`
      Parameters:
        `userName` - Username

    - #### getPassword

          public java.lang.String getPassword()

      Specified by:
        `getPassword` in interface `FBManagerMBean`
      Returns:
        password

    - #### setPassword

          public void setPassword​(java.lang.String password)

      Description copied from interface: `FBManagerMBean`
      Set the password.
      Specified by:
        `setPassword` in interface `FBManagerMBean`
      Parameters:
        `password` - Password

    - #### getRoleName

          public java.lang.String getRoleName()

      Specified by:
        `getRoleName` in interface `FBManagerMBean`
      Returns:
        SQL role to use.

    - #### setRoleName

          public void setRoleName​(java.lang.String roleName)

      Specified by:
        `setRoleName` in interface `FBManagerMBean`
      Parameters:
        `roleName` - SQL role to use.

    - #### setDialect

          public void setDialect​(int dialect)

      Description copied from interface: `FBManagerMBean`
      Set the database dialect to use when creating a new database.
      Specified by:
        `setDialect` in interface `FBManagerMBean`
      Parameters:
        `dialect` - Database dialect (1 or 3)
      See Also:
        `FBManagerMBean.getDialect()`

    - #### getDialect

          public int getDialect()

      Specified by:
        `getDialect` in interface `FBManagerMBean`
      Returns:
        Database dialect (either 1 or 3), default is 3.

    - #### setPageSize

          public void setPageSize​(int pageSize)

      Description copied from interface: `FBManagerMBean`
      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.

      Specified by:
        `setPageSize` in interface `FBManagerMBean`
      Parameters:
        `pageSize` - The page size to be used in the created database, see `PageSizeConstants`
      See Also:
        `PageSizeConstants`

    - #### getPageSize

          public int getPageSize()

      Specified by:
        `getPageSize` in interface `FBManagerMBean`
      Returns:
        The page size to be used when creating a database, or `-1` if the database default is used.

    - #### setDefaultCharacterSet

          public void setDefaultCharacterSet​(java.lang.String firebirdCharsetName)

      Description copied from interface: `FBManagerMBean`
      Set the default database character set to use when creating a new database.
      Specified by:
        `setDefaultCharacterSet` in interface `FBManagerMBean`
      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

          public java.lang.String getDefaultCharacterSet()

      Specified by:
        `getDefaultCharacterSet` in interface `FBManagerMBean`
      Returns:
        The default character set name, `null` means not set.
      See Also:
        `FBManagerMBean.setDefaultCharacterSet(String)`

    - #### setForceWrite

          public void setForceWrite​(java.lang.Boolean forceWrite)

      Description copied from interface: `FBManagerMBean`
      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).

      Specified by:
        `setForceWrite` in interface `FBManagerMBean`
      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

          public java.lang.Boolean getForceWrite()

      Specified by:
        `getForceWrite` in interface `FBManagerMBean`
      Returns:
        The forced writes configuration
      See Also:
        `FBManagerMBean.setForceWrite(Boolean)`

    - #### isCreateOnStart

          public boolean isCreateOnStart()

      Description copied from interface: `FBManagerMBean`
      Get if the database will be created when calling `FBManagerMBean.start()`.
      Specified by:
        `isCreateOnStart` in interface `FBManagerMBean`
      Returns:
        `true` when the database will be created on start, `false` otherwise.

    - #### setCreateOnStart

          public void setCreateOnStart​(boolean createOnStart)

      Description copied from interface: `FBManagerMBean`
      Set if the database will be created when calling `FBManagerMBean.start()`.
      Specified by:
        `setCreateOnStart` in interface `FBManagerMBean`
      Parameters:
        `createOnStart` - `true` to create the database on start, `false` to not create on start (default)

    - #### isDropOnStop

          public boolean isDropOnStop()

      Description copied from interface: `FBManagerMBean`
      Get if the database will be created when calling `FBManagerMBean.stop()`.
      Specified by:
        `isDropOnStop` in interface `FBManagerMBean`
      Returns:
        `true` to drop the database on stop, `false` otherwise

    - #### setDropOnStop

          public void setDropOnStop​(boolean dropOnStop)

      Description copied from interface: `FBManagerMBean`
      Set if the database will be created when calling `FBManagerMBean.stop()`.
      Specified by:
        `setDropOnStop` in interface `FBManagerMBean`
      Parameters:
        `dropOnStop` - `true` to drop the database on stop, `false` to not drop on stop (default)

    - #### isForceCreate

          public boolean isForceCreate()

      Description copied from interface: `FBManagerMBean`
      Get if the database will be dropped if exists when creating a database.
      Specified by:
        `isForceCreate` in interface `FBManagerMBean`
      Returns:
        `true` to drop existing database on create, `false` to not create a database if it exists.

    - #### setForceCreate

          public void setForceCreate​(boolean forceCreate)

      Description copied from interface: `FBManagerMBean`
      Set if the database will be dropped if exists when creating a database.
      Specified by:
        `setForceCreate` in interface `FBManagerMBean`
      Parameters:
        `forceCreate` - `true` to drop existing database on create, `false` to not create a database if it exists.

    - #### createDatabase

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

      Description copied from interface: `FBManagerMBean`
      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.

      Specified by:
        `createDatabase` in interface `FBManagerMBean`
      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

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

      Description copied from interface: `FBManagerMBean`
      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.

      Specified by:
        `createDatabase` in interface `FBManagerMBean`
      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

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

      Description copied from interface: `FBManagerMBean`
      Drop a database with the specified file name, username and password on the specified `server` and `port`.
      Specified by:
        `dropDatabase` in interface `FBManagerMBean`
      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

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

      Description copied from interface: `FBManagerMBean`
      Drop a database with the specified file name, username, password and role on the specified `server` and `port`.
      Specified by:
        `dropDatabase` in interface `FBManagerMBean`
      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

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

      Description copied from interface: `FBManagerMBean`
      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.

      Specified by:
        `isDatabaseExists` in interface `FBManagerMBean`
      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