Package com.denodo.vdb.engine.storedprocedure

Interface DatabaseEnvironment

public interface DatabaseEnvironment

Interface which defines utility methods accessible from the stored procedures, and used to communicate with the VDP server: obtains database properties, logging, query execution, procedure and function lookup...

For the methods executeQuery and executeUpdate that support parameters (the ones that have the parameter Object[] parameterValues), take the following into account:

• When you execute them, the Server replaces the place holders ("?") of the query with the values of the parameters. Then, it executes the query.
• The benefit of using these methods is that you do not need to know how to format the parameters. With integers and string is easy, but it is more complex with dates. It is easier to pass the parameters as objects and let the Server process them appropriately.
• The number of elements in the array parameterValues has to match the number of "?" in the query.
• Do not surround the place holders with single quotes, even if the value is a text.

For example,

 SELECT * FROM customer WHERE last_name = ?
 

The Virtual DataPort server will format each value depending on the class of the object. For example:

• If the object is a number (java.lang.Double, java.lang.Integer, etc.), it replaces the placeholder with the number, without quotes.
• If the object is a java.lang.String, it surrounds the value with single quotes.
• ...

Method Summary

Modifier and Type	Method	Description
Transaction	createTransaction()	Creates a new transaction.
ResultSet	executeQuery(String query)	Executes a query against the VDP server.
ResultSet	executeQuery(String query, long queryTimeout, long chunkTimeout, long chunkSize)	Executes a query against the VDP server.
ResultSet	executeQuery(String query, Object[] parameterValues)	Executes a parameterized query.
ResultSet	executeQuery(String query, Object[] parameterValues, long queryTimeout, long chunkTimeout, long chunkSize)	Executes a parameterized query specifying the timeouts.
int	executeUpdate(String query)	Executes an INSERT, UPDATE or DELETE query.
int	executeUpdate(String query, Object[] parameterValues)	Executes a parameterized INSERT, UPDATE or DELETE query.
int	executeUpdate(String query, Object[] parameterValues, long queryTimeout)	Executes a parameterized INSERT, UPDATE or DELETE query specifying the timeouts.
String	executeVqlCommand(String command)	Executes a VQL command.
String	executeVqlCommand(String command, long queryTimeout)	Executes a VQL command with a timeout.
String	executeVqlCommand(String databaseName, String command)	Executes a VQL command over the given database.
String	executeVqlCommand(String databaseName, String command, long queryTimeout)	Executes a VQL command over the given database with a timeout.
String	getDatabaseProperty(String name)	Obtains a database property.
void	joinTransaction(StoredProcedure storedProcedure)	Joins a stored procedure to the current transaction.
void	log(int level, String logMessage)	Adds an entry log, with the specified level.
DatabaseFunction	lookupFunction(String functionName, int arity)	Obtains a handler to execute a function.
StoredProcedureExecutor	lookupProcedure(String procedureName)	Obtains a stored procedure reference, which can be used to execute it.

Method Details

executeQuery

ResultSet executeQuery(String query)
                throws StoredProcedureException

Executes a query against the VDP server.

Parameters:

query - the VQL query.

Returns:

a JDBC ResultSet.

Throws:

StoredProcedureException - If there is some error executing the query.

executeQuery

ResultSet executeQuery(String query,
 long queryTimeout,
 long chunkTimeout,
 long chunkSize)
                throws StoredProcedureException

Executes a query against the VDP server.

Parameters:

query - the VQL query.

queryTimeout - query timeout configuration.

chunkTimeout - chunk timeout configuration.

chunkSize - chunk size configuration.

Returns:

a JDBC ResultSet.

Throws:

StoredProcedureException - If there is some error executing the query.

executeQuery

ResultSet executeQuery(String query,
 Object[] parameterValues)
                throws StoredProcedureException

Executes a parameterized query.

Parameters:

query - a VQL query that may contain one or more '?' parameter placeholders

parameterValues - the list of values to be replaced in the query. The number of elements in this array has to match the number of "?" in the query.

Returns:

a JDBC ResultSet.

Throws:

StoredProcedureException - If there is some error executing the query, or the parameters supplied are invalid.

executeQuery

ResultSet executeQuery(String query,
 Object[] parameterValues,
 long queryTimeout,
 long chunkTimeout,
 long chunkSize)
                throws StoredProcedureException

Executes a parameterized query specifying the timeouts.

Parameters:

query - a VQL query that may contain one or more '?' parameter placeholders

parameterValues - the list of values to be replaced in the query. The number of elements in this array has to match the number of "?" in the query.

queryTimeout - query timeout configuration.

chunkTimeout - chunk timeout configuration.

chunkSize - chunk size configuration.

Returns:

a JDBC ResultSet.

Throws:

StoredProcedureException - If there is some error executing the query, or the parameters supplied are invalid.

lookupProcedure

StoredProcedureExecutor lookupProcedure(String procedureName)
                                 throws StoredProcedureException

Obtains a stored procedure reference, which can be used to execute it.

Parameters:

procedureName - the name of the stored procedure.

Returns:

the a reference to the stored procedure.

Throws:

StoredProcedureException - If there is some error obtaining the procedure.

lookupFunction

DatabaseFunction lookupFunction(String functionName,
 int arity)
                         throws StoredProcedureException

Obtains a handler to execute a function.

Parameters:

functionName - the name of the function.

arity - the arity of the function.

Returns:

a function handler.

Throws:

StoredProcedureException - If there is some error obtaining the function.

getDatabaseProperty

String getDatabaseProperty(String name)
                    throws StoredProcedureException

Obtains a database property.

Parameters:

name - the name of the property. The available properties are:

• CURRENT_USER: The user executing the stored procedure.
• CURRENT_DATABASE: The database where the stored procedure is being executed.

Returns:

the value of the property

Throws:

StoredProcedureException - If there is some error retrieving the property

log

void log(int level,
 String logMessage)

Adds an entry log, with the specified level.

Parameters:

level - the desired log level. Should be one of these:

• StoredProcedureExecutor.LOG_TRACE
• StoredProcedureExecutor.LOG_DEBUG
• StoredProcedureExecutor.LOG_INFO
• StoredProcedureExecutor.LOG_WARN
• StoredProcedureExecutor.LOG_ERROR
• StoredProcedureExecutor.LOG_FATAL

logMessage - the message to be logged.

executeUpdate

int executeUpdate(String query)
           throws StoredProcedureException

Executes an INSERT, UPDATE or DELETE query.

Parameters:

query - the query to be executed.

Returns:

the number of rows affected by the query.

Throws:

StoredProcedureException - If there is an error during the execution of the query.

executeUpdate

int executeUpdate(String query,
 Object[] parameterValues)
           throws StoredProcedureException

Executes a parameterized INSERT, UPDATE or DELETE query.

Parameters:

query - a VQL query that may contain one or more '?' parameter placeholders

parameterValues - the list of values to be replaced in the query. The number of elements in this array has to match the number of "?" in the query.

Returns:

a JDBC ResultSet.

Throws:

StoredProcedureException - If there is some error executing the query, or the parameters supplied are invalid.

executeUpdate

int executeUpdate(String query,
 Object[] parameterValues,
 long queryTimeout)
           throws StoredProcedureException

Executes a parameterized INSERT, UPDATE or DELETE query specifying the timeouts.

Parameters:

query - a VQL query that may contain one or more '?' parameter place holders

parameterValues - the list of values to be replaced in the query. The number of elements in this array has to match the number of "?" in the query.

queryTimeout - query timeout configuration.

Returns:

number of rows affected by the execution of this query.

Throws:

StoredProcedureException - If there is an error executing the query, or the parameters supplied are invalid.

executeVqlCommand

String executeVqlCommand(String databaseName,
 String command)
                  throws StoredProcedureException

Executes a VQL command over the given database. Important: We advise against invoking this method to create/modify/delete elements if this stored procedure is going to run on a production environment.

Parameters:

databaseName - database where the command is executed

command - command to be executed

Returns:

command result

Throws:

StoredProcedureException - If there is some error executing the command, or the parameters supplied are invalid.

executeVqlCommand

String executeVqlCommand(String command,
 long queryTimeout)
                  throws StoredProcedureException

Executes a VQL command with a timeout. Important: We advise against invoking this method to create/modify/delete elements if this stored procedure is going to run on a production environment.

Parameters:

command - command to be executed

queryTimeout - query timeout configuration.

Returns:

command result

Throws:

StoredProcedureException - If there is some error executing the command, or the parameters supplied are invalid.

executeVqlCommand

String executeVqlCommand(String databaseName,
 String command,
 long queryTimeout)
                  throws StoredProcedureException

Executes a VQL command over the given database with a timeout. Important: We advise against invoking this method to create/modify/delete elements if this stored procedure is going to run on a production environment.

Parameters:

databaseName - database where the command is executed

command - command to be executed

queryTimeout - query timeout configuration.

Returns:

command result

Throws:

StoredProcedureException - If there is some error executing the command, or the parameters supplied are invalid.

executeVqlCommand

String executeVqlCommand(String command)
                  throws StoredProcedureException

Executes a VQL command. Important: We advise against invoking this method to create/modify/delete elements if this stored procedure is going to run on a production environment.

Parameters:

command - command to be executed

Returns:

command result

Throws:

StoredProcedureException - If there is some error executing the command, or the parameters supplied are invalid.

createTransaction

Transaction createTransaction()
                       throws javax.transaction.NotSupportedException,
javax.transaction.SystemException

Creates a new transaction.

Returns:

an user transaction

Throws:

javax.transaction.NotSupportedException - If a transaction has already been started.

javax.transaction.SystemException - If there is an error starting the transaction.

joinTransaction

void joinTransaction(StoredProcedure storedProcedure)
              throws javax.transaction.RollbackException,
javax.transaction.SystemException

Joins a stored procedure to the current transaction.

Parameters:

storedProcedure - the procedure to be joined to the transaction.

Throws:

javax.transaction.RollbackException - If there is an error joining the transaction.

javax.transaction.SystemException - If there is an error joining the transaction.