be.SIRAPRISE.client

Class DBTransaction

java.lang.Object

be.SIRAPRISE.client.DBTransaction

public class DBTransaction
extends java.lang.Object

A DBTransaction represents the transaction that is active on some DBConnection.

Author:

Erwin Smout

Method Summary

Modifier and Type	Method and Description
void	commit() Commits this non-autocommit transaction.
Relation	compileAndCacheQuery(java.lang.String query) Deprecated. - support for the COMPILE/CACHE commands has been dropped. Replace with INQUIRE __EXPRESSIONINFO(query).
Relation	compileQuery(java.lang.String query) Deprecated. - support for the COMPILE command has been dropped. Replace with INQUIRE __EXPRESSIONINFO(query).
void	end(boolean commit) Ends the transaction, issuing either a commit or a rollback.
Relation	execDmlCommand(java.lang.String cmd) Deprecated. - replace with execServerCommand(ServerCommand.getCommandObjectFrom(cmd))
Relation	execDmlCommandAndEndTransaction(java.lang.String cmd) Deprecated. - replace with execServerCommand(ServerCommand.getCommandFrom(cmd))
Relation	execMultipleStatementAndEndTransaction(java.lang.String[] commands) Deprecated. - replace with execServerCommandAndEndTransaction(new ServerMultipleAssignmentCommand(...))
Relation[]	execQueries(java.lang.String... expressions) Executes a series of inquire commands on the server.
Relation[]	execQueriesAndEndTransaction(java.lang.String... expressions) Executes a series of inquire commands on the server.
Relation	execQuery(java.lang.String expression) Executes an inquire command on the server.
Relation	execQuery(java.lang.String expression, java.util.List<java.lang.String> orderByAttributeNames) Executes an inquire command on the server.
Relation	execQueryAndEndTransaction(java.lang.String expression) Executes an inquire command on the server.
Relation	execQueryAndEndTransaction(java.lang.String expression, java.util.List<java.lang.String> orderByAttributeNames) Executes an inquire command on the server.
Relation	execServerCommand(ServerCommand serverCommand) Sends a command to the server and returns the result obtained.
Relation	execServerCommandAndEndTransaction(ServerCommand serverCommand) Sends a command to the server and returns the result obtained.
DBTransaction	getParentTransaction() Gets The "parent" transaction of this nested transaction, or null if this is not a nested transaction
long	getTransactionID() Gets The numerical server-side ID of the started transaction, or -1 if the server is pre 1.2
boolean	isAutoCommit() Gets the flag indicating whether all DML statements executed in the transaction should be automatically committed
boolean	isReadOnly() Gets the Flag indicating whether the transaction is read-only
void	rollback() Commits this non-autocommit transaction.
DBTransaction	savePoint() Takes a savepoint in the current transaction.
DBTransaction	startNestedTransaction(boolean newAutoCommit, boolean readOnly) Starts a nested transaction within this transaction.
java.lang.String	toString()

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Detail

commit

public final void commit()
                  throws ConnectionClosedException

Commits this non-autocommit transaction. If the transaction is auto-commit, this method is a NOP.

Throws:

ConnectionClosedException - If the connection was closed due to an I/O error that occurred during communication with the server, or if the commit failed.

compileAndCacheQuery

@Deprecated
public final Relation compileAndCacheQuery(java.lang.String query)
                                                throws ConnectionClosedException,
                                                       ErrorMessageException

Deprecated. - support for the COMPILE/CACHE commands has been dropped. Replace with INQUIRE __EXPRESSIONINFO(query).

Sends a query expression to the server for compilation-and-caching.

Parameters:

query - the query to be compiled-and-cached, in textual form.

Returns:

the result of the compilation. That result is a relation with the following attributes :

• QUERYID(LONG(...)) The internal ID of the compiled query, by which the query can later be referenced
• HEADING(RELATION(...)) The description of the heading of the relation as it will be output by the query
• PARMS(RELATION(...)) The description of all parameters required by the query

The heading of the 'HEADING' relation is as follows :

• ATTRIBUTENAME(NAME(...)) The name of an attribute in the output of the query
• TYPENAME(NAME(...)) The name of the type of that attribute in the output of the query

The heading of the 'PARMS' relation is as follows :

• PARAMETERNAME(NAME(...)) The name of a parameter required by the query
• TYPENAME(NAME(...)) The name of the type of that parameter

Throws:

ConnectionClosedException - If the connection was closed due to an I/O error that occurred during communication with the server

ErrorMessageException - If the response obtained from the server is not a commit confirmation, but an error response instead.

compileQuery

@Deprecated
public final Relation compileQuery(java.lang.String query)
                                        throws ConnectionClosedException,
                                               ErrorMessageException

Deprecated. - support for the COMPILE command has been dropped. Replace with INQUIRE __EXPRESSIONINFO(query).

Sends a query expression to the server for verification only.

Parameters:

query - the query to be verified, in textual form.

Returns:

the result of the verification. That result is a relation with the following attributes :

1. HEADING(RELATION(...)) The description of the heading of the relation as it will be output by the query
2. PARMS(RELATION(...)) The description of all parameters required by the query

The heading of the 'HEADING' relation is as follows :

1. ATTRIBUTENAME(NAME(...)) The name of an attribute in the output of the query
2. TYPENAME(NAME(...)) The name of the type of that attribute in the output of the query

The heading of the 'PARMS' relation is as follows :

1. PARAMETERNAME(NAME(...)) The name of a parameter required by the query
2. TYPENAME(NAME(...)) The name of the type of that parameter

Throws:

ConnectionClosedException - If the connection was closed due to an I/O error that occurred during communication with the server

ErrorMessageException - If the response obtained from the server is not a commit confirmation, but an error response instead.

end

public final void end(boolean commit)
               throws ConnectionClosedException

Ends the transaction, issuing either a commit or a rollback.

Parameters:

commit - true if the transaction is to be committed, false if it is to be rolled back.

Throws:

ConnectionClosedException - If the connection was closed due to an I/O error that occurred during communication with the server

execDmlCommand

@Deprecated
public final Relation execDmlCommand(java.lang.String cmd)
                                          throws ConnectionClosedException,
                                                 ErrorMessageException

Deprecated. - replace with execServerCommand(ServerCommand.getCommandObjectFrom(cmd))

Sends a command to the server and returns the result obtained.

Parameters:

cmd - the command to be executed, in textual form.

Returns:

the result of the command.

Throws:

ConnectionClosedException - If the connection was closed due to an I/O error that occurred during communication with the server

ErrorMessageException - If the response obtained from the server is not a commit confirmation, but an error response instead.

execServerCommandAndEndTransaction

public final Relation execServerCommandAndEndTransaction(ServerCommand serverCommand)
                                                  throws ConnectionClosedException,
                                                         ErrorMessageException

Sends a command to the server and returns the result obtained.

Parameters:

serverCommand - the command to be executed.

Returns:

the result of the command.

Throws:

ConnectionClosedException - If the connection was closed due to an I/O error that occurred during communication with the server

ErrorMessageException - If the response obtained from the server is not a commit confirmation, but an error response instead.

execDmlCommandAndEndTransaction

@Deprecated
public final Relation execDmlCommandAndEndTransaction(java.lang.String cmd)
                                                           throws ConnectionClosedException,
                                                                  ErrorMessageException

Deprecated. - replace with execServerCommand(ServerCommand.getCommandFrom(cmd))

Sends a command to the server and returns the result obtained. After execution of the command, the transaction is committed and ended.

Parameters:

cmd - the command to be executed, in textual form.

Returns:

The result of executing the command. Null if the command is an assignment command.

Throws:

ConnectionClosedException - If the connection was closed due to an I/O error that occurred during communication with the server

ErrorMessageException - If the response obtained from the server is not a commit confirmation, but an error response instead.

execMultipleStatementAndEndTransaction

@Deprecated
public final Relation execMultipleStatementAndEndTransaction(java.lang.String[] commands)
                                                                  throws ConnectionClosedException,
                                                                         ErrorMessageException

Deprecated. - replace with execServerCommandAndEndTransaction(new ServerMultipleAssignmentCommand(...))

Executes a series of single-assignment commands as a multiple-assignment command.

Parameters:

commands - The single-assignment commands to be executed. Execution is in the obvious order, and thus not randomly, or in reverse order, or whatever.

Returns:

the DBResponse obtained.

Throws:

ConnectionClosedException - If the connection was closed due to an I/O error that occurred during communication with the server

ErrorMessageException - If the response obtained from the server is not a commit confirmation, but an error response instead.

execQueries

public final Relation[] execQueries(java.lang.String... expressions)
                             throws ConnectionClosedException,
                                    ErrorMessageException

Executes a series of inquire commands on the server.

Parameters:

expressions - The expressions of the relational algebra to be inquired.

Returns:

response A DBResponse array holding the values of the corresponding queried expressions.

Throws:

ConnectionClosedException - If the connection was closed due to an I/O error that occurred during communication with the server

ErrorMessageException - If the response obtained from the server is not a commit confirmation, but an error response instead.

execQueriesAndEndTransaction

public final Relation[] execQueriesAndEndTransaction(java.lang.String... expressions)
                                              throws ConnectionClosedException,
                                                     ErrorMessageException

Executes a series of inquire commands on the server.

Parameters:

expressions - The expressions of the relational algebra to be inquired.

Returns:

response A DBResponse array holding the values of the corresponding queried expressions.

Throws:

ConnectionClosedException - If the connection was closed due to an I/O error that occurred during communication with the server

ErrorMessageException - If the response obtained from the server is not a commit confirmation, but an error response instead.

execQuery

public final Relation execQuery(java.lang.String expression)
                         throws ConnectionClosedException,
                                ErrorMessageException

Executes an inquire command on the server. If the result indicates any kind of error, then the connection will be closed.

Parameters:

expression - The expression of the relational algebra to be inquired.

Returns:

response A DBResponse holding the value of the queried expression.

Throws:

ConnectionClosedException - If the connection was closed due to an I/O error that occurred during communication with the server

ErrorMessageException - If the response obtained from the server is not a commit confirmation, but an error response instead.

execQuery

public final Relation execQuery(java.lang.String expression,
                                java.util.List<java.lang.String> orderByAttributeNames)
                         throws ConnectionClosedException,
                                ErrorMessageException

Executes an inquire command on the server. If the result indicates any kind of error, then the connection will be closed.

Parameters:

expression - The expression of the relational algebra to be inquired.

orderByAttributeNames - The spec of the requested ordering for the tuples in the resulting relation

Returns:

response A DBResponse holding the value of the queried expression.

Throws:

ConnectionClosedException - If the connection was closed due to an I/O error that occurred during communication with the server

ErrorMessageException - If the response obtained from the server is not a commit confirmation, but an error response instead.

execQueryAndEndTransaction

public final Relation execQueryAndEndTransaction(java.lang.String expression)
                                          throws ConnectionClosedException,
                                                 ErrorMessageException

Executes an inquire command on the server. Optionally closes the connection immediately after succesfull execution of the query. If the result indicates any kind of error, then the connection will be closed.

Parameters:

expression - The expression of the relational algebra to be inquired.

Returns:

response A DBResponse holding the value of the queried expression.

Throws:

ConnectionClosedException - If the connection was closed due to an I/O error that occurred during communication with the server

ErrorMessageException - If the response obtained from the server is not a commit confirmation, but an error response instead.

execQueryAndEndTransaction

public final Relation execQueryAndEndTransaction(java.lang.String expression,
                                                 java.util.List<java.lang.String> orderByAttributeNames)
                                          throws ConnectionClosedException,
                                                 ErrorMessageException

Executes an inquire command on the server. Optionally closes the connection immediately after succesfull execution of the query. If the result indicates any kind of error, then the connection will be closed.

Parameters:

expression - The expression of the relational algebra to be inquired.

orderByAttributeNames - The spec of the requested ordering for the tuples in the resulting relation

Returns:

response A DBResponse holding the value of the queried expression.

Throws:

ConnectionClosedException - If the connection was closed due to an I/O error that occurred during communication with the server

ErrorMessageException - If the response obtained from the server is not a commit confirmation, but an error response instead.

execServerCommand

public final Relation execServerCommand(ServerCommand serverCommand)
                                 throws ConnectionClosedException,
                                        ErrorMessageException

Sends a command to the server and returns the result obtained.

Parameters:

serverCommand - the command to be executed.

Returns:

the result of the command.

Throws:

ConnectionClosedException - If the connection was closed due to an I/O error that occurred during communication with the server

ErrorMessageException - If the response obtained from the server is not a commit confirmation, but an error response instead.

getParentTransaction

public final DBTransaction getParentTransaction()

Gets The "parent" transaction of this nested transaction, or null if this is not a nested transaction

Returns:

The "parent" transaction of this nested transaction, or null if this is not a nested transaction

getTransactionID

public final long getTransactionID()

Gets The numerical server-side ID of the started transaction, or -1 if the server is pre 1.2

Returns:

The numerical server-side ID of the started transaction, or -1 if the server is pre 1.2

isAutoCommit

public final boolean isAutoCommit()

Gets the flag indicating whether all DML statements executed in the transaction should be automatically committed

Returns:

true if all DML statements executed in the transaction should be automatically committed

isReadOnly

public final boolean isReadOnly()

Gets the Flag indicating whether the transaction is read-only

Returns:

Flag indicating whether the transaction is read-only

rollback

public final void rollback()
                    throws ConnectionClosedException

Commits this non-autocommit transaction. If the transaction is auto-commit, this method is a NOP.

Throws:

ConnectionClosedException - If the connection was closed due to an I/O error that occurred during communication with the server

savePoint

public final DBTransaction savePoint()
                              throws ErrorMessageException,
                                     ConnectionClosedException

Takes a savepoint in the current transaction. Rolling back to this savepoint is done by invoking the rollback() method on the DBTransaction object returned by this method invocation. Rolling back to this savepoint AND discarding it, is done by invoking the endTransaction(false) method on the DBTransaction object returned from this method.

Returns:

A DBTransaction object representing the new "nested" transaction that is started on the server side and that will span all activities done on the server from this point on.

Throws:

ConnectionClosedException - If the connection was closed due to an I/O error that occurred during communication with the server

ErrorMessageException - If the response obtained from the server is not a confirmation, but an error response instead.

startNestedTransaction

public final DBTransaction startNestedTransaction(boolean newAutoCommit,
                                                  boolean readOnly)
                                           throws ErrorMessageException,
                                                  ConnectionClosedException

Starts a nested transaction within this transaction.

Parameters:

newAutoCommit - The autocommit setting for the new transaction nested inside the current one

readOnly - The readOnly setting for the new transaction nested inside the current one. May only be false if this transaction is not read-only too.

Returns:

A DBTransaction object representing the new "nested" transaction that is started on the server side and that will span all activities done on the server from this point on.

Throws:

ConnectionClosedException - If the connection was closed due to an I/O error that occurred during communication with the server

ErrorMessageException - If the response obtained from the server is not a confirmation, but an error response instead.

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object