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 TypeMethodDescriptionCreates a new transaction.executeQuery
(String query) Executes a query against the VDP server.executeQuery
(String query, long queryTimeout, long chunkTimeout, long chunkSize) Executes a query against the VDP server.executeQuery
(String query, Object[] parameterValues) Executes a parameterized query.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.executeVqlCommand
(String command) Executes a VQL command.executeVqlCommand
(String command, long queryTimeout) Executes a VQL command with a timeout.executeVqlCommand
(String databaseName, String command) Executes a VQL command over the given database.executeVqlCommand
(String databaseName, String command, long queryTimeout) Executes a VQL command over the given database with a timeout.getDatabaseProperty
(String name) Obtains a database property.void
joinTransaction
(StoredProcedure storedProcedure) Joins a stored procedure to the current transaction.void
Adds an entry log, with the specified level.lookupFunction
(String functionName, int arity) Obtains a handler to execute a function.lookupProcedure
(String procedureName) Obtains a stored procedure reference, which can be used to execute it.
-
Method Details
-
executeQuery
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
Executes a parameterized query.- Parameters:
query
- a VQL query that may contain one or more '?' parameter placeholdersparameterValues
- 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 placeholdersparameterValues
- 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
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
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
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
Adds an entry log, with the specified level.- Parameters:
level
- the desired log level. Should be one of these:logMessage
- the message to be logged.
-
executeUpdate
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
Executes a parameterized INSERT, UPDATE or DELETE query.- Parameters:
query
- a VQL query that may contain one or more '?' parameter placeholdersparameterValues
- 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 holdersparameterValues
- 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
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 executedcommand
- command to be executed- Returns:
- command result
- Throws:
StoredProcedureException
- If there is some error executing the command, or the parameters supplied are invalid.
-
executeVqlCommand
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 executedqueryTimeout
- 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 executedcommand
- command to be executedqueryTimeout
- query timeout configuration.- Returns:
- command result
- Throws:
StoredProcedureException
- If there is some error executing the command, or the parameters supplied are invalid.
-
executeVqlCommand
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.SystemExceptionCreates 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.
-