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

Version:
  1.0
Author:
  David Jencks

### Method Summary

Methods
`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, user name and password 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, user name and password on the specified `server` and `port`.
`java.lang.String` `getDefaultCharacterSet()`
`int` `getDialect()`
`java.lang.String` `getFileName()`
`java.lang.String` `getName()`
`int` `getPageSize()`
`java.lang.String` `getPassword()`
`int` `getPort()`
`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, user name 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 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 be dropped if exists when creating a 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` `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 user name.
`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`, `LOCAL`)

#### getUserName

    java.lang.String getUserName()

Returns:
  User name

#### setUserName

    void setUserName(java.lang.String userName)

Set the user name.

Parameters:
  `userName` - User name

#### getPassword

    java.lang.String getPassword()

Returns:
  password

#### setPassword

    void setPassword(java.lang.String password)

Set the password.

Parameters:
  `password` - Password

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

#### 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 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 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, user name 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.

#### 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, user name 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.

#### 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, user name 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