# UnclosablePreparedStatement.java

    /*
    ** Module   : UnclosablePreparedStatement.java
    ** Abstract : Provides a prepared statement proxy suitable for caching.
    **
    ** Copyright (c) 2020-2024, Golden Code Development Corporation.
    **
    ** -#- -I- --Date-- ---------------------------------------Description---------------------------------------
    ** 001 AIL 20201020 Created initial version.
    **     OM  20220228 Added toString() implementation to allow the statements to be correctly displayed with
    **                  SQLStatementLogger. Javadoc fixes.
    **     TJD 20220331 Removed deprecation from setUnicodeStream as it   is a proxy class
    **     CA  20221031 Added JMX instrumentation for 'execute' methods.
    ** 002 AL2 20230216 Avoid using array to store return value of JMX instrumented code.
    ** 003 GBB 20230512 Logging methods replaced by CentralLogger/ConversionStatus.
    ** 004 RAA 20230613 The SQL is now stored. toString() now prints only the SQL, not the whole statement.
    ** 005 AL2 20230630 Avoid clearing generated keys as these may not be computed anyway.
    ** 006 RAA 20231011 Removed SQL field. Reverted toString() to print the whole statement.
    ** 007 HC  20240222 Enabled JMX on FWD Client.
    ** 008 CA  20240307 Added a secondary pool of prepared statements, to be used when the instance from the main
    **                  cache is checked out.
    ** 009 AI  20250220 Added check for JMX_DEBUG to minimize use of lambda.
    */

    /*
    ** This program is free software: you can redistribute it and/or modify
    ** it under the terms of the GNU Affero General Public License as
    ** published by the Free Software Foundation, either version 3 of the
    ** License, or (at your option) any later version.
    **
    ** This program is distributed in the hope that it will be useful,
    ** but WITHOUT ANY WARRANTY; without even the implied warranty of
    ** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    ** GNU Affero General Public License for more details.
    **
    ** You may find a copy of the GNU Affero GPL version 3 at the following
    ** location: https://www.gnu.org/licenses/agpl-3.0.en.html
    **
    ** Additional terms under GNU Affero GPL version 3 section 7:
    **
    **   Under Section 7 of the GNU Affero GPL version 3, the following additional
    **   terms apply to the works covered under the License.  These additional terms
    **   are non-permissive additional terms allowed under Section 7 of the GNU
    **   Affero GPL version 3 and may not be removed by you.
    **
    **   0. Attribution Requirement.
    **
    **     You must preserve all legal notices or author attributions in the covered
    **     work or Appropriate Legal Notices displayed by works containing the covered
    **     work.  You may not remove from the covered work any author or developer
    **     credit already included within the covered work.
    **
    **   1. No License To Use Trademarks.
    **
    **     This license does not grant any license or rights to use the trademarks
    **     Golden Code, FWD, any Golden Code or FWD logo, or any other trademarks
    **     of Golden Code Development Corporation. You are not authorized to use the
    **     name Golden Code, FWD, or the names of any author or contributor, for
    **     publicity purposes without written authorization.
    **
    **   2. No Misrepresentation of Affiliation.
    **
    **     You may not represent yourself as Golden Code Development Corporation or FWD.
    **
    **     You may not represent yourself for publicity purposes as associated with
    **     Golden Code Development Corporation, FWD, or any author or contributor to
    **     the covered work, without written authorization.
    **
    **   3. No Misrepresentation of Source or Origin.
    **
    **     You may not represent the covered work as solely your work.  All modified
    **     versions of the covered work must be marked in a reasonable way to make it
    **     clear that the modified work is not originating from Golden Code Development
    **     Corporation or FWD.  All modified versions must contain the notices of
    **     attribution required in this license.
    */
    package com.goldencode.p2j.persist.orm;

    import java.io.*;
    import java.math.BigDecimal;
    import java.net.URL;
    import java.sql.*;
    import java.util.ArrayDeque;
    import java.util.Calendar;
    import java.util.Deque;
    import java.util.logging.*;

    import com.goldencode.p2j.jmx.*;
    import com.goldencode.p2j.util.logging.*;

    /**
     * Prepared statement proxy used for caching statements at connection level.
     */
    public class UnclosablePreparedStatement
    implements PreparedStatement
    {
       /** Instrumentation for execute methods. */
       private static final NanoTimer EXEC = NanoTimer.getInstance(FwdServerJMX.TimeStat.OrmTempTableQuery);

       /** The proxied prepared statement */
       private final PreparedStatement target;

       /** Flag to indicate if this statement is checked-out */
       private boolean checkedOut;

       /** Flag to indicate if this statement should close itself on check-in */
       private boolean closeOnCheckIn;

       /**
        * Secondary pool of prepared statements for the same SQL, when the main is checked out.  Only set on the
        * 'master' instance, which is in the main cache.
         */
       private Deque<UnclosablePreparedStatement> pool = null;

       /**
        * When set, it means this instance is in the secondary {@link #pool}, and the field references the
        * instance from the main cache.
        */
       private UnclosablePreparedStatement master = null;

       /** Logger */
       private static final CentralLogger LOG = CentralLogger.get(UnclosablePreparedStatement.class.getName());

       /**
        * Default constructor
        *
        * @param   target
        *          The prepared statement to be proxied.
        */
       public UnclosablePreparedStatement(PreparedStatement target, String sql)
       {
          this(target, sql, true);
       }

       /**
        * Constructor.
        *
        * @param   target
        *          Represents the prepared statement instance which should be proxied
        * @param   sql
        *          The SQL used in this statement.
        * @param   closeOnCheckIn
        *          Flag to indicate id the statement should be closed when checked-in
        */
       public UnclosablePreparedStatement(PreparedStatement target, String sql, boolean closeOnCheckIn)
       {
          this.target = target;
          this.closeOnCheckIn = closeOnCheckIn;
          this.checkedOut = false;
       }

       /**
        * Get another instance from the {@link #pool secondary pool}.  Must be called only on the master instance.
        *
        * @return   Another instance or <code>null</code> if the pool is empty.
        */
       public UnclosablePreparedStatement getFromPool()
       {
          if (pool == null || pool.isEmpty())
          {
             return null;
          }

          return pool.pop();
       }

       /**
        * Add the given instance to the {@link #pool secondary pool}.  Must be called only on the master instance.
        *
        * @param    ps
        *           The prepared statement instance.
        */
       public void addToPool(UnclosablePreparedStatement ps)
       {
          if (pool == null)
          {
             pool = new ArrayDeque<>(5);
          }
          pool.push(ps);

          ps.master = this;
       }

       /**
        * Set the checkOut flag on true.
        */
       public void checkOut()
       {
          if (!isCheckedOut())
          {
             this.checkedOut = true;
          }
          else
          {
             throw new IllegalStateException("Can't check out a statement which was already checked-out.");
          }
       }

       /**
        * Set the checkOut flag on false. If the closeOnCheckIn is set, force close this statement.
        */
       public void checkIn()
       {
          if (isCheckedOut())
          {
             this.checkedOut = false;

             try
             {
                if (isCloseOnCheckIn() || (master != null && master.isClosed()))
                {
                   // if master is already closed, the force close it, there is no way to check it out from the
                   // secondary cache again
                   forceClose();
                }
                else
                {
                   if (master != null)
                   {
                      // this is part of the secondary cache, pool is always non-null
                      master.pool.push(this);
                   }

                   // make sure that the result set will be closed
                   // cached statements will also automatically cache the result-set
                   ResultSet rs = this.target.getResultSet();
                   if (rs != null)
                   {
                      rs.close();
                   }

                   // AL2: if there are no generated keys, H2 will try to create a dummy
                   // empty result-set for us to close. There should be no place in
                   // FWD where we rely on auto-generated keys, so we shouldn't force the
                   // creation of generated keys just to close them.

                   // make sure that the generated keys will be closed
                   // cached statements will also automatically cache the generated-keys
                   // if (this.target.getGeneratedKeys() != null)
                   // {
                   //    this.target.getGeneratedKeys().close();
                   // }
                }
             }
             catch (SQLException e)
             {
                if (LOG.isLoggable(Level.WARNING))
                {
                   LOG.log(Level.WARNING, "Can't close the freshly checked-in statement: " + target.toString());
                }
             }
          }
          else
          {
             throw new IllegalStateException("Can't check in a statement which wasn't yet checked-out.");
          }
       }

       /**
        * Check if this statement is checked out
        *
        * @return   true if this statement is checked out
        */
       public boolean isCheckedOut()
       {
          return this.checkedOut;
       }

       /**
        * Check if this statement should close when checked-in
        *
        * @return  true if this statement should close when checked-in
        */
       public boolean isCloseOnCheckIn()
       {
          return this.closeOnCheckIn;
       }

       /**
        * Set the closeOnCheckIn flag.
        *
        * @param    closeOnCheckIn
        *           The new value for the closeOnCheckIn flag.
        */
       public void setCloseOnCheckIn(boolean closeOnCheckIn)
       {
          this.closeOnCheckIn = closeOnCheckIn;
       }

       /**
        * Close the proxy. This will flag that this statement is inactive and can be checked-in the pool.
        *
        * @throws   SQLException
        *           if a database access error occurs.
        */
       public void close()
       throws SQLException
       {
          // closing a statement will eventually mean the return of it in the pool - so check-in
          checkIn();
       }

       /**
        * Permanently close the prepared statement as this will be removed from the pool.
        *
        * @throws  SQLException
        *          if a database access error occurs.
        * @throws  IllegalStateException
        *          when the statement is still checked-out and cannot be closed.
        */
       public void forceClose()
       throws SQLException
       {
          // close such prepared statements only in force mode this also closes the attached result set if any
          if (!isCheckedOut())
          {
             // this is called when the master is removed from the main cache.
             // if there is a pool of secondary statements, then:
             // 1. all not-"cheched out" can be closed
             // 2. the others are marked as 'force close' (although removing them from the pool on checkout will
             //    not allow checked out instances to exist in the secondary pool).  These will be closed when
             //    they are attempted to be checked in, if the master is already closed.
             if (pool != null)
             {
                for (UnclosablePreparedStatement ps : pool)
                {
                   if (!ps.isCheckedOut())
                   {
                      ps.forceClose();
                   }
                   else
                   {
                      ps.setCloseOnCheckIn(true);
                   }
                }
             }

             this.target.close();
          }
          else
          {
             throw new IllegalStateException("Can't close a statement which is still checked-out.");
          }
       }

       public ResultSet executeQuery(String sql)
       throws SQLException
       {
          if (FwdServerJMX.JMX_DEBUG)
          {
             return exec(() -> this.target.executeQuery(sql));
          }
          else
          {
             return this.target.executeQuery(sql);
          }
       }

       public int executeUpdate(String sql)
       throws SQLException
       {
          if (FwdServerJMX.JMX_DEBUG)
          {
             return exec(() -> this.target.executeUpdate(sql));
          }
          else
          {
             return this.target.executeUpdate(sql);
          }
       }

       public boolean execute(String sql)
       throws SQLException
       {
          if (FwdServerJMX.JMX_DEBUG)
          {
             return exec(() -> this.target.execute(sql));
          }
          else
          {
             return this.target.execute(sql);
          }
       }

       public int[] executeBatch()
       throws SQLException
       {
          if (FwdServerJMX.JMX_DEBUG)
          {
             return exec(() -> this.target.executeBatch());
          }
          else
          {
             return this.target.executeBatch();
          }
       }

       public int executeUpdate(String sql, int autoGeneratedKeys)
       throws SQLException
       {
          if (FwdServerJMX.JMX_DEBUG)
          {
             return exec(() -> this.target.executeUpdate(sql, autoGeneratedKeys));
          }
          else
          {
             return this.target.executeUpdate(sql, autoGeneratedKeys);
          }
       }

       public int executeUpdate(String sql, int[] columnIndexes)
       throws SQLException
       {
          if (FwdServerJMX.JMX_DEBUG)
          {
             return exec(() -> this.target.executeUpdate(sql, columnIndexes));
          }
          else
          {
             return this.target.executeUpdate(sql, columnIndexes);
          }
       }

       public int executeUpdate(String sql, String[] columnNames)
       throws SQLException
       {
          if (FwdServerJMX.JMX_DEBUG)
          {
             return exec(() -> this.target.executeUpdate(sql, columnNames));
          }
          else
          {
             return this.target.executeUpdate(sql, columnNames);
          }
       }

       public boolean execute(String sql, int autoGeneratedKeys)
       throws SQLException
       {
          if (FwdServerJMX.JMX_DEBUG)
          {
             return exec(() -> this.target.execute(sql, autoGeneratedKeys));
          }
          else
          {
             return this.target.execute(sql, autoGeneratedKeys);
          }
       }

       public boolean execute(String sql, int[] columnIndexes)
       throws SQLException
       {
          if (FwdServerJMX.JMX_DEBUG)
          {
             return exec(() -> this.target.execute(sql, columnIndexes));
          }
          else
          {
             return this.target.execute(sql, columnIndexes);
          }
       }

       public boolean execute(String sql, String[] columnNames)
       throws SQLException
       {
          if (FwdServerJMX.JMX_DEBUG)
          {
             return exec(() -> this.target.execute(sql, columnNames));
          }
          else
          {
             return this.target.execute(sql, columnNames);
          }
       }

       public ResultSet executeQuery()
       throws SQLException
       {
          if (FwdServerJMX.JMX_DEBUG)
          {
             return exec(() -> this.target.executeQuery());
          }
          else
          {
             return this.target.executeQuery();
          }
       }

       public int executeUpdate()
       throws SQLException
       {
          if (FwdServerJMX.JMX_DEBUG)
          {
             return exec(() -> this.target.executeUpdate());
          }
          else
          {
             return this.target.executeUpdate();
          }
       }

       public boolean execute()
       throws SQLException
       {
          if (FwdServerJMX.JMX_DEBUG)
          {
             return exec(() -> this.target.execute());
          }
          else
          {
             return this.target.execute();
          }
       }

       public int getMaxFieldSize() throws SQLException { return this.target.getMaxFieldSize(); }
       public void setMaxFieldSize(int max) throws SQLException { this.target.setMaxFieldSize(max); }
       public int getMaxRows() throws SQLException { return this.target.getMaxRows(); }
       public void setMaxRows(int max) throws SQLException { this.target.setMaxRows(max); }
       public void setEscapeProcessing(boolean enable) throws SQLException { this.target.setEscapeProcessing(enable); }
       public int getQueryTimeout() throws SQLException { return this.target.getQueryTimeout(); }
       public void setQueryTimeout(int seconds) throws SQLException { this.target.setQueryTimeout(seconds); }
       public void cancel() throws SQLException { this.target.cancel(); }
       public SQLWarning getWarnings() throws SQLException { return this.target.getWarnings(); }
       public void clearWarnings() throws SQLException { this.target.clearWarnings(); }
       public void setCursorName(String name) throws SQLException { this.target.setCursorName(name); }
       public ResultSet getResultSet() throws SQLException { return this.target.getResultSet(); }
       public int getUpdateCount() throws SQLException { return this.target.getUpdateCount(); }
       public boolean getMoreResults() throws SQLException { return this.target.getMoreResults(); }
       public void setFetchDirection(int direction) throws SQLException { this.target.setFetchDirection(direction); }
       public int getFetchDirection() throws SQLException { return this.target.getFetchDirection(); }
       public void setFetchSize(int rows) throws SQLException { this.target.setFetchSize(rows); }
       public int getFetchSize() throws SQLException { return this.target.getFetchSize(); }
       public int getResultSetConcurrency() throws SQLException { return this.target.getResultSetConcurrency(); }
       public int getResultSetType() throws SQLException { return this.target.getResultSetType(); }
       public void addBatch(String sql) throws SQLException { this.target.addBatch(sql); }
       public void clearBatch() throws SQLException { this.target.clearBatch(); }
       public Connection getConnection() throws SQLException { return this.target.getConnection(); }
       public boolean getMoreResults(int current) throws SQLException { return this.target.getMoreResults(current); }
       public ResultSet getGeneratedKeys() throws SQLException { return this.target.getGeneratedKeys(); }
       public int getResultSetHoldability() throws SQLException { return this.target.getResultSetHoldability(); }
       public boolean isClosed() throws SQLException { return this.target.isClosed(); }
       public void setPoolable(boolean poolable) throws SQLException { this.target.setPoolable(poolable); }
       public boolean isPoolable() throws SQLException { return this.target.isPoolable(); }
       public void closeOnCompletion() throws SQLException { this.target.isCloseOnCompletion(); }
       public boolean isCloseOnCompletion() throws SQLException { return this.target.isCloseOnCompletion(); }
       public <T> T unwrap(Class<T> iface) throws SQLException { return this.target.unwrap(iface); }
       public boolean isWrapperFor(Class<?> iface) throws SQLException { return this.target.isWrapperFor(iface); }
       public void setNull(int parameterIndex, int sqlType) throws SQLException {
          this.target.setNull(parameterIndex, sqlType); }
       public void setBoolean(int parameterIndex, boolean x) throws SQLException {
          this.target.setBoolean(parameterIndex, x); }
       public void setByte(int parameterIndex, byte x) throws SQLException { this.target.setByte(parameterIndex, x); }
       public void setShort(int parameterIndex, short x) throws SQLException { this.target.setShort(parameterIndex, x); }
       public void setInt(int parameterIndex, int x) throws SQLException { this.target.setInt(parameterIndex, x); }
       public void setLong(int parameterIndex, long x) throws SQLException { this.target.setLong(parameterIndex, x); }
       public void setFloat(int parameterIndex, float x) throws SQLException { this.target.setFloat(parameterIndex, x); }
       public void setDouble(int parameterIndex, double x) throws SQLException {
          this.target.setDouble(parameterIndex, x); }
       public void setBigDecimal(int parameterIndex, BigDecimal x) throws SQLException {
          this.target.setBigDecimal(parameterIndex, x); }
       public void setString(int parameterIndex, String x) throws SQLException {
          this.target.setString(parameterIndex, x); }
       public void setBytes(int parameterIndex, byte[] x) throws SQLException { this.target.setBytes(parameterIndex, x); }
       public void setDate(int parameterIndex, Date x) throws SQLException { this.target.setDate(parameterIndex, x); }
       public void setTime(int parameterIndex, Time x) throws SQLException { this.target.setTime(parameterIndex, x); }
       public void setTimestamp(int parameterIndex, Timestamp x) throws SQLException {
          this.target.setTimestamp(parameterIndex, x); }
       public void setAsciiStream(int parameterIndex, InputStream x, int length) throws SQLException {
          this.target.setAsciiStream(parameterIndex, x, length); }
       @SuppressWarnings("deprecation")
       public void setUnicodeStream(int parameterIndex, InputStream x, int length) throws SQLException {
          this.target.setUnicodeStream(parameterIndex, x, length);}
       public void setBinaryStream(int parameterIndex, InputStream x, int length) throws SQLException {
          this.target.setBinaryStream(parameterIndex, x, length); }
       public void clearParameters() throws SQLException { this.target.clearParameters(); }
       public void setObject(int parameterIndex, Object x, int targetSqlType) throws SQLException {
          this.target.setObject(parameterIndex, x, targetSqlType);}
       public void setObject(int parameterIndex, Object x) throws SQLException {
          this.target.setObject(parameterIndex, x); }
       public void addBatch() throws SQLException { this.target.addBatch(); }
       public void setCharacterStream(int parameterIndex, Reader reader, int length) throws SQLException {
          this.target.setCharacterStream(parameterIndex, reader, length); }
       public void setRef(int parameterIndex, Ref x) throws SQLException { this.target.setRef(parameterIndex, x); }
       public void setBlob(int parameterIndex, Blob x) throws SQLException { this.target.setBlob(parameterIndex, x); }
       public void setClob(int parameterIndex, Clob x) throws SQLException { this.target.setClob(parameterIndex, x); }
       public void setArray(int parameterIndex, Array x) throws SQLException { this.target.setArray(parameterIndex, x); }
       public ResultSetMetaData getMetaData() throws SQLException { return this.target.getMetaData(); }
       public void setDate(int parameterIndex, Date x, Calendar cal) throws SQLException {
          this.target.setDate(parameterIndex, x, cal); }
       public void setTime(int parameterIndex, Time x, Calendar cal) throws SQLException {
          this.target.setTime(parameterIndex, x, cal); }
       public void setTimestamp(int parameterIndex, Timestamp x, Calendar cal) throws SQLException {
          this.target.setTimestamp(parameterIndex, x, cal); }
       public void setNull(int parameterIndex, int sqlType, String typeName) throws SQLException {
          this.target.setNull(parameterIndex, sqlType, typeName); }
       public void setURL(int parameterIndex, URL x) throws SQLException { this.target.setURL(parameterIndex, x); }
       public ParameterMetaData getParameterMetaData() throws SQLException { return this.target.getParameterMetaData(); }
       public void setRowId(int parameterIndex, RowId x) throws SQLException { this.target.setRowId(parameterIndex, x); }
       public void setNString(int parameterIndex, String value) throws SQLException {
          this.target.setNString(parameterIndex, value); }
       public void setNCharacterStream(int parameterIndex, Reader value, long length) throws SQLException {
          this.target.setNCharacterStream(parameterIndex, value, length); }
       public void setNClob(int parameterIndex, NClob value) throws SQLException {
          this.target.setNClob(parameterIndex, value); }
       public void setClob(int parameterIndex, Reader reader, long length) throws SQLException {
          this.target.setClob(parameterIndex, reader, length); }
       public void setBlob(int parameterIndex, InputStream inputStream, long length) throws SQLException {
          this.target.setBlob(parameterIndex, inputStream, length); }
       public void setNClob(int parameterIndex, Reader reader, long length) throws SQLException {
          this.target.setNClob(parameterIndex, reader, length); }
       public void setSQLXML(int parameterIndex, SQLXML xmlObject) throws SQLException {
          this.target.setSQLXML(parameterIndex, xmlObject); }
       public void setObject(int parameterIndex, Object x, int targetSqlType, int scaleOrLength) throws SQLException {
          this.target.setObject(parameterIndex, x, targetSqlType, scaleOrLength); }
       public void setAsciiStream(int parameterIndex, InputStream x, long length) throws SQLException {
          this.target.setAsciiStream(parameterIndex, x, length); }
       public void setBinaryStream(int parameterIndex, InputStream x, long length) throws SQLException {
          this.target.setBinaryStream(parameterIndex, x, length); }
       public void setCharacterStream(int parameterIndex, Reader reader, long length) throws SQLException {
          this.target.setCharacterStream(parameterIndex, reader, length); }
       public void setAsciiStream(int parameterIndex, InputStream x) throws SQLException {
          this.target.setAsciiStream(parameterIndex, x); }
       public void setBinaryStream(int parameterIndex, InputStream x) throws SQLException {
          this.target.setBinaryStream(parameterIndex, x); }
       public void setCharacterStream(int parameterIndex, Reader reader) throws SQLException {
          this.target.setCharacterStream(parameterIndex, reader); }
       public void setNCharacterStream(int parameterIndex, Reader value) throws SQLException {
          this.target.setNCharacterStream(parameterIndex, value); }
       public void setClob(int parameterIndex, Reader reader) throws SQLException {
          this.target.setClob(parameterIndex, reader); }
       public void setBlob(int parameterIndex, InputStream inputStream) throws SQLException {
          this.target.setBlob(parameterIndex, inputStream); }
       public void setNClob(int parameterIndex, Reader reader) throws SQLException {
          this.target.setNClob(parameterIndex, reader); }

       /**
        * Returns a string representation of the object, exposing the target statement.
        *
        * @return  a string representation of the object.
        */
       @Override
       public String toString()
       {
          return "SqlStmt{" + target + '}';
       }

       /**
        * Execute the code in a {@link #EXEC timer} to track the time spent.
        *
        * @param    f
        *           The code to execute.
        *
        * @return   The returned value by the code.
        *
        * @throws   SQLException
        *           Throw if the executed code throws this exception.
        */
       private <T> T exec(ReturningOperation<T> f)
       throws SQLException
       {
          try
          {
             return EXEC.timerWithReturn(f);
          }
          catch (Exception e)
          {
             if (e.getCause() instanceof SQLException)
             {
                throw (SQLException) e.getCause();
             }
             throw e;
          }
       }
    }