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

Class FBManager

java.lang.Object
org.firebirdsql.management.FBManager
All Implemented Interfaces:
AutoCloseable, AttachmentProperties, BaseProperties, FBManagerMBean
public class FBManager extends 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 Details

    • FBManager

      public FBManager()

    • FBManager

      public FBManager(GDSType type)

    • FBManager

      public FBManager(String type)

  • Method Details

    • start

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

    • stop

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

    • close

      public void close() throws Exception
      Description copied from interface: FBManagerMBean
      Alias for FBManagerMBean.stop()
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface FBManagerMBean
      Throws:
      Exception

    • getState

      public String getState()
      Specified by:
      getState in interface FBManagerMBean
      Returns:
      Current state ("Stopped" or "Started"

    • getName

      public String getName()
      Specified by:
      getName in interface FBManagerMBean
      Returns:
      Descriptive name of this manager

    • setServerName

      public void setServerName(String serverName)
      Description copied from interface: AttachmentProperties
      Set the hostname or IP address of the Firebird server.

      When set to null (the default), the databaseName or serviceName is used as the full identification of the database host, port and database path/alias. Protocol implementations, for example PURE_JAVA, may default to localhost when this property is null, but databaseName/serviceName does not (seem to) contain a host name.

      Specified by:
      setServerName in interface AttachmentProperties
      Parameters:
      serverName - Hostname or IP address of the server

    • getServerName

      public String getServerName()
      Description copied from interface: AttachmentProperties
      Get the hostname or IP address of the Firebird server.
      Specified by:
      getServerName in interface AttachmentProperties
      Returns:
      Hostname or IP address of the server
      See Also:

    • setServer

      public void setServer(String host)
      Description copied from interface: FBManagerMBean
      Set the hostname of the Firebird server.
      Specified by:
      setServer in interface FBManagerMBean
      Parameters:
      host - hostname
      See Also:

    • getServer

      public String getServer()
      Specified by:
      getServer in interface FBManagerMBean
      Returns:
      hostname of the Firebird server (default is "localhost")
      See Also:

    • setPortNumber

      public void setPortNumber(int portNumber)
      Description copied from interface: AttachmentProperties
      Set the port number of the server.

      Defaults to 3050. This property value will be ignored if serverName is null, unless the protocol implementation needs a hostname, but cannot find a hostname in databaseName/serviceName.

      Specified by:
      setPortNumber in interface AttachmentProperties
      Parameters:
      portNumber - Port number of the server
      See Also:

    • getPortNumber

      public int getPortNumber()
      Description copied from interface: AttachmentProperties
      Get the port number of the server.
      Specified by:
      getPortNumber in interface AttachmentProperties
      Returns:
      Port number of the server
      See Also:

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

    • getPort

      public int getPort()
      Specified by:
      getPort in interface FBManagerMBean
      Returns:
      port of the Firebird server (default is 3050)
      See Also:

    • getFileName

      public String getFileName()
      Specified by:
      getFileName in interface FBManagerMBean
      Returns:
      File name or alias of the database

    • setFileName

      public void setFileName(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 String getType()
      Specified by:
      getType in interface AttachmentProperties
      Returns:
      type of the connection, for example, "PURE_JAVA", "NATIVE", "EMBEDDED", depends on the GDS implementations installed in the system.

    • setType

      public void setType(String type)
      Specified by:
      setType in interface AttachmentProperties
      Parameters:
      type - type of the connection, for example, "PURE_JAVA", "NATIVE", "EMBEDDED", depends on the GDS implementations installed in the system.

    • getUser

      public String getUser()
      Specified by:
      getUser in interface AttachmentProperties
      Returns:
      Name of the user to authenticate to the server.

    • setUser

      public void setUser(String user)
      Specified by:
      setUser in interface AttachmentProperties
      Parameters:
      user - Name of the user to authenticate to the server.

    • getUserName

      public String getUserName()
      Specified by:
      getUserName in interface FBManagerMBean
      Returns:
      username
      See Also:

    • setUserName

      public void setUserName(String userName)
      Description copied from interface: FBManagerMBean
      Set the username.
      Specified by:
      setUserName in interface FBManagerMBean
      Parameters:
      userName - username
      See Also:

    • getPassword

      public String getPassword()
      Specified by:
      getPassword in interface AttachmentProperties
      Returns:
      Password to authenticate to the server.

    • setPassword

      public void setPassword(String password)
      Specified by:
      setPassword in interface AttachmentProperties
      Parameters:
      password - Password to authenticate to the server.

    • getRoleName

      public String getRoleName()
      Specified by:
      getRoleName in interface AttachmentProperties
      Returns:
      SQL role to use.

    • setRoleName

      public void setRoleName(String roleName)
      Specified by:
      setRoleName in interface AttachmentProperties
      Parameters:
      roleName - SQL role to use.

    • getAuthPlugins

      public String getAuthPlugins()
      Description copied from interface: AttachmentProperties
      Get the list of authentication plugins to try.
      Specified by:
      getAuthPlugins in interface AttachmentProperties
      Returns:
      comma-separated list of authentication plugins

    • setAuthPlugins

      public void setAuthPlugins(String authPlugins)
      Description copied from interface: AttachmentProperties
      Sets the authentication plugins to try.

      Invalid names are skipped during authentication.

      Specified by:
      setAuthPlugins in interface AttachmentProperties
      Parameters:
      authPlugins - comma-separated list of authentication plugins

    • setEnableProtocol

      public void setEnableProtocol(String enableProtocol)
      Description copied from interface: AttachmentProperties
      Comma-separated list of additionally enabled protocols.
      Specified by:
      setEnableProtocol in interface AttachmentProperties
      Parameters:
      enableProtocol - List of unsupported protocol versions to try in addition to the supported protocols.
      See Also:

    • getEnableProtocol

      public String getEnableProtocol()
      Description copied from interface: AttachmentProperties
      Comma-separated list of additionally enabled protocols.

      By default, pure Java connections of Jaybird only supports the protocol versions of supported Firebird versions. This property lists the additionally enabled unsupported protocol versions. If Jaybird does not have a listed protocol, it is silently ignored.

      This property is ignored for native connections.

      Specified by:
      getEnableProtocol in interface AttachmentProperties
      Returns:
      List of unsupported protocol versions to try in addition to the supported protocols. Comma-separated using only the version number (e.g. "10,11"). Both the unmasked and masked version are supported (e.g. 32780 for protocol 12), but we recommend to use the unmasked version. The value "*" will try all available protocols.

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

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

    • 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(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 String getDefaultCharacterSet()
      Specified by:
      getDefaultCharacterSet in interface FBManagerMBean
      Returns:
      The default character set name, null means not set.
      See Also:

    • setForceWrite

      public void setForceWrite(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 Boolean getForceWrite()
      Specified by:
      getForceWrite in interface FBManagerMBean
      Returns:
      The forced writes configuration
      See Also:

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

    • createDatabase

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

    • dropDatabase

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

    • dropDatabase

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

    • isDatabaseExists

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

    • getProperty

      public final String getProperty(String name)
      Description copied from interface: BaseProperties
      Retrieves a string property value by name.

      For properties with an explicit default, this method should return the string presentation of that default, not null. For int or boolean the string equivalent is returned.

      Specified by:
      getProperty in interface BaseProperties
      Parameters:
      name - Property name (not null or empty)
      Returns:
      Value of the property, or null when not set or not a known property

    • setProperty

      public final void setProperty(String name, String value)
      Description copied from interface: BaseProperties
      Sets a property by name.

      This method can be used to set all defined properties, but also properties not known by Jaybird. When setting int or boolean properties, the appropriate conversions are applied. Using null will reset to the default value. For boolean properties, an empty string is taken to mean true.

      Specified by:
      setProperty in interface BaseProperties
      Parameters:
      name - Property name (not null or empty)
      value - Property value (use null to apply default)

    • getIntProperty

      public final Integer getIntProperty(String name)
      Description copied from interface: BaseProperties
      Retrieves an int property value by name.

      For properties with an explicit default, this method should return the integer presentation of that default. For implementation simplicity, it is allowed to convert any string property to int instead of checking if something is actually an int property

      Specified by:
      getIntProperty in interface BaseProperties
      Parameters:
      name - Property name (not null or empty)
      Returns:
      Integer with value of the property, or null when not set

    • setIntProperty

      public final void setIntProperty(String name, Integer value)
      Description copied from interface: BaseProperties
      Sets an int property by name.

      For implementation simplicity, it is allowed to also set string properties. The value set will be the string equivalent.

      Specified by:
      setIntProperty in interface BaseProperties
      Parameters:
      name - Property name (not null or empty)
      value - Property value (use null to apply default)

    • getBooleanProperty

      public final Boolean getBooleanProperty(String name)
      Description copied from interface: BaseProperties
      Retrieves a boolean property value by name.

      For properties with an explicit default, this method should return the boolean presentation of that default. For implementation simplicity, it is allowed to convert any string property to boolean instead of checking if something is actually a boolean property

      Specified by:
      getBooleanProperty in interface BaseProperties
      Parameters:
      name - Property name (not null or empty)
      Returns:
      Integer with value of the property, or null when not set

    • setBooleanProperty

      public final void setBooleanProperty(String name, Boolean value)
      Description copied from interface: BaseProperties
      Sets a boolean property by name.

      For implementation simplicity, it is allowed to also set string properties. The value set will be the string equivalent.

      Specified by:
      setBooleanProperty in interface BaseProperties
      Parameters:
      name - Property name (not null or empty)
      value - Property value (use null to apply default)

    • connectionPropertyValues

      public final Map<ConnectionProperty,Object> connectionPropertyValues()
      Description copied from interface: BaseProperties
      An unmodifiable view on the connection properties held by this BaseProperties implementation.

      Be aware, implementations can have additional properties that are not mapped from ConnectionProperty. Such properties will need to be retrieved in an implementation-specific manner.

      Specified by:
      connectionPropertyValues in interface BaseProperties
      Returns:
      An unmodifiable view on the property values held in this properties instance