Package helma.objectmodel.db

# Class DbMapping

java.lang.Object
helma.objectmodel.db.DbMapping

public final class DbMapping extends Object
A DbMapping describes how a certain type of Nodes is to mapped to a relational database table. Basically it consists of a set of JavaScript property-to- Database row bindings which are represented by instances of the Relation class.

## Field Summary

Fields
Modifier and Type
Field
Description
`protected final Application`
`app`
`protected Relation`
`propRelation`
`protected Relation`
`subRelation`

## Constructor Summary

Constructors
Constructor
Description
`DbMapping(Application app, String parentTypeName)`
Create an internal DbMapping used for "virtual" mappings aka collections, mountpoints etc.
`DbMapping(Application app, String typename, Properties props)`
Create a DbMapping from a type.properties property file
`DbMapping(Application app, String typename, Properties props, boolean virtual)`
Create a DbMapping from a type.properties property file

## Method Summary

Modifier and Type
Method
Description
`protected void`
`addDependency(DbMapping dbmap)`
Register a DbMapping that depends on this DbMapping, so that collections of other mapping should be reloaded if data on this mapping is updated.
`void`
`addJoinConstraints(StringBuffer s, String pre)`
Add constraints to select query string to join object references
`protected void`
`appendCondition(StringBuffer q, String column, String val)`
Append a sql-condition for the given column which must have the value given to the given StringBuffer.
`protected void`
`appendCondition(StringBuffer q, String column, String[] values)`
Append a sql-condition for the given column which must have one of the values contained inside the given Set to the given StringBuffer.
`static boolean`
`areStorageCompatible(DbMapping dbm1, DbMapping dbm2)`
Static utility method to check whether two DbMappings use the same storage.
`String`
`columnNameToProperty(String columnName)`
Translate a database column name to an object property name according to this mapping.
`Relation`
`columnNameToRelation(String columnName)`
Translate a database column name to an object property name according to this mapping.
`Application`
`getApplication()`
Get the application this DbMapping belongs to.
`String`
`getAppName()`
Get the name of this mapping's application
`DbColumn`
`getColumn(String columnName)`
`DbColumn[]`
`getColumns()`
Return an array of DbColumns for the relational table mapped by this DbMapping.
`Connection`
`getConnection()`
Get a JDBC connection for this DbMapping.
`DbSource`
`getDbSource()`
Get the DbSource object for this DbMapping.
`String`
`getDbSourceName()`
Get the dbsource name used for this type mapping.
`Relation`
`getExactPropertyRelation(String propname)`
`String`
`getExtends()`
Get the name of this type's parent type, if any.
`String`
`getExtensionId()`
get the id-value of this extension
`String[]`
`getExtensions()`
Returns the Set of Prototypes extending this prototype
`DbMapping`
`getGroupbyMapping()`
If subnodes are grouped by one of their properties, return the db-mapping with the right relations to create the group-by nodes
`String`
`getIDField()`
Get the primary key column name for objects using this mapping.
`String`
`getIDgen()`
`String`
`getInsert()`
`Relation[]`
`getJoins()`
Return the array of relations that are fetched with objects of this type.
`long`
`getLastDataChange()`
Get the last time something changed in our data
`long`
`getLastTypeChange()`
Get the last time something changed in the Mapping
`String`
`getNameField()`
Get the column used for (internal) names of objects of this type.
`protected long`
`getNewID(long dbmax)`
Helper method to generate a new ID.
`ParentInfo[]`
`getParentInfo()`
`DbMapping`
`getParentMapping()`
Get the mapping we inherit from, or null
`String`
`getParentSetting()`
`Properties`
`getProperties()`
Get our ResourceProperties
`Enumeration`
`getPropertyEnumeration()`
Return an enumeration of all properties defined by this db mapping.
`DbMapping`
`getPropertyMapping(String propname)`
`String[]`
`getPropertyNames()`
Return the list of defined property names as String array.
`Relation`
`getPropertyRelation(String propname)`
`String`
`getPrototypeField()`
Get the column used for names of prototype.
`String`
`getPrototypeName(String id)`
Looks up the prototype name identified by the given id, returing our own type name if it can't be resolved
`StringBuffer`
`getSelect(Relation rel)`
Get a StringBuffer initialized to the first part of the select statement for objects defined by this DbMapping
`String`
`getStorageTypeName()`
Return the name of the prototype which specifies the storage location (dbsource + tablename) for this type, or null if it is stored in the embedded db.
`String`
`getSubnodeGroupby()`
`DbMapping`
`getSubnodeMapping()`
`Relation`
`getSubnodeRelation()`
`Properties`
`getSubProperties(String prefix)`
`String`
`getTableName()`
Get the table name used for this type mapping.
`String`
`getTypeName()`
Get the name of the object type this DbMapping belongs to.
`StringBuffer`
`getUpdate()`
`WrappedNodeManager`
`getWrappedNodeManager()`
`protected boolean`
`inheritsStorage()`
Check whether this DbMapping inherits its storage location from its parent mapping.
`boolean`
`isGroup()`
Find if this DbMapping describes a group node.
`boolean`
`isH2()`
Is the database behind this a H2 db?
`boolean`
`isInstanceOf(String other)`
Return true if this db mapping represents the prototype indicated by the string argument, either itself or via one of its parent prototypes.
`boolean`
`isMySQL()`
Is the database behind this a MySQL db?
`boolean`
`isOracle()`
Is the database behind this an Oracle db?
`boolean`
`isPostgreSQL()`
Is the database behind this a PostgreSQL db?
`boolean`
`isRelational()`
Tell whether this data mapping maps to a relational database table.
`boolean`
`isStorageCompatible(DbMapping other)`
Tell if this DbMapping uses the same storage as the given DbMapping.
`boolean`
`isVirtual()`
Find if this DbMapping describes a virtual node (collection, mountpoint, groupnode)
`boolean`
`needsPersistence()`
Find whether a node with this DbMapping must be stored in the database.
`boolean`
`needsQuotes(String columnName)`
Return true if values for the column identified by the parameter need to be quoted in SQL queries.
`boolean`
`needsUpdate()`
Tell the type manager whether we need update() to be called
`String`
`propertyToColumnName(String propName)`
Translate an object property name to a database column name according to this mapping.
`Relation`
`propertyToRelation(String propName)`
Translate an object property name to a database column name according to this mapping.
`void`
`remove()`
Method in interface Updatable.
`protected void`
`setIndirectDataChange()`
Set the last time something changed in the data.
`void`
`setLastDataChange()`
Set the last time something changed in the data, propagating the event to mappings that depend on us through an additionalTables switch.
`void`
`setPropertyRelation(Relation rel)`
`String`
`toString()`
Return a string representation for this DbMapping
`void`
`update()`
Read the mapping from the Properties.

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

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

## Field Details

### app

protected final Application app

### subRelation

protected Relation subRelation

### propRelation

protected Relation propRelation

## Constructor Details

### DbMapping

public DbMapping(Application app, String parentTypeName)
Create an internal DbMapping used for "virtual" mappings aka collections, mountpoints etc.

### DbMapping

public DbMapping(Application app, String typename, Properties props, boolean virtual)
Create a DbMapping from a type.properties property file

### DbMapping

public DbMapping(Application app, String typename, Properties props)
Create a DbMapping from a type.properties property file

## Method Details

### needsUpdate

public boolean needsUpdate()
Tell the type manager whether we need update() to be called

### update

public void update()
Read the mapping from the Properties. Return true if the properties were changed. The read is split in two, this method and the rewire method. The reason is that in order for rewire to work, all other db mappings must have been initialized and registered.

### getExtensions

public String[] getExtensions()
Returns the Set of Prototypes extending this prototype

Returns:
  the Set of Prototypes extending this prototype

### getPrototypeName

public String getPrototypeName(String id)
Looks up the prototype name identified by the given id, returing our own type name if it can't be resolved

Parameters:
  `id` - the id specified for the prototype
Returns:
  the name of the extending prototype

### getExtensionId

public String getExtensionId()
get the id-value of this extension

### remove

public void remove()
Method in interface Updatable.

### getConnection

public Connection getConnection() throws ClassNotFoundException, SQLException
Get a JDBC connection for this DbMapping.

Throws:
  `ClassNotFoundException`
  `SQLException`

### getDbSource

public DbSource getDbSource()
Get the DbSource object for this DbMapping. The DbSource describes a JDBC data source including URL, JDBC driver, username and password.

### getDbSourceName

public String getDbSourceName()
Get the dbsource name used for this type mapping.

### getTableName

public String getTableName()
Get the table name used for this type mapping.

### getApplication

public Application getApplication()
Get the application this DbMapping belongs to.

### getAppName

public String getAppName()
Get the name of this mapping's application

### getTypeName

public String getTypeName()
Get the name of the object type this DbMapping belongs to.

### getExtends

public String getExtends()
Get the name of this type's parent type, if any.

### getIDField

public String getIDField()
Get the primary key column name for objects using this mapping.

### getNameField

public String getNameField()
Get the column used for (internal) names of objects of this type.

### getPrototypeField

public String getPrototypeField()
Get the column used for names of prototype.

### columnNameToProperty

public String columnNameToProperty(String columnName)
Translate a database column name to an object property name according to this mapping.

### propertyToColumnName

public String propertyToColumnName(String propName)
Translate an object property name to a database column name according to this mapping. If no mapping is found, the property name is returned, assuming property and column names are equal.

### columnNameToRelation

public Relation columnNameToRelation(String columnName)
Translate a database column name to an object property name according to this mapping.

### propertyToRelation

public Relation propertyToRelation(String propName)
Translate an object property name to a database column name according to this mapping.

### getParentSetting

public String getParentSetting()

Returns:
  the parent info as unparsed string.

### getParentInfo

public ParentInfo[] getParentInfo()

Returns:
  the parent info array, which tells an object of this type how to determine its parent object.

### getSubnodeMapping

public DbMapping getSubnodeMapping()

Returns:
  ...

### getPropertyMapping

public DbMapping getPropertyMapping(String propname)

Parameters:
  `propname` - ...
Returns:
  ...

### getGroupbyMapping

public DbMapping getGroupbyMapping()
If subnodes are grouped by one of their properties, return the db-mapping with the right relations to create the group-by nodes

### setPropertyRelation

public void setPropertyRelation(Relation rel)

Parameters:
  `rel` - ...

### getSubnodeRelation

public Relation getSubnodeRelation()

Returns:
  ...

### getPropertyNames

public String[] getPropertyNames()
Return the list of defined property names as String array.

### getPropertyRelation

public Relation getPropertyRelation(String propname)

Parameters:
  `propname` - ...
Returns:
  ...

### getExactPropertyRelation

public Relation getExactPropertyRelation(String propname)

Parameters:
  `propname` - ...
Returns:
  ...

### getSubnodeGroupby

public String getSubnodeGroupby()

Returns:
  ...

### getIDgen

public String getIDgen()

Returns:
  ...

### getWrappedNodeManager

public WrappedNodeManager getWrappedNodeManager()

Returns:
  ...

### isRelational

public boolean isRelational()
Tell whether this data mapping maps to a relational database table. This returns true if a datasource is specified, even if it is not a valid one. Otherwise, objects with invalid mappings would be stored in the embedded db instead of an error being thrown, which is not what we want.

### getColumns

public DbColumn[] getColumns() throws ClassNotFoundException, SQLException
Return an array of DbColumns for the relational table mapped by this DbMapping.

Throws:
  `ClassNotFoundException`
  `SQLException`

### getJoins

public Relation[] getJoins()
Return the array of relations that are fetched with objects of this type.

### getColumn

public DbColumn getColumn(String columnName) throws ClassNotFoundException, SQLException

Parameters:
  `columnName` - ...
Returns:
  ...
Throws:
  `ClassNotFoundException` - ...
  `SQLException` - ...

### getSelect

public StringBuffer getSelect(Relation rel)
Get a StringBuffer initialized to the first part of the select statement for objects defined by this DbMapping

Parameters:
  `rel` - the Relation we use to select. Currently only used for optimizer hints. Is null if selecting by primary key.
Returns:
  the StringBuffer containing the first part of the select query

### getInsert

public String getInsert() throws ClassNotFoundException, SQLException

Returns:
  ...
Throws:
  `ClassNotFoundException`
  `SQLException`

### getUpdate

public StringBuffer getUpdate()

Returns:
  ...

### needsQuotes

public boolean needsQuotes(String columnName) throws SQLException, ClassNotFoundException
Return true if values for the column identified by the parameter need to be quoted in SQL queries.

Throws:
  `SQLException`
  `ClassNotFoundException`

### addJoinConstraints

public void addJoinConstraints(StringBuffer s, String pre)
Add constraints to select query string to join object references

### isOracle

public boolean isOracle()
Is the database behind this an Oracle db?

Returns:
  true if the dbsource is using an oracle JDBC driver

### isMySQL

public boolean isMySQL()
Is the database behind this a MySQL db?

Returns:
  true if the dbsource is using a MySQL JDBC driver

### isPostgreSQL

public boolean isPostgreSQL()
Is the database behind this a PostgreSQL db?

Returns:
  true if the dbsource is using a PostgreSQL JDBC driver

### isH2

public boolean isH2()
Is the database behind this a H2 db?

Returns:
  true if the dbsource is using a H2 JDBC driver

### toString

public String toString()
Return a string representation for this DbMapping

Overrides:
  `toString` in class `Object`
Returns:
  a string representation

### getLastTypeChange

public long getLastTypeChange()
Get the last time something changed in the Mapping

Returns:
  time of last mapping change

### getLastDataChange

public long getLastDataChange()
Get the last time something changed in our data

Returns:
  time of last data change

### setLastDataChange

public void setLastDataChange()
Set the last time something changed in the data, propagating the event to mappings that depend on us through an additionalTables switch.

### setIndirectDataChange

protected void setIndirectDataChange()
Set the last time something changed in the data. This is already an indirect data change triggered by a mapping we depend on, so we don't propagate it to mappings that depend on us through an additionalTables switch.

### getNewID

protected long getNewID(long dbmax)
Helper method to generate a new ID. This is only used in the special case when using the select(max) method and the underlying table is still empty.

Parameters:
  `dbmax` - the maximum value already stored in db
Returns:
  a new and hopefully unique id

### getPropertyEnumeration

public Enumeration getPropertyEnumeration()
Return an enumeration of all properties defined by this db mapping.

Returns:
  the property enumeration

### getStorageTypeName

public String getStorageTypeName()
Return the name of the prototype which specifies the storage location (dbsource + tablename) for this type, or null if it is stored in the embedded db.

### inheritsStorage

protected boolean inheritsStorage()
Check whether this DbMapping inherits its storage location from its parent mapping. The raison d'etre for this is that we need to detect inherited storage even if the dbsource and table are explicitly set in the extended mapping.

Returns:
  true if this mapping shares its parent mapping storage

### areStorageCompatible

public static boolean areStorageCompatible(DbMapping dbm1, DbMapping dbm2)
Static utility method to check whether two DbMappings use the same storage.

Returns:
  true if both use the embedded database or the same relational table.

### isStorageCompatible

public boolean isStorageCompatible(DbMapping other)
Tell if this DbMapping uses the same storage as the given DbMapping.

Returns:
  true if both use the embedded database or the same relational table.

### isInstanceOf

public boolean isInstanceOf(String other)
Return true if this db mapping represents the prototype indicated by the string argument, either itself or via one of its parent prototypes.

### getParentMapping

public DbMapping getParentMapping()
Get the mapping we inherit from, or null

Returns:
  the parent DbMapping, or null

### getProperties

public Properties getProperties()
Get our ResourceProperties

Returns:
  our properties

### getSubProperties

public Properties getSubProperties(String prefix)

### addDependency

protected void addDependency(DbMapping dbmap)
Register a DbMapping that depends on this DbMapping, so that collections of other mapping should be reloaded if data on this mapping is updated.

Parameters:
  `dbmap` - the DbMapping that depends on us

### appendCondition

protected void appendCondition(StringBuffer q, String column, String[] values) throws SQLException, ClassNotFoundException
Append a sql-condition for the given column which must have one of the values contained inside the given Set to the given StringBuffer.

Parameters:
  `q` - the StringBuffer to append to
  `column` - the column which must match one of the values
  `values` - the list of values
Throws:
  `SQLException`
  `ClassNotFoundException`

### appendCondition

protected void appendCondition(StringBuffer q, String column, String val) throws SQLException, ClassNotFoundException
Append a sql-condition for the given column which must have the value given to the given StringBuffer.

Parameters:
  `q` - the StringBuffer to append to
  `column` - the column which must match one of the values
  `val` - the value
Throws:
  `SQLException`
  `ClassNotFoundException`

### isVirtual

public boolean isVirtual()
Find if this DbMapping describes a virtual node (collection, mountpoint, groupnode)

Returns:
  true if this instance describes a virtual node.

### isGroup

public boolean isGroup()
Find if this DbMapping describes a group node.

Returns:
  true if this instance describes a group node.

### needsPersistence

public boolean needsPersistence()
Find whether a node with this DbMapping must be stored in the database. This is true if this mapping defines a non-virtual node, or a virtual node with non-relational child objects.

Returns:
  true if this node needs to be stored in the db, false otherwise