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 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:
      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.