FWD » Core Development » Database

      /** Lazily hydrated an new record (not rehydrated from cache) */

      HydratorNewRecord,

      /** Lazily hydrated a record (including rehydration from cache) */

      HydratorLazyRecord,

      /** Fully or partially hydrated a record, but not lazy */

      HydratorNonLazyRecord,

      /** The hydrator token matched the result-set token */

      HydratorHit,

      /** The hydrator token mismatched the result-set token */

      HydratorMiss,

      /** The hydrator fallbacked to refresh and succeeded */

      HyratorSuccessfullRefresh,

      /** The hydrator fallbacked to refresh and failed */

      HyratorUnsuccessfullRefresh,

      /** Created a {@code ScrollableResults} instance with lazy results */

      HydratorLazyScrollable,

      /** Created a {@code ScrollableResults} instance without lazy results */

      HydratorNonLazyScrollable,

      /** Executed uniqueResult instance with lazy results */

      HydratorLazyUnique,

      /** Executed uniqueResult instance without lazy results */

      HydratorNonLazyUnique,

      TempTotalFields,

      PersistentTotalFields,

      TempHydratedRecordsWhenSessionCloses,

      PersistentHydratedRecordsWhenSessionCloses,

      TempHydratedFieldsWhenSessionCloses,

      PersistentHydratedFieldsWhenSessionCloses,

      PersistentHydratedFieldsWithLZS,

      PersistentHydratedFieldsWithLoader,

      TempHydratedFieldsWithLZS,

      TempHydratedFieldsWithLoader,

      /** Lazily hydrated an new record (not rehydrated from cache) */

      HydratorNewRecord,

      /** Lazily hydrated a record (including rehydration from cache) */

      HydratorLazyRecord,

      /** Fully or partially hydrated a record, but not lazy */

      HydratorNonLazyRecord,

      /** The hydrator token matched the result-set token */

      HydratorHit,

      /** The hydrator token mismatched the result-set token */

      HydratorMiss,

      /** The hydrator fallbacked to refresh and succeeded */

      HyratorSuccessfullRefresh,

      /** The hydrator fallbacked to refresh and failed */

      HyratorUnsuccessfullRefresh,

      /** Created a {@code ScrollableResults} instance with lazy results */

      HydratorLazyScrollable,

      /** Created a {@code ScrollableResults} instance without lazy results */

      HydratorNonLazyScrollable,

      /** Executed uniqueResult instance with lazy results */

      HydratorLazyUnique,

      /** Executed uniqueResult instance without lazy results */

      HydratorNonLazyUnique,

      /** A call-site's field-usage profile locked in the EAGER hydration verdict */

      HydrationVerdictEager,

      /** A call-site's field-usage profile locked in the LAZY hydration verdict */

      HydrationVerdictLazy,

import com.goldencode.p2j.jmx.*;

   /**

    * Bounded per-database map of runtime field-usage profiles, keyed by FQL. Used by the

    * lazy-feedback hydration layer to decide eager vs lazy hydration per call-site. Hosted on the

    * per-database {@code Persistence} singleton (not the per-session context) so that all sessions

    * against this database share the learned verdicts, while different databases stay isolated. The

    * map is capped (see {@code FieldUsageProfile.maxProfiles()}): dynamic queries generate unbounded

    * distinct FQL strings, so once the cap is hit new call-sites get no profile and hydrate eagerly.

    */

   private final ConcurrentHashMap<String, FieldUsageProfile> usageProfiles = new ConcurrentHashMap<>();

   /**

    * Resolve (creating if necessary) the runtime field-usage profile for the given FQL call-site.

    * Used by the lazy-feedback hydration layer to decide eager vs lazy hydration per call-site.

    *

    * @param   fql

    *          The FQL identifying the call-site.

    *

    * @return  The shared profile for the call-site, or {@code null} when the feature is disabled or

    *          the per-database profile cap has been reached (in which case the call-site hydrates

    *          eagerly, the safe default).

    */

   public FieldUsageProfile getOrCreateProfile(String fql)

   {

      if (!FieldUsageProfile.isEnabled() || fql == null)

      {

         return null;

      }

      FieldUsageProfile profile = usageProfiles.get(fql);

      if (profile != null)

      {

         return profile;

      }

      // hard create-cap: dynamic queries produce unbounded distinct FQL, so refuse new profiles once

      // full rather than evicting (a missing profile simply means EAGER). The size check races with

      // concurrent creators, but only ever overshoots the cap by the number of racing threads.

      if (usageProfiles.size() >= FieldUsageProfile.maxProfiles())

      {

         return null;

      }

      return usageProfiles.computeIfAbsent(fql, FieldUsageProfile::new);

   }

         ErrorManager.recordOrShowError(new int[] {ee.num}, 

                                        new String[] {ee.text},

                                        true,

                                        ee.prefix,

                                        false,

                                        false,

                                        false,

                                        true);

      /** Database dialect */

      private final Dialect dialect;

       * @param   dialect

       *          Database dialect.

      QueryKey(String hql, Dialect dialect, int maxResults, int startOffset, DataRelation relation, boolean lazyMode)

         this.dialect = dialect;

         result = 37 * result + fql.hashCode();

         result = 37 * result + dialect.hashCode();

                this.dialect.equals(that.dialect)          &&

         return fql + "[" + hasMaxResults + ":" + hasStartOffset + "] (" + dialect + ") " + whereStr;

         QueryKey key = new QueryKey(fql, dialect, maxResults, startOffset, relation, lazyMode);

         query = staticQueryCache.get(key);

         if (query == null)

            Consumer<Query> c = (q) ->

               // NOTE: the FQL string is not converted to SQL at this time. The conversion

               //       is performed once, lazily, when the first navigation is required by a

               //       call of list(), scroll(), or uniqueResult() on the new query

               staticQueryCache.put(key, q);

            };

            query = Session.createQuery(c, fql);

                     record.refreshHydrator(session);

            hydrateActiveRecords();

      private void hydrateActiveRecords()

      {

         Iterator<RecordBuffer> iter = bufferManager.activeBuffers(Persistence.this);

         Record record;

         while (iter.hasNext())

         {

            record = iter.next().getCurrentRecord();

            if (record.primaryKey() < 0)

            {

               continue;

            }

            record.hydrateRemainingFields();

         }

      }

import com.goldencode.p2j.jmx.*;

   private static final SimpleCounter HYDRATE_RECORDS_WHEN_SESSION_CLOSE =

      SimpleCounter.getInstance(FwdServerJMX.Counter.PersistentHydratedRecordsWhenSessionCloses);

   private static final SimpleCounter TOTAL_FIELDS =

      SimpleCounter.getInstance(FwdServerJMX.Counter.PersistentTotalFields);

   private static final SimpleCounter HYDRATE_FIELD_WHEN_SESSION_CLOSES =

      SimpleCounter.getInstance(FwdServerJMX.Counter.PersistentHydratedFieldsWhenSessionCloses);

   private static final SimpleCounter HYDRATED_FIELDS_LZS =

      SimpleCounter.getInstance(FwdServerJMX.Counter.PersistentHydratedFieldsWithLZS);

   private static final SimpleCounter HYDRATED_FIELDS_LOADER =

      SimpleCounter.getInstance(FwdServerJMX.Counter.PersistentHydratedFieldsWithLoader);

      Integer datum = (Integer) getDatum(offset);

      OffsetDateTime datum = (OffsetDateTime) getDatum(offset);

   @Override

   protected void countHydrateRecordWhenSessionCloses(long count)

   {

      HYDRATE_RECORDS_WHEN_SESSION_CLOSE.update(count);

   }

   @Override

   protected void countTotalFields(long count)

   {

      TOTAL_FIELDS.update(count);

   }

   @Override

   protected void countHydratedFieldsWithLoader(long count)

   {

      HYDRATED_FIELDS_LOADER.update(count);

   }

   @Override

   protected void countHydratedFieldsWithLZS(long count)

   {

      HYDRATED_FIELDS_LZS.update(count);

   }

   @Override

   protected void countHydratedFieldWhenSessionCloses(long count)

   {

      HYDRATE_FIELD_WHEN_SESSION_CLOSES.update(count);

   }

      Timestamp datum = (Timestamp) getDatum(offset);

      Date datum = (Date) getDatum(offset);

      Boolean datum = (Boolean) getDatum(offset);

      checkIncomplete(offset);

      Long datum = (Long) getDatum(offset);

      BigDecimal datum = (BigDecimal) getDatum(offset);

      String datum = (String) getDatum(offset);

      Long datum = (Long) getDatum(offset);

      Long datum = (Long) getDatum(offset);

      Long datum = (Long) getDatum(offset);

      byte[] datum = (byte[]) getDatum(offset);

      return new clob((String) getDatum(offset), getCodePage(offset));

      String datum = (String) getDatum(offset);

      Long datum = (Long) getDatum(offset);

      byte[] datum = (byte[]) getDatum(offset);

         int last = getLength();

            boolean isChar = getSimpleDatum(i) instanceof String;

            Object datum = getSimpleDatum(i);

            sb.append(datum == null ? incomplete ? "n/a" : "?" : datum);

               sb.append(getSimpleDatum(i));

                  sb.append(getSimpleDatum(i + k));

         Object[] data = getData();

               setLivePropsAtOffset(i);

            setLivePropsAtOffset(i);

               // the buffer is leaving this record: report the field demand observed during the visit

               // to the runtime-feedback hydration layer (no-op unless the record was probing)

               oldRecord.reportDemandSample();

** 006 AL2 20231102 Added computeIndexForHydrator for lazy hydration.

import com.goldencode.p2j.jmx.*;

   private static final SimpleCounter HYDRATE_RECORDS_WHEN_SESSION_CLOSE =

      SimpleCounter.getInstance(FwdServerJMX.Counter.TempHydratedRecordsWhenSessionCloses);

   private static final SimpleCounter TOTAL_FIELDS =

      SimpleCounter.getInstance(FwdServerJMX.Counter.TempTotalFields);

   private static final SimpleCounter HYDRATE_FIELD_WHEN_SESSION_CLOSES =

      SimpleCounter.getInstance(FwdServerJMX.Counter.TempHydratedFieldsWhenSessionCloses);

   private static final SimpleCounter HYDRATED_FIELDS_LZS =

      SimpleCounter.getInstance(FwdServerJMX.Counter.TempHydratedFieldsWithLZS);

   private static final SimpleCounter HYDRATED_FIELDS_LOADER =

      SimpleCounter.getInstance(FwdServerJMX.Counter.TempHydratedFieldsWithLoader);

      return (Long) getDatum(_PEER_ROWID_DATA_INDEX);

      return (Integer) getDatum(_ROW_STATE_DATA_INDEX);

      return (Long) getDatum(_ORIGIN_ROWID_DATA_INDEX);

      return (Long) getDatum(_DATASOURCE_ROWID_INDEX);

      return (Integer) getDatum(_ERROR_FLAG_DATA_INDEX);

      return (String) getDatum(_ERROR_STRING_DATA_INDEX);

   @Override

   protected int getHydratorRowOffset()

   {

      return 2;

   }

   @Override

   protected void countHydrateRecordWhenSessionCloses(long count)

   {

      HYDRATE_RECORDS_WHEN_SESSION_CLOSE.update(count);

   }

   @Override

   protected void countTotalFields(long count)

   {

      TOTAL_FIELDS.update(count);

   }

   @Override

   protected void countHydratedFieldsWithLZS(long count)

   {

      HYDRATED_FIELDS_LZS.update(count);

   }

   @Override

   protected void countHydratedFieldsWithLoader(long count)

   {

      HYDRATED_FIELDS_LOADER.update(count);

   }

   @Override

   protected void countHydratedFieldWhenSessionCloses(long count)

   {

      HYDRATE_FIELD_WHEN_SESSION_CLOSES.update(count);

   }

import com.goldencode.p2j.directory.*;

   /** Directory path for the lazy-hydration master switch. */

   private static final String CFG_LAZY_HYDRATION = "persistence/lazy-hydration/enabled";

   /**

    * Master switch for lazy (just-in-time) hydration of DMOs, read once from configuration. When

    * {@code false}, hydration is always eager and the runtime-feedback layer is moot (no call-site is

    * ever wrapped lazily). Defaults to enabled.

    */

   private static final boolean lazyHydrationEnabled =

      DirectoryManager.getInstance().getBoolean(Directory.ID_RELATIVE_SERVER, CFG_LAZY_HYDRATION, false);

    * Create the error descriptor from the {@code SQLException} message.

    * 

    * @return  <code>true</code> if Common Table Expressions should be used for converted CONTAINS operator

                                                  Collection<WordTable> wordTables);

   /**

    * Indicate whether this dialect is likely to benefit from lazy hydration of DMOs when reading a record

    * from the database. This serves as a hint, but may be overridden by configuration or runtime conditions.

    *

    * @return  {@code true} unless disabled via the {@code persistence/lazy-hydration/enabled}

    *          configuration or overridden by subclasses.

    */

   public boolean useLazyHydration()

   {

      return lazyHydrationEnabled;

   }

            String fql = "delete from " + entity + " where " + Session.PK + " = ?";

               Query query = Session.createQuery(fql);

    * Execute an FQL query and return the results as a list. If the query returns multiple results

** 005 AL2 20231214 Fixed hydrate extents to avoid honoring recOffset if set on -1.

   @Override

   public void hydrateExtents(Session session, BaseRecord r, int recOffset)

         boolean arbitrary = isIncomplete() || recOffset == -1;

            if (arbitrary)

** 004 AL2 20231214 Added implementation for hydrateAt.

import java.util.*;

   /**

    * Hydrate only one property in the base-record. This is largely used by the lazy hydrator,

    * allowing it to hydrate only the property that is accessed now. The other hydration method 

    * ({@link #hydrate}) eagerly hydrates all properties, is a slow process and may do useless

    * hydrations on properties that are not accessed.

    * 

    * @param   resultSet

    *          The ResultSet from which the hydration should be done

    * @param   rsOffset

    *          The result set offset from which the reading should be done. This is relevant as

    *          the result set may contain a joined row, but we are interested only in a specific

    *          record that may start at a specific offset.

    * @param   r

    *          The record that should be hydrated. 

    * @param   propOffset

    *          The property that should be hydrated. The caller is responsible in assuring that

    *          this property wasn't hydrated before.

    * 

    * @return  {@code true} if this worked due to the fact that it was a scalar value. {@code false}

    *          in case the property was a non-expanded 

    *          

    * @throws  PersistenceException

    *          This is thrown when reading the scalar property fails.

    */

   @Override

   public boolean hydrateAt(ResultSet resultSet, int rsOffset, BaseRecord r, int dataIndex)

   throws PersistenceException

   {

      return delegate.hydrateAt(resultSet, rsOffset, r, dataIndex);

   }

   /**

    * Retrieve the fields that were loaded from the database.

    *

    * @return A BitSet object, where true means that the field associated with that position in the {@code

    * data} array has been loaded from database, and false - otherwise.

    */

   @Override

   public BitSet getLoadedFields()

   {

      return delegate.getLoadedFields();

   }

** Copyright (c) 2019-2026, Golden Code Development Corporation.

import com.goldencode.p2j.jmx.*;

   /** The data represented by this record, in it's low-level (database friendly) form */

   private final Object[] data;

   /** Hydrator used to extract data from a result set positioned on a particular target row */

   private Hydrator hydrator = null;

   /** Map of "live" properties (read or assigned), each bit corresponds with a property in the data array */

   // TODO: resolve redundancy with readFields

   private BitSet liveProps;

   /** The number of bits set in {@link #liveProps} */

   private int livePropsCardinality;

   /**

    * Process-wide fast-path gate for the runtime-feedback hydration probe. {@code true} while the

    * feature is enabled and at least one {@link FieldUsageProfile} is still UNKNOWN. When {@code

    * false}, {@link #getDatum} pays only this single volatile read per field access and never touches

    * the per-record probe state, so steady-state hydration cost is unchanged. Maintained by

    * {@link FieldUsageProfile} as profiles are created and as verdicts lock in.

    */

   static volatile boolean PROBING_ACTIVE = false;

   /**

    * The field-usage profile this record is probing for, or {@code null} if not probing. Distinct

    * from {@link #hydrator}, so it survives the hydrator being nulled out in {@link #getDatum}.

    */

   private FieldUsageProfile usageProfile;

   /**

    * While probing, the set of field offsets read via {@link #getDatum} during the current buffer

    * visit; {@code null} except while a probe is armed (see {@link #armUsageProbe}).

    */

   private BitSet accessed;

         Object toDatum = to.getDatum(i);

         Object fromDatum = from.getDatum(i);

         boolean change = toDatum != fromDatum; 

            to.setSimpleDatum(i, fromDatum);

            to.nullProps.set(i, fromDatum == null);

      int len = this.getLength();

      copyArray(from.getData());

      hydrator = from.hydrator;

      liveProps = from.liveProps != null ? (BitSet) from.liveProps.clone() : null;

      livePropsCardinality = from.livePropsCardinality;

   }

   /**

    * Check if two {@link BaseRecord} objects are equal from the point of view of the {@code data} array.

    * <p>

    * <strong>To be noted</strong>, that this method accesses the {@code data} arrays directly without using 

    * any getter. This provides faster access, however should be changed if not all fields are hydrated and

    * access is mandatory from a getter.

    *

    * @param  otherRecord

    *         The instance to compare against.

    *

    * @return True if the {@code data} arrays are equal, false - otherwise

    */

   public boolean equalData(BaseRecord otherRecord)

   {

      if (this.getLength() != otherRecord.getLength())

      {

         return false;

      }

      for  (int i = 0; i < this.getLength(); i++)

      {

         if (this.areAllPropertiesLive() && otherRecord.areAllPropertiesLive())

         {

            return Arrays.equals(this.getData(), otherRecord.getData());

         }

      }

      for  (int i = 0; i < this.getLength(); i++)

      {

         if (!Objects.equals(getDatum(i), otherRecord.getDatum(i)))

         {

            return false;

         }

      }

      return true;

   }

   /**

    * Copy an array of objects into data.

    * 

    * @param   from

    *          The source to copy from.

    */

   public void copyArray(Object[] from)

   {

      System.arraycopy(from, 0, data, 0, getLength());

         setSimpleDatum(i, activePropPreviousValues[i]);

         .append("read: ").append(readFields).append(sep)

         .append("live: ").append(liveProps).append(sep)

         int len = getLength();

            buf.append(getSimpleDatum(i));

      return getData();

      return getData();

   }

   /**

    * Get the data property.

    * 

    * @return   The value of the data property.

    */

   public Object[] getData()

   {

   /**

    * Get the size of the data property.

    * 

    * @return  Size of the data property.

    */

   public int getLength()

   {

      return data.length;

   }

      Object activeOffsetDatum = getDatum(actualIndex);

      if (dirtyProps.get(actualIndex) &&

         !Objects.equals(activePropPreviousValues[actualIndex], activeOffsetDatum))

         res[1] = activeOffsetDatum;

   }  

   /**

    * This should be called when the record is re-attached to a new session. This way, we refresh the 

    * underlying session in hydrator (if any) to properly refresh the record when needed. If this is 

    * not used, we may face {@link LazyHydrationException} due to stale sessions in the hydrator. 

    * 

    * First time a hydrator is created, it will take the session from the generator result-set, thus,

    * there is no need to call this method in that case.

    * 

    * @param   session

    *          The session to which this record is re-attached.

    */

   public void refreshHydrator(Session session)

   {

      if (hydrator != null)

      {

         hydrator.refresh(session);

      }

   }

   /**

    * Sets the bit in {@link BaseRecord#liveProps} to true, meaning that the field at that index has been 

    * read or written.

    * 

    * @param offset

    *        Zero-based offset of the datum in the data array, which corresponds to the index in 

    *        {@link BaseRecord#liveProps}

    */

   protected void setLivePropsAtOffset(int offset)

   {

      if (liveProps != null)

      {

         if (!liveProps.get(offset))

         {

            livePropsCardinality++;

         }

         liveProps.set(offset);

      }

   }

   protected void setAllLiveProps()

   {

      if (liveProps == null)

      {

         return;

      }

      for (int i = 0; i < data.length; i++)

      {

         liveProps.set(i);

      }

   }

   {      

      Object offsetDatum = getDatum(offset);

      activePropPreviousValues[offset] = offsetDatum;

      if (readFields != null)

      {

         readFields.set(offset);

      }

      if (!(Objects.equals(offsetDatum, datum) || 

             offsetDatum != null        && 

             ((Comparable) datum).compareTo(offsetDatum) == 0)))

         setSimpleDatum(offset, datum);

         if (fromProp.getType() != toProp.getType() || fromProp.getExtent() != toProp.getExtent())

         Object offsetDatum = getDatum(toOffset);

         if (!(Objects.equals(offsetDatum, datum) || 

               offsetDatum != null && 

               ((Comparable) datum).compareTo(offsetDatum) == 0)))

         setSimpleDatum(offset, datum);

    * Get the field's value at the specified offset, with {@code null} indicating unknown value.

    * <p>

    * N.B.: if lazy hydration can be active for this record, callers must catch and handle the unchecked

    * {@code LazyHydrationException}.

    * 

    * @param   offset

    *          Zero-based offset of the datum in the data array.

    * 

    * @return  The field's value, with {@code null} indicating unknown value.

    * 

    * @throws  LazyHydrationException

    *          if this record is enabled for lazy hydration, but the attached hydrator was no longer valid.

    *          Although this is an unchecked exception to allow the DMO to be generated with simple getter

    *          methods, callers which invoke this method when lazy hydration could be active MUST catch and

    *          handle this exception.

   throws LazyHydrationException

      // runtime-feedback probe: record that this field was demanded during the current visit. Placed

      // before the hydrator block because eager records have hydrator == null and would otherwise be

      // invisible. Gated on a single volatile read so steady state (feature off / all verdicts

      // locked) costs nothing more.

      if (PROBING_ACTIVE)

      {

         BitSet acc = accessed;

         if (acc != null)

         {

            acc.set(offset);

         }

      }

      if (hydrator != null && liveProps != null && !liveProps.get(offset))

      {

         boolean success = hydrator.hydrate(this, offset, getHydratorRowOffset(), true);

         if (success)

         {

            countHydratedFieldsWithLZS(1);

         }

         if (!success)

         {

            BitSet unhydratedFields = getUnhydratedFields();

            hydrator.refresh(this, id, unhydratedFields);

            countHydratedFieldsWithLoader(unhydratedFields.cardinality());

         }

         if (!success || livePropsCardinality == data.length)

         {

            hydrator = null;

            liveProps = null;

            livePropsCardinality = data.length;

         }

      }

   /**

    * Switch the process-wide probing fast-path gate on or off. Called by {@link FieldUsageProfile}

    * as profiles are created and as their verdicts lock in.

    *

    * @param   active

    *          The new value of {@link #PROBING_ACTIVE}.

    */

   static void setProbingActive(boolean active)

   {

      PROBING_ACTIVE = active;

   }

   /**

    * Arm the runtime-feedback hydration probe for the given profile: while the profile is still

    * learning, this record records which fields are read (via {@link #getDatum}) and reports the

    * sample when the buffer leaves it (see {@link #reportDemandSample}). Hydration itself stays eager

    * — only the demand is observed. No-op when the profile is {@code null} or already locked.

    *

    * @param   profile

    *          The call-site profile to probe for, or {@code null}.

    */

   void armUsageProbe(FieldUsageProfile profile)

   {

      if (profile == null || !profile.isUnknown())

      {

         return;