/**
   * Counts all entities of the specified type matching the given {@link Query} instance. The SQL
   * runs as a <code>SELECT COUNT(*)</code> to ensure maximum performance.
   *
   * @param type The type of the entities which should be counted.
   * @param query The {@link Query} instance used to determine the result set which will be counted.
   * @return The number of entities of the given type which match the specified query.
   */
  public <K> int count(Class<? extends RawEntity<K>> type, Query query) throws SQLException {
    int back = -1;

    Connection conn = getProvider().getConnection();
    try {
      String sql = null;
      tableNameConverterLock.readLock().lock();
      try {
        sql = query.toSQL(type, provider, tableNameConverter, getFieldNameConverter(), true);
      } finally {
        tableNameConverterLock.readLock().unlock();
      }

      Logger.getLogger("net.java.ao").log(Level.INFO, sql);
      PreparedStatement stmt = conn.prepareStatement(sql);
      provider.setQueryStatementProperties(stmt, query);

      query.setParameters(this, stmt);

      ResultSet res = stmt.executeQuery();
      if (res.next()) {
        back = res.getInt(1);
      }
      res.close();
      stmt.close();
    } finally {
      conn.close();
    }

    return back;
  }
  /**
   * Selects all entities of the specified type which match the given <code>Query</code>. This
   * method creates a <code>PreparedStatement</code> using the <code>Query</code> instance specified
   * against the table represented by the given type. This query is then executed (with the
   * parameters specified in the query). The method then iterates through the result set and
   * extracts the specified field, mapping an entity of the given type to each row. This array of
   * entities is returned.
   *
   * @param type The type of the entities to retrieve.
   * @param field The field value to use in the creation of the entities. This is usually the
   *     primary key field of the corresponding table.
   * @param query The {@link Query} instance to use in determining the results.
   * @return An array of entities of the given type which match the specified query.
   */
  public <T extends RawEntity<K>, K> T[] find(Class<T> type, String field, Query query)
      throws SQLException {
    List<T> back = new ArrayList<T>();

    query.resolveFields(type, getFieldNameConverter());

    // <ian>
    Version version = type.getAnnotation(Version.class);
    if (version != null && !version.findInitial()) {
      // Add initial version check to exclude
      // objects that have only been created and not saved yet.
      if (query.getWhereClause() == null) {
        query.where(version.value() + " != ?", version.initial());
      } else {
        // Preserve existing WHERE clause and parameters
        String whereClause =
            new StringBuilder()
                .append(query.getWhereClause())
                .append(" AND ")
                .append(version.value())
                .append(" != ?")
                .toString();
        Object[] paramsOld = query.getWhereParams();
        Object[] paramsNew = new Object[paramsOld.length + 1];
        System.arraycopy(paramsOld, 0, paramsNew, 0, paramsOld.length);
        paramsNew[paramsNew.length - 1] = version.initial();
        query.setWhereClause(whereClause);
        query.setWhereParams(paramsNew);
      }
    }
    // </ian>

    Preload preloadAnnotation = type.getAnnotation(Preload.class);
    if (preloadAnnotation != null) {
      if (!query.getFields()[0].equals("*") && query.getJoins().isEmpty()) {
        String[] oldFields = query.getFields();
        List<String> newFields = new ArrayList<String>();

        for (String newField : preloadAnnotation.value()) {
          newField = newField.trim();

          int fieldLoc = -1;
          for (int i = 0; i < oldFields.length; i++) {
            if (oldFields[i].equals(newField)) {
              fieldLoc = i;
              break;
            }
          }

          if (fieldLoc < 0) {
            newFields.add(newField);
          } else {
            newFields.add(oldFields[fieldLoc]);
          }
        }

        if (!newFields.contains("*")) {
          for (String oldField : oldFields) {
            if (!newFields.contains(oldField)) {
              newFields.add(oldField);
            }
          }
        }

        query.setFields(newFields.toArray(new String[newFields.size()]));
      }
    }

    Connection conn = getProvider().getConnection();
    try {
      String sql = null;
      tableNameConverterLock.readLock().lock();
      try {
        sql = query.toSQL(type, provider, tableNameConverter, getFieldNameConverter(), false);
      } finally {
        tableNameConverterLock.readLock().unlock();
      }

      Logger.getLogger("net.java.ao").log(Level.INFO, sql);
      PreparedStatement stmt =
          conn.prepareStatement(sql, ResultSet.TYPE_SCROLL_INSENSITIVE, ResultSet.CONCUR_READ_ONLY);
      provider.setQueryStatementProperties(stmt, query);

      query.setParameters(this, stmt);

      ResultSet res = stmt.executeQuery();
      provider.setQueryResultSetProperties(res, query);

      while (res.next()) {
        T entity =
            peer(
                type,
                Common.getPrimaryKeyType(type)
                    .pullFromDatabase(this, res, Common.getPrimaryKeyClassType(type), field));
        CacheLayer cacheLayer = getProxyForEntity(entity).getCacheLayer(entity);

        for (String cacheField : query.getCanonicalFields(type, fieldNameConverter)) {
          cacheLayer.put(cacheField, res.getObject(cacheField));
        }

        back.add(entity);
      }
      res.close();
      stmt.close();
    } finally {
      conn.close();
    }

    return back.toArray((T[]) Array.newInstance(type, back.size()));
  }