|
|||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface Transaction
This class models operations with a database.
Strictly speaking this class represents a database connection. Obtaining more such objects for the same database
configurations will result in opening more connections. Connections must be given back to the system using the
close()
method. That will be done automatically by the object's finalizer. In makumba business logic,
connections passed to the BL methods are automatically closed by the system after the BL operations (including
eventual automatic DB acceses) were completed. To open a "sibling" of a connection conn of this type, use
MakumbaSystem.getConnectionTo(conn.getName()). In most cases, you will have to close the sibling yourself.
At the level of this API, data is represented as java.util.Dictionary, both for reading and writing. Most methods
throw DBError
if a fatal database error occurs. If the connection to the database is lost, an attempt is made
to reconnect before throwing a DBError
.
All methods throw subclasses of either Error or RuntimeException, so nothing needs to be caught explicitely.
org.makumba.MakumbaSystem#getDefaultDataSourceName()
,
org.makumba.MakumbaSystem#getDefaultDatabaseName(java.lang.String)
,
MakumbaSystem.getConnectionTo(java.lang.String)
Method Summary | |
---|---|
void |
close()
Give this connection back to the system. |
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 parameterValues)
Delete in the form delete("general.Person p", "p=$1", params) . |
Vector<Dictionary<String,Object>> |
executeQuery(String query,
Object arguments)
Execute query without limiting the results. |
Vector<Dictionary<String,Object>> |
executeQuery(String query,
Object arguments,
int offset,
int limit)
Execute a parametrized OQL query. |
String |
getDataSource()
Returns the name of the data source to which this Transaction is connected |
String |
getName()
Get the name of the database in the form host[_port]_dbprotocol_dbname |
org.makumba.providers.TransactionProvider |
getTransactionProvider()
Returns the TransactionProvider which created this Transaction |
Pointer |
insert(Pointer host,
String subsetField,
Dictionary<String,Object> data)
Insert a record in a subset (1-N set) 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. |
void |
lock(String symbol)
Acquire a lock associated to the given application-specific symbol. |
Dictionary<String,Object> |
read(Pointer ptr,
Object fields)
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)
|
void |
rollback()
Rollback the transaction associated with this connection. |
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 parameterValues)
Update in the form update("general.Person p", "p.birthdate=$1", "p=$2", params) . |
int |
updateSet(Pointer basePointer,
String setName,
Collection<?> addElements,
Collection<?> removeElements)
Convenience method to update the values of an external set. |
List<FieldValueDiff> |
updateWithValueDiff(Pointer ptr,
Dictionary<String,Object> fieldsToChange)
|
Method Detail |
---|
Dictionary<String,Object> read(Pointer ptr, Object fields)
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.
read
in interface Database
ptr
- the pointer to the recordfields
- the fields to read, or null to read all fields. Can be a String, String[], Enumeration or a Vector
InvalidValueException
- if the fields argument is not String, String[], Enumeration or Vector
DBError
- if a fatal database error occurs
IllegalStateException
- if the connection was already closedString getName()
getName
in interface Database
Vector<Dictionary<String,Object>> executeQuery(String query, Object arguments, int offset, int limit)
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.
executeQuery
in interface Database
query
- the query to execute. Refers to parameters as $1, $2 ...arguments
- 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.limit
- the maximum number of records to return, -1 for alloffset
- the offset of the first record to return, 0 for first
DBError
- if a fatal database error occurs
OQLParseError
- if the OQL is not correct
InvalidValueException
- in case of makumba type conflict between a pointer value passed as parameter and the type expected
in the respective OQL expression
IllegalStateException
- if the connection was already closedVector<Dictionary<String,Object>> executeQuery(String query, Object arguments)
executeQuery
in interface Database
executeQuery(java.lang.String,java.lang.Object,int,int)
Pointer insert(String type, Dictionary<String,Object> data)
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:
insert
in interface Database
type
- the makumba type to create a new record fordata
- the field-value mapping for the new record. DBError
- if a fatal database error occurs
DataDefinitionNotFoundError
- if the indicated type is not found
InvalidValueException
- if a certain field does not accept the given value
InvalidValueException
- in case of makumba type conflict between a pointer value passed and the definition of the
respective field
ClassCastException
- in case of java type conflict between a value passed and the definition of the respective field
IllegalStateException
- if the connection was already closedVector<Pointer> insert(String type, Collection<Dictionary<String,Object>> data)
insert(String, Dictionary)
, only
that a collection is provided instead of a single Dictionary.
type
- the makumba type to create a new record fordata
- a set of field-value mapping for the new record. Pointer insert(Pointer host, String subsetField, Dictionary<String,Object> data)
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.
insert
in interface Database
host
- a pointer to the host record, to which a subrecord will be addedsubsetField
- the name of the subrecord field.data
- the field-value mapping for the new subrecord. DBError
- if a fatal database error occurs
InvalidValueException
- if a certain value is not valid for a field
InvalidValueException
- in case of makumba type conflict between a pointer value passed and the definition of the
respective field
ClassCastException
- in case of java type conflict between a value passed and the definition of the respective field
IllegalStateException
- if the connection was already closedint insertFromQuery(String type, String OQL, Object parameterValues)
type
- the type where to insertOQL
- 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
int update(Pointer ptr, Dictionary<String,Object> fieldsToChange)
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:
update
in interface Database
ptr
- pointer to the record to updatefieldsToChange
- key-value pairs for the fields to modify. DBError
- if a fatal database error occurs
InvalidValueException
- if a certain value is not valid for a field
InvalidValueException
- in case of makumba type conflict between a pointer value passed and the definition of the
respective field
ClassCastException
- in case of java type conflict between a value passed and the definition of the respective field
IllegalStateException
- if the connection was already closedPointer.Null
,
Pointer.NullInteger
,
Pointer.NullString
,
Pointer.NullText
,
Pointer.NullDate
,
Pointer.NullSet
List<FieldValueDiff> updateWithValueDiff(Pointer ptr, Dictionary<String,Object> fieldsToChange)
int update(String from, String set, String where, Object parameterValues)
update("general.Person p", "p.birthdate=$1", "p=$2", params)
. 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.
update
in interface Database
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"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
IllegalStateException
- if the connection was already closed
DBError
- if a fatal database error occursint updateSet(Pointer basePointer, String setName, Collection<?> addElements, Collection<?> removeElements)
setName
of the object basePointer
into a
collection, using readExternalSetValues(Pointer, String)
deleteElements
newElements
update(Pointer, Dictionary)
to write the new set values to the database
basePointer
- pointer to the record to updatesetName
- the name of the external set in the type of basePointeraddElements
- A Collection
of String
or Pointer
(the type can vary for each collection
element) of new objects to add to existing set elementsremoveElements
- 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
Vector<Pointer> readExternalSetValues(Pointer basePointer, String setName)
Collection
. This method is a
shortcut to other Makumba API and Java methods, and basically does the following steps:
executeQuery(String, Object)
to read all the values of the field setName
of the
object basePointer
.Vector>
into a Vector
basePointer
- pointer to the record to updatesetName
- the name of the external set in the type of basePointer
Vector
containing the Pointer
of the external setVector<Integer> readIntEnumValues(Pointer basePointer, String setName)
Vector<String> readCharEnumValues(Pointer basePointer, String setName)
void delete(Pointer ptr)
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.
delete
in interface Database
ptr
- the pointer to the record to be deleted
DBError
- if a fatal database error occurs
IllegalStateException
- if the connection was already closedint delete(String from, String where, Object parameterValues)
delete("general.Person p", "p=$1", params)
. 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.
delete
in interface Database
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"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
DBError
- if a fatal database error occurs
IllegalStateException
- if the connection was already closedvoid commit()
commit
in interface Database
void close()
close
in interface Database
DBError
- if a fatal database error occurs
IllegalStateException
- if the connection was already closedvoid rollback()
rollback
in interface Database
void lock(String symbol)
lock
in interface Database
void unlock(String symbol)
unlock
in interface Database
org.makumba.providers.TransactionProvider getTransactionProvider()
String getDataSource()
|
|||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |