Package com.opencloud.slee.resources.dbquery

Interface DatabaseQueryProvider

  • public interface DatabaseQueryProvider
    Defines the provider interface used by services to send queries using the Database Query resource adaptor.

    Synchronous queries

    The procedure to send synchronous queries is:

    1. create a QueryInfo object that contains a copy of the values to set as parameters on the statement
    2. send the query using the sendQuery(QueryInfo) method on the DatabaseQueryProvider
    3. wait for the result by calling getResult() on the DatabaseFutureResult object returned from the sendQuery method
    4. handle failures by catching the exceptions thrown by getResult()
    Example Synchronous Query 
         private void syncRequest(String shortCode) {
         DatabaseFutureResult futureResult = null;
         try {
             futureResult = dbProvider.sendQuery(new SelectLongCodeQueryInfo(shortCode));
         }
         catch (NoDataSourcesAvailableException e) {
             // ... handle exception ...
             return;
         }
         try {
             ResultSet rs = futureResult.getResultSet(TIMEOUT);
             // ... handle result ...
         }
         catch (SQLException e) {
             // ... handle exception ...
         }
         catch (TimeoutException e) {
             // ... handle exception ...
         }
         catch (DatabaseQueryException e) {
             // ... handle exception ...
         }
         finally {
             futureResult.close();
         }
     }
    Example Synchronous Stored Procedure Call 
         private void syncRequest(String shortCode, String prefix) {
         DatabaseFutureResult futureResult = null;
         try {
             futureResult = dbProvider.sendQuery(new ExtendLongCodeProcedure(shortCode, prefix));
             // for ExtendLongCodeProcedure example see QueryInfo
         }
         catch (NoDataSourcesAvailableException e) {
             // ... handle exception ...
             return;
         }
         try {
             CallableStatement cstmt = (CallableStatement) futureResult.getStatement(TIMEOUT);
             String result = cstmt.getString(1);
             // ... handle result ...
         }
         catch (SQLException e) {
             // ... handle exception ...
         }
         catch (TimeoutException e) {
             // ... handle exception ...
         }
         catch (DatabaseQueryException e) {
             // ... handle exception ...
         }
         finally {
             futureResult.close();
         }
     }

    Author:
    OpenCloud

    • Method Detail

      • isDataSourceAvailable

        boolean isDataSourceAvailable()
        Check if any of the configured data sources are currently available.

        Note this does not guarantee that a subsequent sendQuery(QueryInfo) invocation will succeed.

        Returns:
        true if there are currently one or more data sources available, false if there are none.

      • sendQuery

        DatabaseFutureResult sendQuery​(QueryInfo queryInfo)
                        throws NoDataSourcesAvailableException
        Send a request without creating an activity and make the result accessible via a Future-style object. A connection will be retrieved from the pool and Connection.setAutoCommit(boolean) will be called on it with an argument of true.
        Parameters:
        queryInfo - a callback object to set the query string and parameters for the SQL statement
        Returns:
        an object that will return the query result when it is available
        Throws:
        NoDataSourcesAvailableException - if there are no configured data sources currently marked as available

      • sendQuery

        DatabaseFutureResult sendQuery​(QueryInfo queryInfo,
                               DatabaseTransaction databaseTransaction)
                        throws NoDataSourcesAvailableException,
                               DatabaseQueryException
        Send a request without creating an activity and make the result accessible via a Future-style object. If a connection is already associated with the given DatabaseTransaction it will be used, otherwise a connection will be retrieved from the pool and Connection.setAutoCommit(boolean) will be called on it with an argument of false. The same connection will then be used for future calls to this method that pass in the same transaction object.
        Parameters:
        queryInfo - a callback object to set the query string and parameters for the SQL statement
        databaseTransaction - the request will be sent on the connection associated with this transaction
        Returns:
        an object that will return the query result when it is available
        Throws:
        NoDataSourcesAvailableException - if there are no configured data sources currently marked as available
        DatabaseQueryException - if there is an error sending the request on the connection associated with the given transaction
        Since:
        1.2

      • unmarshalTransaction

        DatabaseTransaction unmarshalTransaction​(byte[] marshaledTransaction)
        Return a transaction instance for the given handle. If the resource adaptor does not have a record of the given handle this method returns null.
        Parameters:
        marshaledTransaction - a handle previously obtained by a call to DatabaseTransaction.marshal()
        Returns:
        a valid DatabaseTransaction instance or null if none exists
        Since:
        1.2