Package org.apache.empire.db

Class DBDatabase

java.lang.Object
org.apache.empire.db.DBObject
org.apache.empire.db.DBDatabase
Direct Known Subclasses:
OracleSYSDatabase, TDatabase
public abstract class DBDatabase extends DBObject
This abstract class is the applicaton's interface for a particular database schema.

It provides access to the various database objects such as tables, views and relations.

It also provides methods to execute DQL and DML SQL-commands.

  • Field Details

    • SYSDATE

      public static final DBDatabase.DBSystemDate SYSDATE

    • EMPTY_STRING

      public static final String EMPTY_STRING
      See Also:

    • tables

      protected final List<DBTable> tables

    • relations

      protected final List<DBRelation> relations

    • views

      protected final List<DBView> views

    • rowsetAliasMap

      protected final Map<String,DBRowSet> rowsetAliasMap

    • dbms

      protected DBMSHandler dbms

    • legacyDate

      protected boolean legacyDate
      Flag indicating whether Bean getters / setters use java.util.Date or Java types (LocalDate, LocalDateTime) True (default) when java.util.Date is used

  • Constructor Details

    • DBDatabase

      public DBDatabase(String schema, String linkName)
      Constructs a new DBDatabase object and sets the specified schema object.
      Parameters:
      schema - the database schema
      linkName - the database link name

    • DBDatabase

      public DBDatabase(String schema)
      Constructs a new DBDatabase object and sets the specified schema object.
      Parameters:
      schema - the database schema

    • DBDatabase

      public DBDatabase()
      Constructs a new DBDatabase object set the variable 'schema' = null.

  • Method Details

    • findByIdentifier

      public static DBDatabase findByIdentifier(String dbIdent)
      find a database by id
      Parameters:
      dbIdent - the database id to look for
      Returns:
      the database or null if not found

    • findByClass

      public static DBDatabase findByClass(Class<? extends DBDatabase> clazz)
      find a database by its Java type
      Parameters:
      clazz - the database class to look for
      Returns:
      the database or null if not found

    • discard

      public void discard()
      Frees all resources and unregisters database in global map. Do not reuse this object afterwards! Hint: Database must be closed!

    • register

      protected void register(String dbid)
      registers the database in the global list of databases
      Parameters:
      dbid - the database id

    • getDefaultIdentifier

      protected String getDefaultIdentifier()
      returns the default database identifier Override this to customize
      Returns:
      the defaultId

    • getIdentifier

      public String getIdentifier()
      Returns the database instance identifier
      Returns:
      the identifier of the database

    • getDbms

      public <T extends DBMSHandler> T getDbms()
      Returns the DBMS Handler for this database.
      Type Parameters:
      T - the DBMSHandler type
      Returns:
      returns the DBMS Handler for this database

    • isPreparedStatementsEnabled

      public boolean isPreparedStatementsEnabled()
      Returns whether Prepared Statements are enabled for the read and update operations in DBRecord. Note: This will not affect statements generated via DBContext.createCommand() However statement parameters can always be manually declared using cmd.addCmdParam();
      Returns:
      true if prepared Statements are enabled or false if not

    • setPreparedStatementsEnabled

      public void setPreparedStatementsEnabled(boolean autoPrepareStmt)
      Enables or Disables the use of Prepared Statements only for the read and update operations in DBRecord. For general use of Prepared Statements please use DBContext.createCommand() However statement parameters can always be manually declared using cmd.addCmdParam();
      Parameters:
      autoPrepareStmt - flag whether to automatically convert literal values to prepared statement params

    • checkExists

      public boolean checkExists(DBContext context)
      Checks if the database exists The implementation depends on the DBMSHandler
      Parameters:
      context - the database context
      Returns:
      true if the database exists or false otherwise

    • open

      public void open(DBContext context)
      Attaches the Database to the DBMS Handler provided with the context and allows the Database and the Handler to perform initialization tasks
      Parameters:
      context - the DBContext

    • close

      public void close(DBContext context)
      Closes this database object by detaching it from the dbms
      Parameters:
      context - the DBContext

    • getCreateDDLScript

      public void getCreateDDLScript(DBSQLScript script)
      Creates a DDL Script for creating all database objects on the target database.
      This function may be called even if the database has not been previously opened.

      Once the database is open you can use getDbms().getDLLCommand() to create, alter or delete other database objects

      Parameters:
      script - the script object that will be completed

    • generateDDLScript

      protected void generateDDLScript(DBSQLScript script)
      Override this to change or add DDL commands
      Parameters:
      script - the script on which to add the DDL commands

    • getDatabase

      public DBDatabase getDatabase()
      Description copied from class: DBObject
      Returns the database object to which this object belongs to. For the database object itself this function will return the this pointer.
      Specified by:
      getDatabase in class DBObject
      Returns:
      the database object
      See Also:

    • getSchema

      public String getSchema()
      Returns the schema for SQL statements.
      Returns:
      the schema

    • setSchema

      public void setSchema(String schema)
      Sets the schema for SQL statements.
      Parameters:
      schema - the schema to set

    • getSchemaPrefix

      public String getSchemaPrefix()
      Returns the schema-prefix for SQL statements e.g. "SCHEMA." or empty string if no schema is defined.
      Returns:
      the schema-prefix

    • getLinkName

      public String getLinkName()
      Returns the database link name.
      Returns:
      the name of the database link

    • setLinkName

      public void setLinkName(String linkName)
      Sets the name of the database link used to identify objects.
      Parameters:
      linkName - the database link name

    • appendQualifiedName

      public void appendQualifiedName(DBSQLBuilder sql, String name, Boolean quoteName)
      Adds a full qualified object name including schema prefix and database link postfix (if any). to the string buffer supplied
      Parameters:
      sql - the SQL Builder to which to append the qualified object name
      name - the object's name
      quoteName - use quotes or not. If null detectQuoteName() is called

    • getColumnJavaType

      public Class<?> getColumnJavaType(DBColumnExpr expr)
      Returns the java class type for a given dataType
      Parameters:
      expr - the column expression for which to return the java type
      Returns:
      return the java class used for storing values of this dataType

    • getIgnoreCaseExpr

      public DBColumnExpr getIgnoreCaseExpr(DBColumnExpr columnExpr)
      Returns an expression that ignores the case of a column expression This is only called for case sensitive column expressions (expr.isCaseSensitive()) Default is upper(expr)
      Parameters:
      columnExpr - the expression for which to ignore the case
      Returns:
      the ignore case expression

    • getValueExpr

      public DBValueExpr getValueExpr(Object value, DataType dataType)
      Creates and returns a value object for the given scalar value.
      Parameters:
      value - the scalar value
      dataType - the database systems data type used for this value
      Returns:
      the new DBValueExpr object

    • getSystemDateExpr

      public final DBValueExpr getSystemDateExpr()
      Creates and returns a value object for the database systems current date and time.
      Returns:
      a DBValueExpr object

    • getValueExpr

      public final DBValueExpr getValueExpr(String value)
      Creates and returns a value object for the given string value.
      Parameters:
      value - the String value
      Returns:
      the new DBValueExpr object

    • getValueExpr

      public final DBValueExpr getValueExpr(boolean value)
      Creates and returns a value object for the given boolean value.
      Parameters:
      value - the Boolean value
      Returns:
      the new DBValueExpr object

    • getValueExpr

      public final DBValueExpr getValueExpr(int value)
      Creates and returns a value object for the given integer value.
      Parameters:
      value - the int value
      Returns:
      the new DBValueExpr object

    • getValueExpr

      public final DBValueExpr getValueExpr(long value)
      Creates and returns a value object for the given long value.
      Parameters:
      value - the long value
      Returns:
      the new DBValueExpr object

    • getValueExpr

      public final DBValueExpr getValueExpr(BigDecimal value)
      Creates and returns a value object for the given string value.
      Parameters:
      value - the String value
      Returns:
      the new DBValueExpr object

    • getParamExpr

      public final DBValueExpr getParamExpr(DBCmdParam param)
      Creates and returns a value expression for a command parameter
      Parameters:
      param - the command parameter
      Returns:
      the corresponding DBValueExpr object

    • getNullExpr

      public final DBValueExpr getNullExpr()
      Creates and returns a value expression for NULL
      Returns:
      the corresponding DBValueExpr object

    • addTable

      protected void addTable(DBTable table)
      Adds a DBTable object to list of database tables.
      This function is called internally from the DBTable's constructor.

      Parameters:
      table - the DBTable object

    • removeTable

      public void removeTable(DBTable table)
      Removes a table from the list of database tables
      Parameters:
      table - to remove

    • getTables

      public List<DBTable> getTables()
      Returns the tables which have been defined in the database.
      Returns:
      db tables.

    • getTable

      public DBTable getTable(String name)
      Finds a DBTable object by name.

      Parameters:
      name - the name of the table
      Returns:
      the located DBTable object

    • getRowSet

      public DBRowSet getRowSet(String name)
      Finds a DBRowSet object (DBTable or DBView) by name.

      Parameters:
      name - the name of the table
      Returns:
      the located DBTable object

    • getRowSetByAlias

      public DBRowSet getRowSetByAlias(String alias)
      Finds a RowSet object by the alias name.
      Parameters:
      alias - the alias of the desired table
      Returns:
      the located DBTable object

    • getAllRowSets

      public Collection<DBRowSet> getAllRowSets()
      Returns all DBRowSet instances currently created for this database
      Returns:
      all DBRowSet instances

    • addRelation

      public final DBRelation addRelation(DBRelation.DBReference reference)
      Adds a foreign key relation to the database.
      Parameters:
      reference - a reference for a source and target column pair
      Returns:
      the relation object

    • addRelation

      public final DBRelation addRelation(DBRelation.DBReference ref1, DBRelation.DBReference ref2)
      Adds a foreign key relation to the database.
      Parameters:
      ref1 - a reference for a source and target column pair
      ref2 - a reference for a source and target column pair
      Returns:
      the relation object

    • addRelation

      public DBRelation addRelation(String name, DBRelation.DBReference... references)
      Adds a foreign key relation to the database.
      Parameters:
      name - the relation name
      references - a list of source and target column pairs
      Returns:
      the relation object

    • removeRelation

      public void removeRelation(DBRelation relation)
      removes a relation from the list of relations
      Parameters:
      relation - the relation to remove

    • getRelations

      public List<DBRelation> getRelations()
      Returns the relations which have been defined in the database.
      Returns:
      the list of relations.

    • getRelation

      public DBRelation getRelation(String relationName)
      Returns the relation of a given name
      Parameters:
      relationName - the name of the relation
      Returns:
      db the relation of the given name

    • findRelationsOn

      public List<DBRelation> findRelationsOn(DBTable table)
      Returns a list of foreign key relations on a given table
      Parameters:
      table - the table for which to find all foreign keys
      Returns:
      the list of all foreign key relations

    • addView

      protected void addView(DBView view)
      Adds a DBView object to list of database views.
      This function is called internally from the DBView's constructor.

      Parameters:
      view - the DBView object

    • removeView

      public void removeView(DBView view)
      Removes a view from the list of database views
      Parameters:
      view - to remove

    • getViews

      public List<DBView> getViews()
      Returns the views which have been defined in the database.
      Returns:
      db views.

    • getView

      public DBView getView(String name)
      Finds a DBView object by name.
      Parameters:
      name - the name of the view
      Returns:
      the located DBTable object

    • isOpen

      public boolean isOpen()
      Indicates whether the database has been opened.
      Returns:
      The name of the encoding or null if a single byte encoding is used.

    • checkOpen

      protected void checkOpen()
      checks if the database has been opened or false otherwise

    • createCommand

      public DBCommand createCommand()
      Creates a new Command object for this database Deprecated instead use context.createCommand();
      Returns:
      the command object.

    • detectDataType

      public DataType detectDataType(Object value)
      Detects the DataType of a given value.
      Parameters:
      value - the value to detect
      Returns:
      the DataType enum for the value

    • validateValue

      protected Object validateValue(DBTableColumn column, Object value)
      Checks whether the supplied value is valid for the given column. If the type of the value supplied does not match the columns data type the value will be checked for compatibility. If the value is not valid a FieldIllegalValueException is thrown
      Parameters:
      column - the column to check
      value - the checked to check for validity
      Returns:
      the (possibly converted) value
      Throws:
      FieldValueException - exception thrown if value is not valid

    • validateNumber

      protected Number validateNumber(DBTableColumn column, DataType type, Number n)

    • validateString

      protected String validateString(DBTableColumn column, String value)

    • caseWhen

      public DBCaseExpr caseWhen(DBCompareExpr condition, Object trueValue, Object falseValue)
      Creates a SQL case expression in the form "case when [condition] then [trueValue] else [falseValue] end" This is a helper function to simplify client usage
      Parameters:
      condition - the compare expression
      trueValue - the value to select if the condition is true
      falseValue - the value to select if the condition is false
      Returns:
      the case expression

    • caseWhen

      public DBCaseExpr caseWhen(Map<DBCompareExpr,? extends Object> whenMap, Object elseValue)
      Creates a SQL case expression in the form "case when [mapKey] then [mapValue] else [elseValue] end"
      Parameters:
      whenMap - the map with constraints
      elseValue - the else expression
      Returns:
      the expression

    • caseWhenNull

      public DBCaseExpr caseWhenNull(DBColumnExpr column, Object trueValue, Object falseValue)
      Creates a SQL case expression that check whether a column or column expression is null "case when [condition] is null then [trueValue] else [falseValue] end" This is a helper function to simplify client usage
      Parameters:
      column - a column or column expression
      trueValue - the value to select if the condition is true
      falseValue - the value to select if the condition is false
      Returns:
      an sql case expression

    • caseMap

      public DBCaseExpr caseMap(DBColumnExpr column, Map<? extends Object,? extends Object> valueMap, Object elseValue)
      Creates a SQL case expression in the form "case [Expr] when [mapKey] then [mapValue] else [elseValue] end"
      Parameters:
      column - the column expression which to map
      valueMap - map of key value pairs
      elseValue - the else expression
      Returns:
      the expression

    • caseMap

      public DBCaseExpr caseMap(DBColumnExpr column, Options options, Object elseValue)
      Creates a SQL case expression in the form "case [Expr] when [optionValue] then [optionText] else [elseValue] end"
      Parameters:
      column - a column or column expression
      options - the options to map
      elseValue - the else expression
      Returns:
      the expression

    • caseMap

      public DBCaseExpr caseMap(DBColumnExpr column, Object cmpValue, Object trueValue, Object falseValue)
      Creates a SQL case expression in the form "case [Expr] when [compareValue] then [trueValue] else [elseValue] end"
      Parameters:
      column - a column or column expression
      cmpValue - the value to compare the column value with
      trueValue - the true expression
      falseValue - the false expression
      Returns:
      the expression

    • isSameRowSet

      protected boolean isSameRowSet(DBRowSet first, DBRowSet second)
      Checks if two Rowsets with the same name are equal and just another instance
      Parameters:
      first - the first rowset
      second - the second rowset
      Returns:
      true if both are the same and are just another instance

    • addRowsetToAliasMap

      protected void addRowsetToAliasMap(DBRowSet rowset)
      adds a DBRowSet to the alias map
      Parameters:
      rowset - the rowset to add to the map

    • removeRowsetFromAliasMap

      protected void removeRowsetFromAliasMap(DBRowSet rowset)
      removes a rowset from the alias map
      Parameters:
      rowset - the rowset to remove