/**
  * Called by preAllocateIds when we know that a large number of Id's is going to be needed
  * shortly.
  */
 protected void loadLargeAllocation(final int allocateSize) {
   // preAllocateIds was called with a relatively large batchSize
   // so we will just go ahead and load those anyway in background
   backgroundExecutor.execute(
       new Runnable() {
         public void run() {
           loadMoreIds(allocateSize, null);
         }
       });
 }
  /** Load another batch of Id's using a background thread. */
  protected void loadBatchInBackground() {

    // single threaded processing...
    synchronized (backgroundLoadMonitor) {
      if (currentlyBackgroundLoading > 0) {
        // skip as already background loading
        logger.trace("... skip background sequence load (another load in progress)");
        return;
      }

      currentlyBackgroundLoading = batchSize;

      backgroundExecutor.execute(
          new Runnable() {
            public void run() {
              loadMoreIds(batchSize, null);
              synchronized (backgroundLoadMonitor) {
                currentlyBackgroundLoading = 0;
              }
            }
          });
    }
  }
  /** Find a list/map/set of beans. */
  public <T> BeanCollection<T> findMany(OrmQueryRequest<T> request) {

    // flag indicating whether we need to close the resources...
    boolean useBackgroundToContinueFetch = false;

    CQuery<T> cquery = queryBuilder.buildQuery(request);
    request.setCancelableQuery(cquery);

    try {
      if (!cquery.prepareBindExecuteQuery()) {
        // query has been cancelled already
        logger.trace("Future fetch already cancelled");
        return null;
      }

      if (request.isLogSql()) {
        logSql(cquery);
      }

      BeanCollection<T> beanCollection = cquery.readCollection();

      BeanCollectionTouched collectionTouched = request.getQuery().getBeanCollectionTouched();
      if (collectionTouched != null) {
        // register a listener that wants to be notified when the
        // bean collection is first used
        beanCollection.setBeanCollectionTouched(collectionTouched);
      }

      if (cquery.useBackgroundToContinueFetch()) {
        // stop the request from putting connection back into pool
        // before background fetching is finished.
        request.setBackgroundFetching();
        useBackgroundToContinueFetch = true;
        BackgroundFetch fetch = new BackgroundFetch(cquery);

        FutureTask<Integer> future = new FutureTask<Integer>(fetch);
        beanCollection.setBackgroundFetch(future);
        backgroundExecutor.execute(future);
      }

      if (request.isLogSummary()) {
        logFindManySummary(cquery);
      }

      request.executeSecondaryQueries(defaultSecondaryQueryBatchSize);

      return beanCollection;

    } catch (SQLException e) {
      throw cquery.createPersistenceException(e);

    } finally {
      if (useBackgroundToContinueFetch) {
        // left closing resources to BackgroundFetch...
      } else {
        if (cquery != null) {
          cquery.close();
        }
        if (request.getQuery().isFutureFetch()) {
          // end the transaction for futureFindIds
          // as it had it's own transaction
          logger.debug("Future fetch completed!");
          request.getTransaction().end();
        }
      }
    }
  }