# RecordIdentifier.java

    /*
    ** Module   : RecordIdentifier.java
    ** Abstract : Unique external identifier for a database record
    **
    ** Copyright (c) 2004-2020, Golden Code Development Corporation.
    **
    ** -#- -I- --Date-- --JPRM-- -----------------------------------Description-----------------------------------
    ** 001 ECF 20070411   @32989 Created initial version. Unique external identifier for a database record.
    ** 002 ECF 20071128   @36053 Implement Serializable. Allows use over the network.
    ** 003 VMN 20130830          Made class not-final to TableIdentifier.
    ** 004 ECF 20150801          Performance improvements.
    ** 005 ECF 20160515          Pre-compute immutable hash code.
    ** 006 ECF 20200906          New ORM implementation.
    ** 007 EVL 20200622          Changed exception type raised in constructor to ERROR condition.
    ** 008 IAS 20200914          Re-work (de)serialization
    */

    /*
    ** 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 static com.goldencode.util.NativeTypeSerializer.*;
    import java.io.*;
    import com.goldencode.p2j.util.*;

    /**
     * A combination of database table reference (either the table name, DMO interface, or DMO implementation
     * class) and record ID (primary key), which uniquely identifies a database record.
     * <p>
     * Normally, if the initial import is done with FWD, and anyone creating new records always uses the
     * {@code p2j_id_generator_sequence} for new keys, the {@code Long} {@code recordID} component will unique
     * identify records by itself (FWD keys are guaranteed to be unique across all tables of a database). Adding
     * the {@code table} component (although redundant in normal execution of FWD) will only make it safer (when
     * records are created in a non-standard way), even if at a bit performance penalty.
     * @param <T>
     *        table reference type
     */
    public class RecordIdentifier<T extends Serializable>
    implements Externalizable
    {
       /** Table identifier */
       private T table;

       /** Primary key of a database record */
       private Long recordID;

       /** Cached hash code */
       private int hashCode;

       /** Default constructor */
       public RecordIdentifier()
       {
          super();
       }

       /**
        * Constructor.
        *
        * @param   table
        *          Table identifier.
        * @param   recordID
        *          Primary key.
        *
        * @throws  ErrorConditionException
        *          if any parameter is <code>null</code>.
        */
       public RecordIdentifier(T table, Long recordID)
       {
          if (table == null)
          {
             throw new ErrorConditionException("Table must be non-null");
          }

          if (recordID == null)
          {
             throw new ErrorConditionException("Record ID must be non-null");
          }

          this.table = table;
          this.recordID = recordID;

          // compute immutable hash code; the most common use case for this class is as a hash key
          int hc = 17 * 37 + table.hashCode();
          this.hashCode = 37 * hc + recordID.hashCode();
       }

       /**
        * Get the database table name.
        *
        * @return  Table name.
        */
       public T getTable()
       {
          return table;
       }

       /**
        * Get the record's primary key.
        *
        * @return  Primary key.
        */
       public Long getRecordID()
       {
          return recordID;
       }

       /**
        * Overridden equivalence test which takes all data values of this object into account.
        *
        * @param   o
        *          Another {@code LockRecord} instance to test for equivalence with this instance.
        *
        * @return  {@code true} if both instances have the same values for table and record ID, else
        *          {@code false}.
        */
       @Override
       public boolean equals(Object o)
       {
          if (this == o)
          {
             return true;
          }

          if (!(o instanceof RecordIdentifier))
          {
             return false;
          }

          RecordIdentifier<T> that = (RecordIdentifier<T>) o;

          return table.equals(that.table) && recordID.equals(that.recordID);
       }

       /**
        * Overridden implementation to maintain consistency with overridden {@link #equals} method.
        *
        * @return  Hash code for this instance.
        */
       @Override
       public int hashCode()
       {
          return hashCode;
       }

       /**
        * Compose a string representation of this object for assistance in debugging and testing.
        *
        * @return  String representation of this object's internal state.
        */
       @Override
       public String toString()
       {
          return table.toString() + ':' + recordID;
       }

       /**
        * Replacement for the default object writing method.
        *
        * @param    out
        *           The output destination to which fields will be saved.
        *
        * @throws   IOException
        *           In case of I/O errors.
        */
       @Override
       public void writeExternal(ObjectOutput out) throws IOException
       {
          out.writeObject(table);
          writeLong(out, recordID);
          out.writeInt(hashCode);
       }

       /**
        * Replacement for the default object reading method.
        *
        * @param    in
        *           Input source from which fields will be restored.
        *
        * @throws   IOException
        *           In case of I/O errors.
        * @throws   ClassNotFoundException
        *           If payload can't be instantiated.
        */
       @Override
       public void readExternal(ObjectInput in) throws IOException, ClassNotFoundException
       {
          table = (T)in.readObject();
          recordID = readLong(in);
          hashCode = in.readInt();
       }
    }