/*
    * Licensed to the Apache Software Foundation (ASF) under one or more
    * contributor license agreements.  See the NOTICE file distributed with
    * this work for additional information regarding copyright ownership.
    * The ASF licenses this file to You under the Apache License, Version 2.0
    * (the "License"); you may not use this file except in compliance with
    * the License.  You may obtain a copy of the License at
    *
    *      http://www.apache.org/licenses/LICENSE-2.0
   *
   * Unless required by applicable law or agreed to in writing, software
   * distributed under the License is distributed on an "AS IS" BASIS,
   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   * See the License for the specific language governing permissions and
   * limitations under the License.
   */
  
  package org.apache.commons.beanutils2.sql;
  
  import java.sql.ResultSet;
  import java.sql.SQLException;
  import java.util.ArrayList;
  import java.util.List;
  import java.util.Objects;
  
  import org.apache.commons.beanutils2.BasicDynaBean;
  import org.apache.commons.beanutils2.DynaBean;
  import org.apache.commons.beanutils2.DynaClass;
  import org.apache.commons.beanutils2.DynaProperty;
  
  /**
   * <p>
   * Implements {@link DynaClass} to create an in-memory collection of {@link DynaBean}s representing the results of an SQL query. Once the {@link DynaClass}
   * instance has been created, the JDBC {@code ResultSet} and {@code Statement} on which it is based can be closed, and the underlying {@code Connection} can be
   * returned to its connection pool (if you are using one).
   * </p>
   *
   * <p>
   * The normal usage pattern is something like:
   * </p>
   *
   * <pre>
   *   Connection conn = ...;  // Acquire connection from pool
   *   Statement stmt = conn.createStatement();
   *   ResultSet rs = stmt.executeQuery("SELECT ...");
   *   RowSetDynaClass rsdc = new RowSetDynaClass(rs);
   *   rs.close();
   *   stmt.close();
   *   ...;                    // Return connection to pool
   *   List rows = rsdc.getRows();
   *   ...;                   // Process the rows as desired
   * </pre>
   *
   * <p>
   * Each column in the result set will be represented as a {@link DynaBean} property of the corresponding name (optionally forced to lower case for portability).
   * There will be one {@link DynaBean} in the {@code List</code> returned by <code>getRows()} for each row in the original {@code ResultSet}.
   * </p>
   *
   * <p>
   * In general, instances of {@link RowSetDynaClass} can be serialized and deserialized, which will automatically include the list of {@link DynaBean}s
   * representing the data content. The only exception to this rule would be when the underlying property values that were copied from the {@code ResultSet}
   * originally cannot themselves be serialized. Therefore, a {@link RowSetDynaClass} makes a very convenient mechanism for transporting data sets to remote
   * Java-based application components.
   * </p>
   */
  public class RowSetDynaClass extends AbstractJdbcDynaClass {
  
      /**
       * <p>
       * Limits the size of the returned list. The call to {@code getRows()} will return at most limit number of rows. If less than or equal to 0, does not limit
       * the size of the result.
       */
      protected int limit = -1;
  
      /**
       * <p>
       * The list of {@link DynaBean}s representing the contents of the original {@code ResultSet} on which this {@link RowSetDynaClass} was based.
       * </p>
       */
      protected List<DynaBean> rows = new ArrayList<>();
  
      /**
       * <p>
       * Constructs a new {@link RowSetDynaClass} for the specified {@code ResultSet}. The property names corresponding to column names in the result set will be
       * lower cased.
       * </p>
       *
       * @param resultSet The result set to be wrapped
       * @throws NullPointerException if {@code resultSet} is {@code null}
       * @throws SQLException         if the metadata for this result set cannot be introspected
       */
      public RowSetDynaClass(final ResultSet resultSet) throws SQLException {
          this(resultSet, true, -1);
      }
  
      /**
       * <p>
       * Constructs a new {@link RowSetDynaClass} for the specified {@code ResultSet}. The property names corresponding to the column names in the result set will
       * be lower cased or not, depending on the specified {@code lowerCase} value.
      * </p>
      *
      * If {@code limit</code> is not less than 0, max <code>limit} number of rows will be copied into the resultset.
      *
      *
      * @param resultSet The result set to be wrapped
      * @param lowerCase Should property names be lower cased?
      * @throws NullPointerException if {@code resultSet} is {@code null}
      * @throws SQLException         if the metadata for this result set cannot be introspected
      */
     public RowSetDynaClass(final ResultSet resultSet, final boolean lowerCase) throws SQLException {
         this(resultSet, lowerCase, -1);
     }
 
     /**
      * <p>
      * Constructs a new {@link RowSetDynaClass} for the specified {@code ResultSet}. The property names corresponding to the column names in the result set will
      * be lower cased or not, depending on the specified {@code lowerCase} value.
      * </p>
      *
      * <p>
      * <strong>WARNING</strong> - If you specify {@code false} for {@code lowerCase}, the returned property names will exactly match the column names returned
      * by your JDBC driver. Because different drivers might return column names in different cases, the property names seen by your application will vary
      * depending on which JDBC driver you are using.
      * </p>
      *
      * @param resultSet      The result set to be wrapped
      * @param lowerCase      Should property names be lower cased?
      * @param useColumnLabel true if the column label should be used, otherwise false
      * @throws NullPointerException if {@code resultSet} is {@code null}
      * @throws SQLException         if the metadata for this result set cannot be introspected
      * @since 1.8.3
      */
     public RowSetDynaClass(final ResultSet resultSet, final boolean lowerCase, final boolean useColumnLabel) throws SQLException {
         this(resultSet, lowerCase, -1, useColumnLabel);
     }
 
     /**
      * <p>
      * Constructs a new {@link RowSetDynaClass} for the specified {@code ResultSet}. The property names corresponding to the column names in the result set will
      * be lower cased or not, depending on the specified {@code lowerCase} value.
      * </p>
      *
      * <p>
      * <strong>WARNING</strong> - If you specify {@code false} for {@code lowerCase}, the returned property names will exactly match the column names returned
      * by your JDBC driver. Because different drivers might return column names in different cases, the property names seen by your application will vary
      * depending on which JDBC driver you are using.
      * </p>
      *
      * @param resultSet The result set to be wrapped
      * @param lowerCase Should property names be lower cased?
      * @param limit     Maximum limit for the {@code List} of {@link DynaBean}
      * @throws NullPointerException if {@code resultSet} is {@code null}
      * @throws SQLException         if the metadata for this result set cannot be introspected
      */
     public RowSetDynaClass(final ResultSet resultSet, final boolean lowerCase, final int limit) throws SQLException {
         this(resultSet, lowerCase, limit, false);
     }
 
     /**
      * <p>
      * Constructs a new {@link RowSetDynaClass} for the specified {@code ResultSet}. The property names corresponding to the column names in the result set will
      * be lower cased or not, depending on the specified {@code lowerCase} value.
      * </p>
      *
      * <p>
      * <strong>WARNING</strong> - If you specify {@code false} for {@code lowerCase}, the returned property names will exactly match the column names returned
      * by your JDBC driver. Because different drivers might return column names in different cases, the property names seen by your application will vary
      * depending on which JDBC driver you are using.
      * </p>
      *
      * @param resultSet      The result set to be wrapped
      * @param lowerCase      Should property names be lower cased?
      * @param limit          Maximum limit for the {@code List} of {@link DynaBean}
      * @param useColumnLabel true if the column label should be used, otherwise false
      * @throws NullPointerException if {@code resultSet} is {@code null}
      * @throws SQLException         if the metadata for this result set cannot be introspected
      * @since 1.8.3
      */
     @SuppressWarnings("resource") // resultSet is not allocated here
     public RowSetDynaClass(final ResultSet resultSet, final boolean lowerCase, final int limit, final boolean useColumnLabel) throws SQLException {
         Objects.requireNonNull(resultSet, "resultSet");
         this.lowerCase = lowerCase;
         this.limit = limit;
         setUseColumnLabel(useColumnLabel);
         introspect(resultSet);
         copy(resultSet);
     }
 
     /**
      * <p>
      * Constructs a new {@link RowSetDynaClass} for the specified {@code ResultSet}. The property names corresponding to column names in the result set will be
      * lower cased.
      * </p>
      *
      * If {@code limit</code> is not less than 0, max <code>limit} number of rows will be copied into the list.
      *
      * @param resultSet The result set to be wrapped
      * @param limit     The maximum for the size of the result.
      * @throws NullPointerException if {@code resultSet} is {@code null}
      * @throws SQLException         if the metadata for this result set cannot be introspected
      */
     public RowSetDynaClass(final ResultSet resultSet, final int limit) throws SQLException {
         this(resultSet, true, limit);
     }
 
     /**
      * <p>
      * Copy the column values for each row in the specified {@code ResultSet} into a newly created {@link DynaBean}, and add this bean to the list of
      * {@link DynaBean}s that will later by returned by a call to {@code getRows()}.
      * </p>
      *
      * @param resultSet The {@code ResultSet} whose data is to be copied
      * @throws SQLException if an error is encountered copying the data
      */
     protected void copy(final ResultSet resultSet) throws SQLException {
         int cnt = 0;
         while (resultSet.next() && (limit < 0 || cnt++ < limit)) {
             final DynaBean bean = createDynaBean();
             for (final DynaProperty property : properties) {
                 final String name = property.getName();
                 final Object value = getObject(resultSet, name);
                 bean.set(name, value);
             }
             rows.add(bean);
         }
     }
 
     /**
      * <p>
      * Create and return a new {@link DynaBean} instance to be used for representing a row in the underlying result set.
      * </p>
      *
      * @return A new {@code DynaBean} instance
      */
     protected DynaBean createDynaBean() {
         return new BasicDynaBean(this);
     }
 
     /**
      * <p>
      * Gets a {@code List} containing the {@link DynaBean}s that represent the contents of each {@code Row} from the {@code ResultSet} that was the basis of
      * this {@link RowSetDynaClass} instance. These {@link DynaBean}s are disconnected from the database itself, so there is no problem with modifying the
      * contents of the list, or the values of the properties of these {@link DynaBean}s. However, it is the application's responsibility to persist any such
      * changes back to the database, if it so desires.
      * </p>
      *
      * @return A {@code List} of {@link DynaBean} instances
      */
     public List<DynaBean> getRows() {
         return this.rows;
     }
 
 }