edu.ucsb.nceas.metacat.admin

## Class DBAdmin

- java.lang.Object
- - edu.ucsb.nceas.metacat.admin.MetacatAdmin
  - - edu.ucsb.nceas.metacat.admin.DBAdmin

-     public class DBAdmin
      extends MetacatAdmin

  Control the display of the database configuration page and the processing of the configuration values.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `DB_DOES_NOT_EXIST`
    `static int` | `TABLES_DO_NOT_EXIST`
    `static int` | `TABLES_EXIST`
    `static int` | `VERSION_ACTIVE`
    `static int` | `VERSION_INACTIVE`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `configureDatabase(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)` Handle configuration of the database the first time that Metacat starts or when it is explicitly called.
    `int` | `getDBStatus()` Performs a status check on the database.
    `DBVersion` | `getDBVersion()` Get the version of the database as a string
    `static DBAdmin` | `getInstance()` Get the single instance of DBAdmin.
    `DBVersion` | `getUnRegisteredDBVersion()` Finds the version of the database for a database that does not have a dbVersion table yet.
    `java.util.Vector<java.lang.String>` | `getUpdateClasses()`
    `java.util.Vector<java.lang.String>` | `getUpdateScripts()` Creates a list of database update script names by looking at the database version and the metacat version and then getting any script that is inbetween the two (inclusive of metacat version).
    `java.util.Vector<java.lang.String>` | `loadSQLFromFile(java.lang.String sqlFileName)` Very basic utility to read sql from a file and return a vector of the individual sql statements.
    `void` | `runSQLFile(java.lang.String sqlFileName)` Runs the commands in a sql script.
    `void` | `updateDBVersion()` Updates the version of the database.
    `void` | `upgradeDatabase()` Iterates through the list of scripts that need to be run to upgrade the database and calls runSQLFile on each.
    `java.lang.String` | `validateDBConnectivity(java.lang.String dbDriver, java.lang.String connection, java.lang.String user, java.lang.String password)` Validate connectivity to the database.
    `protected java.util.Vector<java.lang.String>` | `validateOptions(javax.servlet.http.HttpServletRequest request)` Validate the most important configuration options submitted by the user.

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

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

- - ### Field Detail

    - #### DB_DOES_NOT_EXIST

          public static final int DB_DOES_NOT_EXIST

      See Also:
        Constant Field Values

    - #### TABLES_DO_NOT_EXIST

          public static final int TABLES_DO_NOT_EXIST

      See Also:
        Constant Field Values

    - #### TABLES_EXIST

          public static final int TABLES_EXIST

      See Also:
        Constant Field Values

    - #### VERSION_INACTIVE

          public static final int VERSION_INACTIVE

      See Also:
        Constant Field Values

    - #### VERSION_ACTIVE

          public static final int VERSION_ACTIVE

      See Also:
        Constant Field Values

  - ### Method Detail

    - #### getInstance

          public static DBAdmin getInstance()
                                     throws AdminException

      Get the single instance of DBAdmin.
      Returns:
        the single instance of DBAdmin
      Throws:
        `AdminException`

    - #### configureDatabase

          public void configureDatabase(javax.servlet.http.HttpServletRequest request,
                                        javax.servlet.http.HttpServletResponse response)
                                 throws AdminException

      Handle configuration of the database the first time that Metacat starts or when it is explicitly called. Collect necessary update information from the administrator.
      Parameters:
        `request` - the http request information
        `response` - the http response to be sent back to the client
      Throws:
        `AdminException`

    - #### getDBStatus

          public int getDBStatus()
                          throws java.sql.SQLException,
                                 edu.ucsb.nceas.utilities.PropertyNotFoundException

      Performs a status check on the database.
      Throws:
        `java.sql.SQLException`
        `edu.ucsb.nceas.utilities.PropertyNotFoundException`

    - #### getDBVersion

          public DBVersion getDBVersion()
                                 throws AdminException

      Get the version of the database as a string
      Throws:
        `AdminException`

    - #### getUnRegisteredDBVersion

          public DBVersion getUnRegisteredDBVersion()
                                             throws AdminException,
                                                    java.sql.SQLException

      Finds the version of the database for a database that does not have a dbVersion table yet. Work backwards with various clues found in update scripts to find the version.
      Throws:
        `AdminException`
        `java.sql.SQLException`

    - #### updateDBVersion

          public void updateDBVersion()
                               throws java.sql.SQLException

      Updates the version of the database. Typically this is done in the update scripts that get run when we upgrade the application. This method can be used if you are automating a patch on the database internally.
      Throws:
        `java.sql.SQLException`

    - #### validateDBConnectivity

          public java.lang.String validateDBConnectivity(java.lang.String dbDriver,
                                                         java.lang.String connection,
                                                         java.lang.String user,
                                                         java.lang.String password)

      Validate connectivity to the database. Validation methods return a string error message if there is an issue. This allows the calling code to run several validations and compile the errors into a list that can be displayed on a web page if desired.
      Parameters:
        `dbDriver` - the database driver
        `connection` - the jdbc connection string
        `user` - the user name
        `password` - the login password
      Returns:
        a string holding error message if validation fails.

    - #### getUpdateScripts

          public java.util.Vector<java.lang.String> getUpdateScripts()
                                                              throws AdminException

      Creates a list of database update script names by looking at the database version and the metacat version and then getting any script that is inbetween the two (inclusive of metacat version).
      Throws:
        `AdminException`

    - #### getUpdateClasses

          public java.util.Vector<java.lang.String> getUpdateClasses()
                                                              throws AdminException

      Throws:
        `AdminException`

    - #### upgradeDatabase

          public void upgradeDatabase()
                               throws AdminException

      Iterates through the list of scripts that need to be run to upgrade the database and calls runSQLFile on each.
      Throws:
        `AdminException`

    - #### runSQLFile

          public void runSQLFile(java.lang.String sqlFileName)
                          throws AdminException,
                                 java.sql.SQLException

      Runs the commands in a sql script. Individual commands are loaded into a string vector and run one at a time.
      Parameters:
        `sqlFileName` - the name of the file holding the sql statements that need to get run.
      Throws:
        `AdminException`
        `java.sql.SQLException`

    - #### loadSQLFromFile

          public java.util.Vector<java.lang.String> loadSQLFromFile(java.lang.String sqlFileName)
                                                             throws java.io.IOException

      Very basic utility to read sql from a file and return a vector of the individual sql statements. This ignores any line that starts with /* or *. It strips anything following --. Sql is parsed by looking for lines that start with one of the following identifiers: INSERT, UPDATE, ALTER, CREATE, DROP, BEGIN and COMMIT. It then assumes that everything until the line that ends with ; is part of the sql, excluding comments.
      Parameters:
        `sqlFileName` - the name of the file to read.
      Returns:
        a vector holding the individual sql statements.
      Throws:
        `java.io.IOException`

    - #### validateOptions

          protected java.util.Vector<java.lang.String> validateOptions(javax.servlet.http.HttpServletRequest request)

      Validate the most important configuration options submitted by the user.
      Specified by:
        `validateOptions` in class `MetacatAdmin`
      Returns:
        a vector holding error message for any fields that fail validation.

Copyright © 2020 Regents of the University of California. All Rights Reserved.