Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.makumba
Interface Transaction

All Superinterfaces:
  Database

All Known Implementing Classes:
  ClosedDBConnection, DBConnection, DBConnectionWrapper, HibernateTransaction, SQLDBConnection, TransactionImplementation

    public interface Transaction

extends Database

This class models operations with a database. To obtain such an object, use methods from `MakumbaSystem`.

Stricly speaking this class represents a database connection (later on, transaction). 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.

Since:
  makumba-0.5
See Also:
  `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
`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.
`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.
`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)` .

Method Detail

### read

    Dictionary<String,Object> read(Pointer ptr,
                                   Object fields)

  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`
  Parameters:
    `ptr` - the pointer to the record
    `fields` - 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
  Throws:
    `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 closed

### getName

    String getName()

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

  Specified by:
    `getName` in interface `Database`

### executeQuery

    Vector<Dictionary<String,Object>> executeQuery(String query,
                                                   Object arguments,
                                                   int offset,
                                                   int limit)

  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`
  Parameters:
    `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 all
    `offset` - the offset of the first record to return, 0 for first
  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.
  Throws:
    `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 closed

### executeQuery

    Vector<Dictionary<String,Object>> executeQuery(String query,
                                                   Object arguments)

  Execute query without limiting the results.

  Specified by:
    `executeQuery` in interface `Database`
  See Also:
    `executeQuery(java.lang.String,java.lang.Object,int,int)`

### insert

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

  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`
  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
  Throws:
    `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 closed

### insert

    Pointer insert(Pointer host,
                   String subsetField,
                   Dictionary<String,Object> data)

  Insert a record in a subset (1-N set) of the given record.
  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:
  - The new member's external sets (sets of records in other tables) as well as sets of int and char can be inserted as Vectors.
  - The new member can have subrecords, but cannot have base records.

  Specified by:
    `insert` in interface `Database`
  Parameters:
    `host` - a pointer to the host record, to which a subrecord will be added
    `subsetField` - 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
  Throws:
    `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 closed

### insertFromQuery

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

  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.

  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

### update

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

  Change the record pointed by the given pointer. Only fields indicated as keys in fieldsToChange are changed to the respective values.
  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 intger or char, can be indicated for change as Vectors.
  - Base records and subrecords can be changed 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:
    `update` in interface `Database`
  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.
  Throws:
    `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 closed
  See Also:
    `Pointer.Null`, `Pointer.NullInteger`, `Pointer.NullString`, `Pointer.NullText`, `Pointer.NullDate`, `Pointer.NullSet`

### update

    int update(String from,
               String set,
               String where,
               Object parameterValues)

  Update in the form `update("general.Person p", "p.birthdate=$1", "p=$2", params)` .
  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.
  NOTE that this method does not delete subrecords if their pointers are nullified

  Specified by:
    `update` in interface `Database`
  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"
    `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 affected
  Throws:
    `IllegalStateException` - if the connection was already closed
    `DBError` - if a fatal database error occurs
  Since:
    makumba-0.5.5

### delete

    void delete(Pointer ptr)

  Delete the record pointed by the given pointer. If the pointer is a 1-1, the pointer in the base record is set to null. All the subrecords and subsets are automatically deleted.
  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.

  Specified by:
    `delete` in interface `Database`
  Parameters:
    `ptr` - the pointer to the record to be deleted
  Throws:
    `DBError` - if a fatal database error occurs
    `IllegalStateException` - if the connection was already closed

### delete

    int delete(String from,
               String where,
               Object parameterValues)

  Delete in the form `delete("general.Person p", "p=$1", params)` .
  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.
  NOTE that this method does not delete subsets and subrecords

  Specified by:
    `delete` in interface `Database`
  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"
    `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 affected
  Throws:
    `DBError` - if a fatal database error occurs
    `IllegalStateException` - if the connection was already closed
  Since:
    makumba-0.5.5

### commit

    void commit()

  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`

### close

    void close()

  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`
  Throws:
    `DBError` - if a fatal database error occurs
    `IllegalStateException` - if the connection was already closed

### rollback

    void rollback()

  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`

### lock

    void lock(String symbol)

  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`

### unlock

    void unlock(String symbol)

  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`

### getTransactionProvider

    TransactionProvider getTransactionProvider()

  Returns the TransactionProvider which created this Transaction

### getDataSource

    String getDataSource()

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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Docs generated on 2009-02-25 14:20