org.makumba.db
Class TransactionImplementation

java.lang.Object
  org.makumba.db.TransactionImplementation

All Implemented Interfaces:

Database, Transaction

Direct Known Subclasses:

DBConnection, HibernateTransaction

public abstract class TransactionImplementation
extends Object
implements Transaction

Abstract Transaction, with helper methods for both concrete implementations

Version:

$Id: TransactionImplementation.java,v 1.1 Jun 15, 2008 3:31:07 PM rudi Exp $

Field Summary

protected DataDefinitionProvider	ddp
protected QueryProvider	qp
protected TransactionProvider	tp

Constructor Summary

TransactionImplementation(TransactionProvider tp)

Method Summary

abstract void	close() Give this connection back to the system.
abstract void	commit() Commit the transaction associated with this connection.
void	delete(Pointer ptr) Delete the record pointed by the given pointer.
int	delete(String from, String where, Object parameters) Deletes in the form delete("general.Person p", "p=$1", params) NOTE that this method does not delete subsets and subrecords
void	delete1(Pointer ptr)
abstract Vector<Dictionary<String,Object>>	executeQuery(String OQL, Object parameterValues) Execute query without limiting the results.
abstract Vector<Dictionary<String,Object>>	executeQuery(String OQL, Object parameterValues, int offset, int limit) Execute a parametrized OQL query.
protected abstract Vector<Dictionary<String,Object>>	executeReadQuery(Pointer p, StringBuffer sb)
protected abstract int	executeUpdate(String type, String set, String where, Object args) Executes an UPDATE statement or a DELETE FROM statement, depending on the value of set.
protected Enumeration<String>	extractReadFields(Pointer p, Object flds)
abstract String	getDataSource() Returns the name of the data source to which this Transaction is connected
abstract String	getName() Get the name of the database in the form host[_port]_dbprotocol_dbname
abstract String	getNullConstant()
String	getParameterName()
String	getPrimaryKeyName()
String	getPrimaryKeyName(String ptrDD)
String	getSetJoinSyntax()
TransactionProvider	getTransactionProvider() Returns the TransactionProvider which created this Transaction
Pointer	insert(Pointer base, String field, Dictionary<String,Object> data) Insert a record in a subset (1-N set) or subrecord (1-1 pointer) of the given record.
Vector<Pointer>	insert(String type, Collection<Dictionary<String,Object>> data) Performs a batch insert.
Pointer	insert(String type, Dictionary<String,Object> data) Insert a record of the given type.
int	insertFromQuery(String type, String OQL, Object parameterValues) Insert the results of the query in the given type.
protected abstract int	insertFromQueryImpl(String type, String OQL, Object parameterValues)
abstract void	lock(String symbol) Acquire a lock associated to the given application-specific symbol.
protected Map<String,Object>	paramsToMap(Object args) Takes a heterogeneous argument object (coming from the BL API or the view layer) and transforms it into a Map, taking into account possible context attributes (session, request, and other bundled makumba Attributes)
protected Map<String,Object>	paramsToMap1(Object args)
Dictionary<String,Object>	read(Pointer p, Object flds) Read fields of a record.
Vector<String>	readCharEnumValues(Pointer basePointer, String setName)
Vector<Pointer>	readExternalSetValues(Pointer basePointer, String setName) Convenience method to read all the values of an external set into one Collection.
Vector<Integer>	readIntEnumValues(Pointer basePointer, String setName)
protected <T> Vector<T>	readSetValues(Pointer basePointer, String setName)
abstract void	rollback() Rollback the transaction associated with this connection.
void	setContext(Attributes a)
String	transformTypeName(String name)
abstract void	unlock(String symbol) Free the lock on the given symbol, if any exists.
int	update(Pointer ptr, Dictionary<String,Object> fieldsToChange) change the record pointed by the given pointer.
int	update(String from, String set, String where, Object parameters) updates in the form update("general.Person p", "p.birthdate=$1", "p=$2", params) NOTE that this method does not delete subrecords if their pointers are nullified
int	updateSet(Pointer basePointer, String setName, Collection<?> addElements, Collection<?> removeElements) Convenience method to update the values of an external set.
ArrayList<FieldValueDiff>	updateWithValueDiff(Pointer ptr, Dictionary<String,Object> fieldsToChange)
protected abstract StringBuffer	writeReadQuery(Pointer p, Enumeration<String> e)

Methods inherited from class java.lang.Object

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

Field Detail

ddp

protected DataDefinitionProvider ddp

qp

protected QueryProvider qp

tp

protected TransactionProvider tp

Constructor Detail

TransactionImplementation

public TransactionImplementation(TransactionProvider tp)

Method Detail

close

public abstract void close()

Description copied from interface: Transaction

Give this connection back to the system. This will automatically commit the transaction if it was not committed. A connection cannot be used after closing.

Specified by:

close in interface Database

Specified by:

close in interface Transaction

commit

public abstract void commit()

Description copied from interface: Transaction

Commit the transaction associated with this connection. Normally, simply closing the connection will do, but more often committs may be needed. The business logic manager will close (and therefore commit) all transaction that it provides for usage.

Specified by:

commit in interface Database

Specified by:

commit in interface Transaction

rollback

public abstract void rollback()

Description copied from interface: Transaction

Rollback the transaction associated with this connection. Typically rollback should be doneif an error occurs in a business logic operation. The business logic manager will rollback a transaction that it provided for usage if it catches any exception during the business logic execution.

Specified by:

rollback in interface Database

Specified by:

rollback in interface Transaction

getName

public abstract String getName()

Description copied from interface: Transaction

Get the name of the database in the form host[_port]_dbprotocol_dbname

Specified by:

getName in interface Database

Specified by:

getName in interface Transaction

lock

public abstract void lock(String symbol)

Description copied from interface: Transaction

Acquire a lock associated to the given application-specific symbol. This method will block as long as the lock is already taken on another Database object. The commit() and rollback() methods unlcok all locks acquired on this connection

Specified by:

lock in interface Database

Specified by:

lock in interface Transaction

unlock

public abstract void unlock(String symbol)

Description copied from interface: Transaction

Free the lock on the given symbol, if any exists. This will allow the continuation of a thread that needs a lock on the same symbol and uses another Database object

Specified by:

unlock in interface Database

Specified by:

unlock in interface Transaction

executeUpdate

protected abstract int executeUpdate(String type,
                                     String set,
                                     String where,
                                     Object args)

Executes an UPDATE statement or a DELETE FROM statement, depending on the value of set.

Parameters:

type - the type on which to perform the operation

set - the SET part of the query. if null, this performs a DELETE FROM statement

where - the WHERE part of the query

args - the query arguments

Returns:

either (1) the row count for INSERT, UPDATE, or DELETE statements or (2) 0 for SQL statements that return nothing

delete

public void delete(Pointer ptr)

Delete the record pointed by the given pointer. If the pointer is a 1-1, the oringinal is set to null. All the subrecords and subsets are automatically deleted.

Specified by:

delete in interface Database

Specified by:

delete in interface Transaction

Parameters:

ptr - the pointer to the record to be deleted

delete

public int delete(String from,
                  String where,
                  Object parameters)

Deletes in the form delete("general.Person p", "p=$1", params) NOTE that this method does not delete subsets and subrecords

Specified by:

delete in interface Database

Specified by:

delete in interface Transaction

Parameters:

from - a makumba type in which delete will take place, for example "general.Person p"

where - the OQL conditions selecting the objects to be deleted, e.g. "p=$1"

parameters - the parameter values. Should be null if there are no parameters. If there is only one parameter, it can be indicated directly. If there are more parameters, they can be indicated in a Object[] or a java.util.Vector

Returns:

the number of records affected

executeQuery

public abstract Vector<Dictionary<String,Object>> executeQuery(String OQL,
                                                               Object parameterValues,
                                                               int offset,
                                                               int limit)

Description copied from interface: Transaction

Execute a parametrized OQL query. Queries are pre-compiled and cached in the database, so they should be parametrized as much as possible. Database querying is logged (see Logger, MakumbaSystem.setLoggingRoot(java.lang.String)) in the "db.query.compilation", "db.query.execution", "db.query.performance" loggers, with Level.INFO logging level. "db.query.execution" also logs Level.SEVERE fatal errors.

Specified by:

executeQuery in interface Database

Specified by:

executeQuery in interface Transaction

Parameters:

OQL - the query to execute. Refers to parameters as $1, $2 ...

parameterValues - the arguments of the queries. Should be null if there are none. If there is only one parameter, it can be indicated directly. If there are more parameters, they can be indicated in a Object[] or a java.util.Vector. Named parameters can be indicated in a Map.

offset - the offset of the first record to return, 0 for first

limit - the maximum number of records to return, -1 for all

Returns:

a Dictionary, containing a name-value pair for each non-null SELECT column. If a certain SELECT column is not named using AS, it will be automatically named like col1, col2, etc.

executeQuery

public abstract Vector<Dictionary<String,Object>> executeQuery(String OQL,
                                                               Object parameterValues)

Description copied from interface: Transaction

Execute query without limiting the results.

Specified by:

executeQuery in interface Database

Specified by:

executeQuery in interface Transaction

See Also:

Transaction.executeQuery(java.lang.String,java.lang.Object,int,int)

getTransactionProvider

public TransactionProvider getTransactionProvider()

Description copied from interface: Transaction

Returns the TransactionProvider which created this Transaction

Specified by:

getTransactionProvider in interface Transaction

insert

public Pointer insert(String type,
                      Dictionary<String,Object> data)

Description copied from interface: Transaction

Insert a record of the given type.
Database update is logged (see Logger, MakumbaSystem.setLoggingRoot(java.lang.String)) in the "db.update.execution", "db.update.performance" loggers, with Level.INFO logging level. "db.update.execution" also logs Level.SEVERE fatal errors.

Special makumba fields are treated as follows:

• External sets (sets of records in other tables), as well as sets of int and char can be inserted as Vectors.
  
• Base records and subrecords can be inserted as well. Base records are indicated by fixed, notnull pointers and the record constitutes logical extensions of its base records (this is called subtyping in database theory).
• Subrecords are indicated by 1-1 pointers, and are a logical extension of the record.
• Both base record fields and subrecord fields can be referred to via their pointer, like P.field, where P is a pointer to the base record or a 1-1 pointer. By extension P1.P2.field notations can exist.

Specified by:

insert in interface Database

Specified by:

insert in interface Transaction

Parameters:

type - the makumba type to create a new record for

data - the field-value mapping for the new record.
The ommitted fields will be set to null.
To insert an set of integets (set int {...}) pass a Vector of Integers. (or null, or an empty vector).
To insert an set of strings (set char {...}) pass a Vector of String. (or null, or an empty vector).
To refer to a field of base record or subrecord, indicate the pointer that leads to the record, and the respective field, like ptr1.ptr2.field. Every mentioned base record and subrecord will be inserted.

Returns:

a Pointer to the inserted record

insert

public Vector<Pointer> insert(String type,
                              Collection<Dictionary<String,Object>> data)

Description copied from interface: Transaction

Performs a batch insert. The way of providing data is the same as for Transaction.insert(String, Dictionary), only that a collection is provided instead of a single Dictionary.

Specified by:

insert in interface Transaction

Parameters:

type - the makumba type to create a new record for

data - a set of field-value mapping for the new record.

Returns:

a Vector containing the pointers of the inserted records, in the order in which they were inserted.

insert

public Pointer insert(Pointer base,
                      String field,
                      Dictionary<String,Object> data)

Insert a record in a subset (1-N set) or subrecord (1-1 pointer) of the given record. For 1-1 pointers, if another subrecord existed, it is deleted.

Specified by:

insert in interface Database

Specified by:

insert in interface Transaction

Parameters:

base - a pointer to the host record, to which a subrecord will be added

field - the name of the subrecord field.

data - the field-value mapping for the new subrecord.
The ommitted fields will be set to null.
To insert an external set, pass a Vector of Pointers (or null, or an empty vector).
To insert an set of integets (set int {...}) pass a Vector of Integers. (or null, or an empty vector).
To insert an set of strings (set char {...}) pass a Vector of String. (or null, or an empty vector).
To refer to a field of a subrecord (subset members cannot have base records), indicate the pointer that leads to the record, and the respective field, like ptr1.ptr2.field.

Returns:

a Pointer to the inserted record

insertFromQuery

public int insertFromQuery(String type,
                           String OQL,
                           Object parameterValues)

Description copied from interface: Transaction

Insert the results of the query in the given type. Generates an INSERT...SELECT. The labels of the OQL query must match field names of the given type.

Specified by:

insertFromQuery in interface Transaction

Parameters:

type - the type where to insert

OQL - the OQL query to execute. Refers to parameters as $1, $2 ...

parameterValues - the parameter values. Should be null if there are no parameters. If there is only one parameter, it can be indicated directly. If there are more parameters, they can be indicated in a Object[] or a java.util.Vector

Returns:

the number of records inserted

insertFromQueryImpl

protected abstract int insertFromQueryImpl(String type,
                                           String OQL,
                                           Object parameterValues)

writeReadQuery

protected abstract StringBuffer writeReadQuery(Pointer p,
                                               Enumeration<String> e)

update

public int update(Pointer ptr,
                  Dictionary<String,Object> fieldsToChange)

change the record pointed by the given pointer. Only fields indicated are changed to the respective values

Specified by:

update in interface Database

Specified by:

update in interface Transaction

Parameters:

ptr - pointer to the record to update

fieldsToChange - key-value pairs for the fields to modify.
To nullify a field, pass the respective Null value from the Pointer class.
To change an external set, pass a Vector of Pointers (an empty vector will empty the set).
To change a set of integrers (set int{...}), pass a Vector of Integers (an empty vector will empty the set).
To change a set of integrers (set char{...}), pass a Vector of Strings (an empty vector will empty the set).
To refer to a field of a base record or subrecord, indicate the pointer that leads to the record, and the respective field, like ptr1.ptr2.field.

See Also:

Pointer.Null, Pointer.NullInteger, Pointer.NullString, Pointer.NullText, Pointer.NullDate, Pointer.NullSet

updateWithValueDiff

public ArrayList<FieldValueDiff> updateWithValueDiff(Pointer ptr,
                                                     Dictionary<String,Object> fieldsToChange)

Specified by:

updateWithValueDiff in interface Transaction

updateSet

public int updateSet(Pointer basePointer,
                     String setName,
                     Collection<?> addElements,
                     Collection<?> removeElements)

Description copied from interface: Transaction

Convenience method to update the values of an external set. This method is a shortcut to other Makumba API and Java methods, and basically does the following steps:

1. Read all the existing values of the field setName of the object basePointer into a collection, using Transaction.readExternalSetValues(Pointer, String)
2. Remove the set elements specified in the parameter deleteElements
3. Add the set elements specified in the parameter newElements
4. Use Transaction.update(Pointer, Dictionary) to write the new set values to the database

Specified by:

updateSet in interface Transaction

Parameters:

basePointer - pointer to the record to update

setName - the name of the external set in the type of basePointer

addElements - A Collection of String or Pointer (the type can vary for each collection element) of new objects to add to existing set elements

removeElements - A Collection of String or Pointer (the type can vary for each collection element) of objects that should be removed from the existing set elements

Returns:

the number of records affected

readExternalSetValues

public Vector<Pointer> readExternalSetValues(Pointer basePointer,
                                             String setName)

Description copied from interface: Transaction

Convenience method to read all the values of an external set into one Collection. This method is a shortcut to other Makumba API and Java methods, and basically does the following steps:

1. Run Transaction.executeQuery(String, Object) to read all the values of the field setName of the object basePointer.
2. Convert the resulting Vector> into a Vector

Specified by:

readExternalSetValues in interface Transaction

Parameters:

basePointer - pointer to the record to update

setName - the name of the external set in the type of basePointer

Returns:

A Vector containing the Pointer of the external set

readIntEnumValues

public Vector<Integer> readIntEnumValues(Pointer basePointer,
                                         String setName)

Specified by:

readIntEnumValues in interface Transaction

readCharEnumValues

public Vector<String> readCharEnumValues(Pointer basePointer,
                                         String setName)

Specified by:

readCharEnumValues in interface Transaction

readSetValues

protected <T> Vector<T> readSetValues(Pointer basePointer,
                                      String setName)

update

public int update(String from,
                  String set,
                  String where,
                  Object parameters)

updates in the form update("general.Person p", "p.birthdate=$1", "p=$2", params) NOTE that this method does not delete subrecords if their pointers are nullified

Specified by:

update in interface Database

Specified by:

update in interface Transaction

Parameters:

from - a makumba type in which update will take place, for example "general.Person p"

set - the assignments made by the update, as OQL expression e.g. "p.birthdate=$1". Use "nil" for null assignments.

where - the OQL conditions selecting the objects on which the update will be made, e.g. "p=$2"

parameters - the parameter values. Should be null if there are no parameters. If there is only one parameter, it can be indicated directly. If there are more parameters, they can be indicated in a Object[] or a java.util.Vector

Returns:

the number of records affected

read

public Dictionary<String,Object> read(Pointer p,
                                      Object flds)

Description copied from interface: Transaction

Read fields of a record. Database querying is logged (see Logger, MakumbaSystem.setLoggingRoot(java.lang.String)) in the "db.query.compilation", "db.query.execution", "db.query.performance" loggers, with Level.INFO logging level. "db.query.execution" also logs Level.SEVERE fatal errors.

Specified by:

read in interface Database

Specified by:

read in interface Transaction

Parameters:

p - the pointer to the record

flds - the fields to read, or null to read all fields. Can be a String, String[], Enumeration or a Vector

Returns:

a Dictionary, containing a name-value pair for each non-null field, or null if the record doesn't exist

extractReadFields

protected Enumeration<String> extractReadFields(Pointer p,
                                                Object flds)
                                         throws ProgrammerError

Throws:

ProgrammerError

executeReadQuery

protected abstract Vector<Dictionary<String,Object>> executeReadQuery(Pointer p,
                                                                      StringBuffer sb)

delete1

public void delete1(Pointer ptr)

getSetJoinSyntax

public String getSetJoinSyntax()

paramsToMap

protected Map<String,Object> paramsToMap(Object args)

Takes a heterogeneous argument object (coming from the BL API or the view layer) and transforms it into a Map, taking into account possible context attributes (session, request, and other bundled makumba Attributes)

paramsToMap1

protected Map<String,Object> paramsToMap1(Object args)

transformTypeName

public String transformTypeName(String name)

getParameterName

public String getParameterName()

getPrimaryKeyName

public String getPrimaryKeyName()

getPrimaryKeyName

public String getPrimaryKeyName(String ptrDD)

getNullConstant

public abstract String getNullConstant()

getDataSource

public abstract String getDataSource()

Description copied from interface: Transaction

Returns the name of the data source to which this Transaction is connected

Specified by:

getDataSource in interface Transaction

setContext

public void setContext(Attributes a)