# OutputDataSetHandleCopier.java

    /*
    ** Module   : OutputDataSetHandleCopier.java
    ** Abstract : Finalizable for copying data in OUTPUT direction in DataSet-handle parameter case.
    **
    ** Copyright (c) 2019-2024, Golden Code Development Corporation.
    **
    ** -#- -I- --Date-- -----------------------Description-------------------------------------------
    ** 001 OM  20190709 Created initial version.
    **     OM  20190712 Fixed finished() implementation.
    **     CA  20190720 DATASET-HANDLE arguments get deleted only after they are copied.
    **                  These fixes are not proved and BY-REFERENCE, OUTPUT and DELETE combinations
    **                  are most likely related to NUM-REFERENCES attribute.
    **     CA  20190728 This needs to be processed first, before buffer's are closing their scope.
    **     CA  20190812 Changes to allow for mutable datasets; any API which receives a Buffer instance
    **                  and is invoked from converted code must resolve the runtime instance before
    **                  saving the instance.
    ** 002 CA  20200110 More fixes for DATASET parameters and resource delete.
    ** 003 CA  20210928 A dataset-handle parameter can be deleted if is not BY-REFERENCE and references the same
    **                  dataset as the caller's.
    **     CA  20211112 Allow the DATASET and TABLE parameters for remote SOAP calls to be transferred via XML
    **                  (so that relations, schema, etc is done on the server-side).
    **     CA  20220923 Internal var definitions must be done via TypeFactory and not UndoableFactory.
    **     CA  20221006 Added JMX instrumentation for 'finished'. Refs #6814
    **     CA  20220609 A fix for OUTPUT DATASET-HANDLE ... BY-REFERENCE - copy directly the callee's dataset.
    **     CA  20220618 Automatically delete datasets created for remote parameters.
    **     CA  20220912 If a dataset from the call has no buffers added to it, just create an empty one with the
    **                  same settings - there are no rows to copy.
    **     CA  20221130 Fixed BIND for a REFERENCE-ONLY source dataset.
    **     CA  20230116 Avoid using handle.unwrap, handle.getReference or other BDT usage from within FWD runtime.
    ** 004 HC  20240222 Enabled JMX on FWD Client.
    ** 005 CA  20240809 Skip using JMX timers when JMX_DEBUG flag is not set.
    */

    /*
    ** 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;

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

    import java.util.*;

    /**
     * Class which is registered as a top-level finalizable and copies data in OUTPUT direction
     * in DataSet-handle parameter case.
     */
    public class OutputDataSetHandleCopier
    implements Finalizable
    {
       /** Instrumentation for {@link #finished()}. */
       private static final NanoTimer COPIER = NanoTimer.getInstance(FwdServerJMX.TimeStat.OutputDataSetHandleCopier);

       /** Calling-side {@code DataSet} parameter. */
       private final DataSetParameter calling;

       /** Called-side {@code DataSet} handle. */
       private final handle called;

       /** {@code DataSet} postponed for deletion. */
       private DataSet dsToDelete = null;

       /**
        * Map of all output copiers for the procedure/function for which this copier is registered, to
        * their 0-based indexes in the set of all DATASET-HANDLE parameters for the procedure/function
        * (excluding other types of parameters).
        */
       private Map<OutputDataSetHandleCopier, Integer> siblings;

       /**
        * Constructor.
        *
        * @param   calling
        *          Calling-side {@code DataSet} parameter.
        * @param   called
        *          Called-side {@code DataSet} handle.
        */
       public OutputDataSetHandleCopier(DataSetParameter calling, handle called)
       {
          this.calling = calling;
          this.called = called;
       }

       /** Copies data in OUTPUT direction in DataSet-handle parameter case.*/
       @Override
       public void finished()
       {
          if (FwdServerJMX.JMX_DEBUG)
          {
             COPIER.timer(() -> finishedImpl());
          }
          else
          {
             finishedImpl();
          }
       }

       /** Copies data in OUTPUT direction in DataSet-handle parameter case. */
       private void finishedImpl()
       {
          boolean doDelete = false;
          if (called._isValid())
          {
             doDelete = ((DataSet) called.getResource()).isPostponedDelete() && !calling.isByReference();
          }

          boolean res = true;
          DataSet callingDataset = calling.getDataset();
          DataSet originalDataset = calling.getOriginalDataSet();
          if (originalDataset != null && originalDataset.referenceOnly && calling.isBind())
          {
             if (called._isValid())
             {
                ((StaticDataSet) originalDataset).bind((DataSet) called.get(),
                                                       calling.isInputMode(),
                                                       calling.isOutputMode(),
                                                       false,
                                                       true);
             }
          }
          else if (callingDataset == null || !callingDataset.valid() || calling.isRemoteParameter())
          {
             // if [calling.isRemoteParameter()] the [callingDataset] is most likely to be valid as
             // it has sent data as I/O parameter. In this case [called] is referencing it and is also
             // valid
             if (calling.isRemoteParameter() && calling.getDatasetWrapper().isAsXml())
             {
                DatasetWrapper wrapper = calling.getDatasetWrapper();
                String dsXml = DataSet.writeToXml(called, wrapper.isUseBeforeImage(), wrapper.isDatasetHandle());
                wrapper.setXmlDataset(dsXml);

                // always cleanup after remote parameter
                doDelete = true;
             }
             else if (called._isValid())
             {
                if (calling.isRemoteParameter())
                {
                   // fill result set(s)
                   DatasetWrapper oldWrapper = calling.getDatasetWrapper();
                   DataSetContainer rs = new DataSetContainer((DataSet) called.getResource(),
                                                              oldWrapper.isInput(),
                                                              oldWrapper.isOutput(),
                                                              oldWrapper.isAppend());
                   DatasetWrapper wrapper = new DatasetWrapper(rs);
                   wrapper.setDatasetName(((DataSet) called.getResource())._name());
                   wrapper.setDatasetHandle(true);
                   calling.setDatasetWrapper(wrapper);

                   // always cleanup after remote parameter
                   doDelete = true;
                }
                else
                {
                   if (calling.isByReference())
                   {
                      calling.getDatasetHandle().assign(called);
                      doDelete = false;
                   }
                   else
                   {
                      // create new dataset
                      handle newDSh = TypeFactory.handle();
                      DataSet.create(newDSh);
                      DataSet newDS = (DataSet) newDSh.getResource();
                      if (((DataSet) called.getResource())._getNumTopBuffers() > 0)
                      {
                         res = newDS.copyDatasetImpl(
                               called, calling.isAppend(), false, false, null, false, "").booleanValue();
                      }
                      else
                      {
                         // there are no rows to copy, just create it
                         res = newDS.createLike(called).booleanValue();
                      }
                      if (res)
                      {
                         calling.getDatasetHandle().assign(newDS);
                      }
                   }
                }
             }
          }
          else if (called._isValid() && (called.getResource() != callingDataset || !calling.isByReference()))
          {
             res = called.getResource() == callingDataset ||
                   callingDataset.copyDatasetImpl(called, calling.isAppend(), false, false, null, false, "")
                                 .booleanValue();
          }

          if (!res)
          {
             TemporaryBuffer.deferCopyError();
          }

          DataSetManager.instance().unregisterOutputDataSetHandleCopier(this);

          if (doDelete && called._isValid() && ((DynamicResource) called.getResource())._dynamic())
          {
             ((DataSet) called.getResource()).delete();
          }

          // CA: 'dstToDelete' is always null, as there is no caller of 'setDataSetToDelete
          /*
          if (dsToDelete != null &&
              (dsToDelete.equals(called.getResource()) ||
               (!called._isValid() && (siblings.size() == 1 || siblings.get(this) != 0))))
          {
             // If we have:
             // 1. DataSet postponed for delete AND
             // 2. corresponding DATASET-HANDLE value hasn't changed OR ...
             // 3. DATASET-HANDLE value is unknown and it is the single DATASET-HANDLE parameter OR ...
             // 4. DATASET-HANDLE value is unknown, there are multiple DATASET-HANDLE parameter and it
             //    is not the first one.
             DataSetManager.instance().unregisterOutputDataSetHandleCopier(this);
             dsToDelete.clear();
          }
          */
       }

       /** No-op. */
       @Override
       public void deleted()
       {
       }

       /** No-op. */
       @Override
       public void iterate()
       {
       }

       /** No-op. */
       @Override
       public void retry()
       {
       }

       /**
        * Get the weight of this finalizable.  Instances will be ordered by their
        * {@link WeightFactor weight}, before they are processed.
        *
        * @return   The weight of this finalizable - {@link WeightFactor#FIRST}.
        */
       @Override
       public WeightFactor weight()
       {
          return WeightFactor.FIRST;
       }

       /**
        * Set {@code DataSet} for postponed deletion.
        *
        * @param dsToDelete
        *        {@code DataSet} for postponed deletion.
        */
       public void setDataSetToDelete(DataSet dsToDelete)
       {
          this.dsToDelete = dsToDelete.ref();
       }

       /**
        * Get called-side {@code DataSet} handle.
        *
        * @return  called-side {@code DataSet} handle.
        */
       public handle getCalled()
       {
          return called;
       }

       /**
        * Set the map of all output copiers for the procedure/function for which this copier is
        * registered, to their 0-based indexes in the set of all DATASET-HANDLE parameters for the
        * procedure/function (excluding other types of parameters).
        *
        * @param siblings
        *        See above.
        */
       public void setSiblingsMap(Map<OutputDataSetHandleCopier, Integer> siblings)
       {
          this.siblings = siblings;
       }
    }