// This Source Code is in the Public Domain per: http://litesoft.org/License.txt
package org.litesoft.orsup.nonpublic;

import java.io.*;
import java.sql.*;
import java.util.*;

import org.litesoft.bo.*;
import org.litesoft.changemanagement.ServerStateChange.*;
import org.litesoft.core.*;
import org.litesoft.core.util.*;
import org.litesoft.db.*;
import org.litesoft.encryption.symmetric.*;
import org.litesoft.orsup.base.*;
import org.litesoft.orsup.lazyload.*;
import org.litesoft.orsup.otherattributeaccessors.*;
import org.litesoft.orsup.selection.*;
import org.litesoft.orsup.selection.nonpublic.IllegalArgument;
import org.litesoft.orsup.selection.nonpublic.*;
import org.litesoft.orsup.transact.*;
import org.litesoft.sequences.*;
import org.litesoft.util.*;

public abstract class PersistentObjectImpl<T extends PersistentObjectImpl> implements LLPersistentObject<T>
{
    @SuppressWarnings({"UnusedDeclaration"})
    protected static final WhereClauseFactory WCF = WhereClauseFactory.INSTANCE;

    public static final int INITIAL_CHANGE_NUMBER = 0;

    protected MetaDataForPO mMetaDataForPO;
    private boolean mNew;
    private boolean mRehydrating;

    private boolean mForcedUpdate = false;
    private boolean mForcedChangeNotification = false;

    private Transaction mTransaction = null;
    private NonTransactionalFinder mNonTransactionalFinder = null;
    private boolean mDeleteRequested = false;
    private OriginalValueChangeTracker<T> mChangeTracker = OriginalValueChangeTrackerNull.getInstance();
    private LazyLoadedsTracker mLazyLoadedsTracker = LazyLoadedsTrackerNull.INSTANCE;
    private int mChangeNumber = INITIAL_CHANGE_NUMBER;

    private PersistentObjectImpl( MetaDataForPO pMetaDataForPO, Transaction pTransaction, boolean pNew, ConstructionControl pConstructionControlExpected, ConstructionControl pConstructionControlActual )
    {
        mMetaDataForPO = pMetaDataForPO;
        mNew = pNew;
        if ( pNew )
        {
            IllegalArgument.ifNull( "Transaction on New PO", pTransaction );
            mTransaction = pTransaction;
            mNonTransactionalFinder = pTransaction.getNonTransactionalFinder();
            mRehydrating = false;
            incChangeNumber();
        }
        else
        {
            IllegalArgument.ifNotNull( "Transaction on Rehydrating PO", pTransaction );
            mRehydrating = true;
        }
        if ( pConstructionControlExpected != pConstructionControlActual )
        {
            throw new IllegalStateException( "Invalid attempt to Construct with ConstructionControl" );
        }
    }

    @SuppressWarnings({"unchecked"})
    protected void setDefaults()
    {
        for ( AttributeAccessorSCD zSCD : getMetaDataForPO().getAccessorSCDs() )
        {
            Object zDefault = zSCD.getDefault();
            if ( zDefault != null )
            {
                zSCD.setValueOnPO( this, zDefault );
            }
        }
    }

    protected PersistentObjectImpl( MetaDataForPO pMetaDataForPO, Transaction pTransaction ) // Only used for New
    {
        this( pMetaDataForPO, pTransaction, true, null, null );
    }

    protected PersistentObjectImpl( MetaDataForPO pMetaDataForPO, ConstructionControl pConstructionControlExpected, ConstructionControl pConstructionControlActual )
    {
        this( pMetaDataForPO, null, false, pConstructionControlExpected, pConstructionControlActual );
    }

    protected void registerWithTransaction()
    {
        PersistentObjectImpl<T> po = getTransactionBackdoor().addPO( this );
        if ( po != this ) // Identity check / this method called outside of 'new' constructor
        {
            throw new IllegalStateException( "Apparently 'new' object already in Transaction?\nthis=" + this );
        }
    }

    protected long getNextSequenceNumber( String pGroup )
    {
        return getSequenceSource().getNextSequenceNumber( pGroup );
    }

    protected long getNextSequenceNumber( Class pGroup )
    {
        return getSequenceSource().getNextSequenceNumber( pGroup );
    }

    protected SequenceSource getSequenceSource()
    {
        return getFinder().getSequenceSource();
    }

    @Override
    public SymmetricEncryptorManager getEncryptorManager()
    {
        return getFinder().getEncryptorManager();
    }

    @SuppressWarnings({"unchecked"})
    public void setCommitTimestamps( Timestamp pTransactionTimeStamp )
    {
        ((MetaDataForPOinternalExtension) getMetaDataForPO()).setCommitTimestamps( this, pTransactionTimeStamp );
    }

    /**
     * @return the Finder associated with this PO, either the Transaction of the NonTransactionalFinder
     */
    @Override
    public final Finder getFinder()
    {
        Transaction transaction = getTransaction();
        return (transaction != null) ? transaction : getNonTransactionalFinder();
    }

    @Override
    public final NonTransactionalFinder<?> getNonTransactionalFinder()
    {
        return mNonTransactionalFinder;
    }

    @Override
    public final Transaction getTransaction()
    {
        return mTransaction;
    }

    @Override
    public String getObjectName()
    {
        return getMetaDataForPO().getIdentifierName();
    }

    @Override
    public String getRegisteredName()
    {
        return getClass().getName();
    }

    @Override
    public final boolean isImmortal()
    {
        MetaDataForPO md = getMetaDataForPO();
        switch ( md.getMortality() )
        {
            default:
            case Mortal:
                return false;
            case Immortal:
                return true;
            case InstanceImmortal:
                String name = md.getInstanceImmortalImmortalAttributeName();
                Object value = getAttributeValue( name );
                return Boolean.TRUE.equals( value );
        }
    }

    @Override
    public final boolean isUpdatable()
    {
        MetaDataForPO md = getMetaDataForPO();
        if ( !md.isUpdatable() )
        {
            return false;
        }
        String name = md.getInstanceManagedUpdatabilityLockedAttributeName();
        if ( name != null )
        {
            Object value = getAttributeValue( name );
            return !Boolean.TRUE.equals( value );
        }
        return true;
    }

    @Override
    public void requestDelete()
    {
        verifyMutability();
        if ( mTransaction instanceof TransactionBackdoor )
        {
            if ( !((TransactionBackdoor) mTransaction).getApprovalFromDeleteAugmentors( this ) )
            {
                return;
            }
        }
        if ( isImmortal() )
        {
            String name = getMetaDataForPO().getImmortalInactiveAttributeName();
            setAttributeValue( name, Boolean.TRUE );
        }
        else
        {
            mDeleteRequested = true;
            incChangeNumber();
            List<AbstractAttributeAccessorSCDtoPO> zNonDependents = new ArrayList<AbstractAttributeAccessorSCDtoPO>();
            // Do the "ThemDependsOnUs"s 1st
            for ( AttributeAccessorSCD acd : getMetaDataForPO().getAccessorSCDs() )
            {
                if ( acd instanceof AbstractAttributeAccessorSCDtoPO )
                {
                    AbstractAttributeAccessorSCDtoPO zToPO = (AbstractAttributeAccessorSCDtoPO) acd;
                    if ( zToPO.isThemDependantOnUs() )
                    {
                        clrValueOnPO( zToPO );
                    }
                    else
                    {
                        zNonDependents.add( zToPO );
                    }
                }
            }
            for ( AbstractAttributeAccessorSCDtoPO acd : zNonDependents )
            {
                clrValueOnPO( acd );
            }
        }
    }

    @SuppressWarnings({"unchecked"})
    private void clrValueOnPO( AbstractAttributeAccessorSCDtoPO pAcdToPO )
    {
        pAcdToPO.clrValueOnPO( this );
    }

    @Override
    public final boolean isDeleteRequested()
    {
        return mDeleteRequested;
    }

    @Override
    public final boolean isNew()
    {
        return mNew;
    }

    @Override
    public int numberOfAttributeChanged()
    {
        return mChangeTracker.numberOfChanges();
    }

    @Override
    public final boolean isAnyAttributeChanged()
    {
        return mChangeTracker.hasChanges();
    }

    @Override
    public boolean isAttributeChanged( String pAttributeName )
    {
        return isAttributeChanged( getAccessorSCDoptional( pAttributeName ) );
    }

    @Override
    public boolean isAttributeChanged( AttributeAccessorSCD pAttributeAccessorSCD )
    {
        return (pAttributeAccessorSCD != null) && mChangeTracker.hasChangeFor( pAttributeAccessorSCD.getName() );
    }

    @Override
    public String[] getChangedAttributeNames()
    {
        return mChangeTracker.getChangedAttributeNames();
    }

    @Override
    public Object getOriginalValueFor( String pAttributeName )
    {
        AttributeAccessorSCD<T> zSCD = getAccessorSCDoptional( pAttributeName );
        if ( zSCD == null )
        {
            return null;
        }
        pAttributeName = zSCD.getName();
        if ( mChangeTracker.hasChangeFor( pAttributeName ) )
        {
            return mChangeTracker.getOriginalValueFor( pAttributeName );
        }
        return getAttributeValue( pAttributeName );
    }

    @Override
    public final boolean willTossFromTransactionCommit()
    {
        return (isNew() && isDeleteRequested()) || !isDirty();
    }

    @Override
    public final boolean isDirty()
    {
        return isDeleteRequested() || isNew() || mForcedUpdate || isAnyAttributeChanged();
    }

    @Override
    public void forceUpdate()
    {
        verifyMutability();
        mForcedUpdate = true;
    }

    private void changeToManyDueToOne()
    {
        if ( getMetaDataForPO().isRecordVersionable() )
        {
            mForcedUpdate = true;
            incChangeNumber();
        }
    }

    private void changeToManyDueToOne( PersistentObjectImpl pPO )
    {
        if ( pPO != null )
        {
            pPO.changeToManyDueToOne();
        }
    }

    private void changeNotifyToManyDueToOne( PersistentObjectImpl pPO )
    {
        if ( pPO != null )
        {
            pPO.forceChangeNotification();
        }
    }

    @Override
    public void forceChangeNotification()
    {
        verifyMutability();
        mForcedChangeNotification = true;
    }

    @Override
    public boolean isForcedChangeNotification()
    {
        return mForcedChangeNotification;
    }

    @Override
    public Object getAttributeValue( String pAttributeName )
            throws NoSuchElementException
    {
        //noinspection unchecked
        return getAccessorSCDrequired( pAttributeName ).getValueOnPO( (T) this );
    }

    @Override
    public void setAttributeValue( String pAttributeName, Object pValue )
            throws NoSuchElementException, AttributeIllegalArgumentException
    {
        try
        {
            //noinspection unchecked
            getAccessorSCDrequired( pAttributeName ).setValueOnPO( (T) this, pValue );
        }
        catch ( IllegalArgumentException e )
        {
            throw new AttributeIllegalArgumentException( pAttributeName, pValue, e );
        }
    }

    @Override
    public void addToAttributeSet( String pAttributeName, PersistentObject<?> pPOtoAdd )
            throws NoSuchElementException, AttributeIllegalArgumentException
    {
        if ( pPOtoAdd != null )
        {
            try
            {
                //noinspection unchecked
                getAccessorSCDtoManyrequired( pAttributeName ).addValueOnPO( this, pPOtoAdd );
            }
            catch ( IllegalArgumentException e )
            {
                throw new AttributeIllegalArgumentException( pAttributeName, pPOtoAdd, e );
            }
        }
    }

    @Override
    public void removeFromAttributeSet( String pAttributeName, PersistentObject<?> pPOtoRemove )
            throws NoSuchElementException, AttributeIllegalArgumentException
    {
        if ( pPOtoRemove != null )
        {
            try
            {
                //noinspection unchecked
                getAccessorSCDtoManyrequired( pAttributeName ).removeValueOnPO( this, pPOtoRemove );
            }
            catch ( IllegalArgumentException e )
            {
                throw new AttributeIllegalArgumentException( pAttributeName, pPOtoRemove, e );
            }
        }
    }

    protected AbstractAttributeAccessorSCDtoMany getAccessorSCDtoManyrequired( String pAttributeName )
            throws NoSuchElementException
    {
        AttributeAccessorSCD<T> zSCD = getAccessorSCDrequired( pAttributeName );
        if ( zSCD instanceof AbstractAttributeAccessorSCDtoMany )
        {
            return (AbstractAttributeAccessorSCDtoMany) zSCD;
        }
        throw new NoSuchElementException( "'" + pAttributeName + "' Not a 'Set' on PO type: " + getMetaDataForPO().getIdentifierName() );
    }

    @Override
    public final ObjectHandle getObjectHandle()
    {
        return new ObjectHandle( getPersistentObjectURL(), getDisplayValue() );
    }

    @Override
    public final PersistentObjectURL getPersistentObjectURL()
    {
        return new PersistentObjectURL( getRegisteredName(), getPersistentObjectUniqueKey() );
    }

    private PersistentObjectUniqueKey mKey = null;

    @Override
    public final PersistentObjectUniqueKey getPersistentObjectUniqueKey()
    {
        if ( mKey == null )
        {
            if ( null == (mKey = createPersistentObjectUniqueKey()) )
            {
                mKey = new PersistentObjectUniqueKeyForInstance( this );
            }
        }
        return mKey;
    }

    protected final PersistentObjectUniqueKey createPersistentObjectUniqueKey()
    {
        AttributeAccessorKeySet keySet = getMetaDataForPO().getKeySet();
        if ( keySet == null )
        {
            return null;
        }
        AttributeAccessorSCD<PersistentObject<?>>[] zAASCDs = keySet.getKeyAttributeAccessorSCDs();
        return (zAASCDs.length == 1) ? new UniqueKeySingle( this, zAASCDs[0] ) : new UniqueKeyMulti( this, zAASCDs );
    }

    private void forcePersistentObjectUniqueKeyToMatch( PersistentObjectImpl pCommonPairedThem )
    {
        AttributeAccessorKeySet zThisKeySet = this.getMetaDataForPO().getKeySet();
        AttributeAccessorKeySet zThemKeySet = pCommonPairedThem.getMetaDataForPO().getKeySet();
        if ( (zThisKeySet != null) && (zThemKeySet != null) )
        {
            AttributeAccessorSCD<PersistentObject<?>>[] zThisAASCDs = zThisKeySet.getKeyAttributeAccessorSCDs();
            AttributeAccessorSCD<PersistentObject<?>>[] zThemAASCDs = zThemKeySet.getKeyAttributeAccessorSCDs();
            if ( (zThisAASCDs.length == 1) && (zThemAASCDs.length == 1) )
            {
                AttributeAccessorSCD<PersistentObject<?>> zThisKey = zThisAASCDs[0];
                AttributeAccessorSCD<PersistentObject<?>> zThemKey = zThemAASCDs[0];
                if ( zThisKey.getColumnType().equals( zThemKey.getColumnType() ) )
                {
                    PersistentObjectURL zOrigURL = this.getPersistentObjectURL();
                    zThisKey.db_setValueOnPO( this, zThemKey.db_getValueOnPO( pCommonPairedThem ) ); // Between this line and the Next the Display Value will report as the old Key!
                    mKey = null; // .................................................................... Clear Cached Key
                    PersistentObjectURL zNewURL = this.getPersistentObjectURL();
                    getTransaction().changedURL( zOrigURL, zNewURL );
                    return;
                }
            }
        }
        throw new IllegalStateException( "Incompatible KeySets for '" + this + "' & '" + pCommonPairedThem + "'" );
    }

    /**
     * @return non-Transactional copy of the latest version of this PO, or Null if the PO is in a Transaction and isNew() OR has been deleted
     */
    @Override
    public final T refreshNonTransactionally()
    {
        return getNonTransactionalFinder().refresh( this );
    }

    /**
     * Refresh this PO into the provided transaction.
     *
     * @param pTransaction !null
     *
     * @return Transactional copy of the latest version read via Transaction, or Null if the PO is in another Transaction and isNew() OR has been deleted
     *
     * @throws UnsupportedOperationException - if the PO is already in the Transaction
     */
    @Override
    public final T refreshInto( Transaction pTransaction )
            throws UnsupportedOperationException
    {
        IllegalArgument.ifNull( "Transaction", pTransaction );
        return pTransaction.refreshInto( this );
    }

    /**
     * Refresh this PO into the provided transaction if needed.
     *
     * @param pTransaction !null
     *
     * @return Transactional copy of the latest version read via Transaction (if it is not already in the Transaction), or Null if the PO is in another Transaction and isNew() OR has been deleted
     */
    public T freshIntoIfNotAlreadyIn( Transaction pTransaction )
    {
        IllegalArgument.ifNull( "Transaction", pTransaction );
        return pTransaction.freshIntoIfNotInTransaction( this );
    }

    /**
     * @return this if it is already in the Transaction, or a COPY of this in the specified Transaction
     */
    @Override
    public final T copyInto( Transaction pTransaction )
            throws UnsupportedOperationException
    {
        IllegalArgument.ifNull( "Transaction", pTransaction );
        PersistentObject existing = (pTransaction == getTransaction()) ? this : pTransaction.getPersistentObjectFromIdentityMap( getPersistentObjectURL() );
        if ( existing != null )
        {
            //noinspection unchecked
            return (T) existing;
        }
        // todo: What if !new and in another Transaction & changed ????
        MetaDataForPOinternalExtension helper = (MetaDataForPOinternalExtension) getMetaDataForPO();
        //noinspection unchecked
        T them = (T) helper.createPOfromFinder();
        for ( AttributeAccessorSCD acd : helper.getPersistingAccessorSCDs() )
        {
            //noinspection unchecked
            acd.db_setValueOnPO( them, acd.db_getValueOnPO( this ) );
        }
        //noinspection unchecked
        them = (T) them.rehydrationComplete( pTransaction );
        them.mNew = this.mNew;
        return them;
    }

    /**
     * Called on each PO that is in the Transaction (found/read, copyInto, or LazyLoaded)
     *
     * @param pTransactionTimestamp
     *
     * @return any value (should probably NOT be the PO) that you want passed along in the DataStoreChange
     */
    public Serializable aboutToCommit( Timestamp pTransactionTimestamp )
    {
        return null;
    }

    @Override
    public String getDisplayValue()
    {
        String format = Utils.deNull( getMetaDataForPO().getDisplayValueFormat() ).trim();
        if ( format.length() == 0 )
        {
            return "Display Value (" + getObjectName() + "): " + getPersistentObjectUniqueKey();
        }
        int from = 0;
        StringBuilder sb = new StringBuilder();
        for ( int at; -1 != (at = format.indexOf( "${", from )); from = at + 1 )
        {
            if ( at != from )
            {
                sb.append( format.substring( from, at ) );
            }
            int end = format.indexOf( '}', at + 2 );
            if ( end == -1 )
            {
                from = at;
                break;
            }
            String attr = format.substring( at + 2, end );
            at = end;
            try
            {
                Object value = getAttributeValue( attr );
                if ( value != null )
                {
                    sb.append( value );
                }
            }
            catch ( NoSuchElementException e )
            {
                sb.append( "${" ).append( attr ).append( '}' );
            }
        }
        return sb.append( format.substring( from ) ).toString();
    }

    @Override
    public Object toSqlValueForEquals()
    {
        PersistentObjectUniqueKey key = getPersistentObjectUniqueKey();
        if ( key instanceof SQLvalueable )
        {
            return ((SQLvalueable) key).toSQLvalue();
        }
        if ( key instanceof WhereClauseToSQLable )
        {
            return ((WhereClauseToSQLable) key).toSqlValueForEquals();
        }
        throw new UnsupportedOperationException( "WhereClause support constrained to non-new POs with a single column unique key.  Not: " + (isNew() ? " New " : "") + getObjectName() + "s." );
    }

    public final boolean equals( PersistentObject pThem )
    {
        return (this == pThem) || ((pThem != null) && this.getPersistentObjectURL().equals( pThem.getPersistentObjectURL() ));
    }

    @Override
    public final boolean equals( Object o )
    {
        return (this == o) || ((o instanceof PersistentObject) && equals( (PersistentObject) o ));
    }

    @Override
    public final int hashCode()
    {
        return getPersistentObjectURL().hashCode();
    }

    @Override
    public final String toString()
    {
        return getDisplayValue();
    }

    public final <Them extends PersistentObjectImpl> List<Them> //
    processLazyLoadAccess( AbstractLazyLoadToMany<T, Them> pValueHolder )
            throws UnsupportedOperationException
    {
        addToLazyLoadeds( pValueHolder );
        return pValueHolder.getValue();
    }

    public final <Them extends PersistentObjectImpl> void //
    processLazyLoadMutation( AbstractLazyLoadToMany<T, Them> pValueHolder, //
                             List<Them> pNewValue )
            throws UnsupportedOperationException
    {
        addToLazyLoadeds( pValueHolder );
        verifyMutability( pValueHolder.getSCDtoMany() );
        if ( (pNewValue != null) && !pNewValue.isEmpty() && anyNotInOurTransaction( pNewValue ) )
        {
            List<Them> zNewPOs = new ArrayList<Them>( pNewValue.size() );
            for ( Them zThem : pNewValue )
            {
                if ( zThem != null )
                {
                    zNewPOs.add( genericSuppressedCopyIntoOurTransaction( zThem ) );
                }
            }
            pNewValue = zNewPOs;
        }
        pValueHolder.setValues( pNewValue );
    }

    private <Them extends PersistentObjectImpl> boolean anyNotInOurTransaction( List<Them> pNotEmptyPOs )
    {
        for ( Them zThem : pNotEmptyPOs )
        {
            if ( (zThem != null) && (zThem.getTransaction() != this.getTransaction()) )
            {
                return true;
            }
        }
        return false;
    }

    public final <Them extends PersistentObjectImpl> void //
    processLazyLoadMutationAdd( AbstractLazyLoadToMany<T, Them> pValueHolder, //
                                Them pNewValue )
            throws UnsupportedOperationException
    {
        if ( pNewValue != null )
        {
            addToLazyLoadeds( pValueHolder );
            verifyMutability( pValueHolder.getSCDtoMany() );
            pValueHolder.addValue( genericSuppressedCopyIntoOurTransaction( pNewValue ) );
        }
    }

    public final <Them extends PersistentObjectImpl> void //
    processLazyLoadMutationRemove( AbstractLazyLoadToMany<T, Them> pValueHolder, //
                                   Them pNewValue )
            throws UnsupportedOperationException
    {
        if ( pNewValue != null )
        {
            addToLazyLoadeds( pValueHolder );
            verifyMutability( pValueHolder.getSCDtoMany() );
            pValueHolder.removeValue( genericSuppressedCopyIntoOurTransaction( pNewValue ) );
        }
    }

    public final <Them extends PersistentObjectImpl> Them //
    processLazyLoadAccess( LazyLoadToOneRegular<T, Them> pValueHolder )
            throws UnsupportedOperationException
    {
        addToLazyLoadeds( pValueHolder );
        return pValueHolder.getValue();
    }

    public final <Them extends PersistentObjectImpl> void //
    processLazyLoadMutation( LazyLoadToOneRegular<T, Them> pValueHolder, //
                             Them pNewThem )
            throws UnsupportedOperationException
    {
        verifyMutability();
        Them zCurThem = processLazyLoadAccess( pValueHolder );
        Object oldKey = pValueHolder.db_getValue();
        Object newKey = null;
        if ( pNewThem != null )
        {
            pNewThem = genericSuppressedCopyIntoOurTransaction( pNewThem );
            newKey = pValueHolder.extract_db_value( pNewThem );
        }
        AttributeAccessorSCDtoOneRegular<T, Them> acdToPO = pValueHolder.getSCDtoOne();
        if ( verifyMutabilityOnChangeToOne( acdToPO, //
                                            zCurThem, oldKey, //
                                            pNewThem, newKey ) )
        {
            pValueHolder.setValue( pNewThem );
        }
    }

    public final <Them extends PersistentObjectImpl> Them //
    processLazyLoadAccess( LazyLoadToOnePaired<T, Them> pValueHolder )
            throws UnsupportedOperationException
    {
        addToLazyLoadeds( pValueHolder );
        return pValueHolder.getValue();
    }

    protected final PersistentObjectImpl //
    processLazyLoadAccess( LazyLoadToOneCommonPaired<T> pValueHolder )
            throws UnsupportedOperationException
    {
        addToLazyLoadeds( pValueHolder );
        return pValueHolder.getValue();
    }

    protected final void //
    processLazyLoadMutation( LazyLoadToOneCommonPaired<T> pValueHolder, //
                             PersistentObjectImpl pNewThem )
            throws UnsupportedOperationException
    {
        verifyMutability();
        PersistentObjectImpl zCurThem = processLazyLoadAccess( pValueHolder );
        Object oldKey = pValueHolder.db_getValue();
        Object newKey = null;
        if ( pNewThem != null )
        {
            pNewThem = genericSuppressedCopyIntoOurTransaction( pNewThem );
            newKey = pValueHolder.extract_db_value( pNewThem, null );
        }
        AttributeAccessorSCDtoOneCommonPaired<T> acdToPO = pValueHolder.getSCDtoOne();
        if ( verifyMutabilityOnChangeToOne( acdToPO, //
                                            zCurThem, oldKey, //
                                            pNewThem, newKey ) )
        {
            //noinspection ConstantConditions
            pNewThem.forcePersistentObjectUniqueKeyToMatch( this );
            pValueHolder.setValue( pNewThem );
        }
    }

    protected final PersistentObjectImpl //
    processLazyLoadAccess( LazyLoadToOneVariable<T> pValueHolder )
            throws UnsupportedOperationException
    {
        addToLazyLoadeds( pValueHolder );
        return pValueHolder.getValue();
    }

    protected final void //
    processLazyLoadMutation( LazyLoadToOneVariable<T> pValueHolder, //
                             PersistentObjectImpl pNewThem, //
                             String pBackRefAttributeNameOnNewThem )
            throws UnsupportedOperationException
    {
        verifyMutability();
        PersistentObjectImpl zCurThem = processLazyLoadAccess( pValueHolder );
        Object oldKey = pValueHolder.db_getValue();
        Object newKey = null;
        if ( pNewThem != null )
        {
            pNewThem = genericSuppressedCopyIntoOurTransaction( pNewThem );
            newKey = pValueHolder.extract_db_value( pNewThem, pBackRefAttributeNameOnNewThem );
        }
        AttributeAccessorSCDtoOneVariable<T> acdToPO = pValueHolder.getSCDtoOne();
        if ( verifyMutabilityOnChangeToOne( acdToPO, //
                                            zCurThem, oldKey, //
                                            pNewThem, newKey ) )
        {
            pValueHolder.setValue( pNewThem, pBackRefAttributeNameOnNewThem );
        }
    }

    public final Blob //
    processLazyLoadAccess( BlobHandler<T> pValueHolder )
            throws UnsupportedOperationException
    {
        addToLazyLoadeds( pValueHolder );
        return pValueHolder.LL_getValue();
    }

    public final void //
    processLazyLoadMutation( BlobHandler<T> pValueHolder, //
                             Blob pNewThem )
            throws UnsupportedOperationException
    {
        verifyMutability();
        Blob zCurThem = processLazyLoadAccess( pValueHolder );
        Object oldKey = pValueHolder.db_getValue();
        Object newKey = null;
        if ( pNewThem != null )
        {
            pNewThem = genericSuppressedCopyIntoOurTransaction( pNewThem );
            newKey = pValueHolder.extract_db_value( pNewThem );
        }
        AttributeAccessorSCDtoBlob<T> acdToPO = pValueHolder.getSCDtoOne();
        if ( verifyMutabilityOnChangeToOne( acdToPO, //
                                            zCurThem, oldKey, //
                                            pNewThem, newKey ) )
        {
            pValueHolder.LL_setValue( pNewThem, null );
        }
    }

    private boolean verifyMutabilityOnChangeToOne( AbstractAttributeAccessorSCDtoOne pSupplimentedSCDtoOne, PersistentObjectImpl pOldThem, Object pOldKey, PersistentObjectImpl pNewThem, Object pNewKey )
    {
        return verifyMutabilityOnChange( pSupplimentedSCDtoOne, //
                                         new ToOneChangeEntry( pOldThem, pOldKey ), //
                                         new ToOneChangeEntry( pNewThem, pNewKey ) );
    }

    @Override
    public final void verifyMutability( SupplimentedSCD pSupplimentedSCD, Object pOldValue, Object pNewValue )
            throws UnsupportedOperationException
    {
        if ( !mRehydrating )
        {
            verifyMutabilityOnChange( pSupplimentedSCD, pOldValue, pNewValue );
        }
    }

    protected final void verifyMutability()
            throws UnsupportedOperationException
    {
        if ( mTransaction == null )
        {
            throw new UnsupportedOperationException( "Attempt to change a read-only (Nontransactional) PersistentObject" );
        }
        if ( !mTransaction.supportsPOmodification( this ) )
        {
            throw new UnsupportedOperationException( "Attempt to change a PersistentObject who's Transaction is currently: " + mTransaction.getState() );
        }
    }

    protected final void verifyMutability( SupplimentedSCD pSupplimentedSCD )
            throws UnsupportedOperationException
    {
        verifyMutability();
        if ( pSupplimentedSCD == null )
        {
            return;
        }
        switch ( pSupplimentedSCD.getMutability() )
        {
            case RW:
                return;
            case AddOnly:
                if ( isNew() )
                {
                    return;
                }
                break;
            case RO:
                if ( pSupplimentedSCD instanceof AttributeAccessorSCDsimplePersistedSysSetOnly )
                {
                    return;
                }
                // Fall Thru
            default:
                break;
        }
        throw new UnsupportedOperationException( "Attempt to change a read-only Attribute (" + pSupplimentedSCD.getName() + ") on a PersistentObject" );
    }

    private void addToLazyLoadeds( AbstractLazyLoadTo pLazyLoadTo )
    {
        mLazyLoadedsTracker = mLazyLoadedsTracker.record( pLazyLoadTo.getAttributeName(), pLazyLoadTo );
    }

    protected AttributeAccessorSCD<T> getAccessorSCDoptional( String pAttributeName )
            throws NoSuchElementException
    {
        //noinspection unchecked
        return getMetaDataForPO().getAccessorSCDoptional( pAttributeName );
    }

    protected AttributeAccessorSCD<T> getAccessorSCDrequired( String pAttributeName )
            throws NoSuchElementException
    {
        //noinspection unchecked
        return getMetaDataForPO().getAccessorSCDrequired( pAttributeName );
    }

    private boolean verifyMutabilityOnChange( SupplimentedSCD pSupplimentedSCD, Object pOldValue, Object pNewValue )
    {
        if ( Utils.areEqual( pOldValue, pNewValue ) )
        {
            return false;
        }
        verifyMutability( pSupplimentedSCD );

        String zAttributeName = pSupplimentedSCD.getName();

        if ( SupplimentedSCD.Form.ToMany.equals( pSupplimentedSCD.getForm() ) )
        {
            throw new IllegalStateException( "Attempt to record change on ToMany attribute (" + zAttributeName + ") on PO (" + this + ") from (" + pOldValue + ") to (" + pNewValue + ")!" );
        }
        if ( pSupplimentedSCD.isPersisted() )
        {
            incChangeNumber();
            recordChange( zAttributeName, pOldValue, pNewValue );
        }
        return true;
    }

    @SuppressWarnings({"unchecked"})
    private void recordChange( String pAttributeName, Object pOldValue, Object pNewValue )
    {
        mChangeTracker = mChangeTracker.recordChange( (T) this, pAttributeName, pOldValue, pNewValue );
    }

    private void changeToManyDueToOne( AbstractAttributeAccessorSCDtoOne pToOne )
    {
        ToOneChangeEntry entry = (ToOneChangeEntry) mChangeTracker.getOriginalValueControlObjectFor( pToOne.getName() );
        if ( entry != null )
        {
            changeToManyDueToOne( entry.getPO() );
        }
        //noinspection unchecked
        changeToManyDueToOne( (PersistentObjectImpl) pToOne.getValueOnPO( this ) );
    }

    private void changeNotifyToManyDueToOne( AbstractAttributeAccessorSCDtoOne pToOne )
    {
        ToOneChangeEntry entry = (ToOneChangeEntry) mChangeTracker.getOriginalValueControlObjectFor( pToOne.getName() );
        if ( entry != null )
        {
            changeNotifyToManyDueToOne( entry.getPO() );
        }
        //noinspection unchecked
        changeNotifyToManyDueToOne( (PersistentObjectImpl) pToOne.getValueOnPO( this ) );
    }

    @SuppressWarnings({"unchecked"})
    private <Them extends PersistentObjectImpl> Them genericSuppressedCopyIntoOurTransaction( Them pNewValue )
    {
        return (Them) pNewValue.copyInto( getTransaction() );
    }

    protected final void incChangeNumber()
    {
        mChangeNumber++;
    }

    @Override
    public final int getChangeNumber()
    {
        return mChangeNumber;
    }

    private void clearChanges()
    {
        mChangeNumber = INITIAL_CHANGE_NUMBER;
        mRehydrating = false;
        mChangeTracker = mChangeTracker.clear();
        mLazyLoadedsTracker = mLazyLoadedsTracker.clear();
    }

    private void backdoorTransactionCommitSucceededDropTransaction()
    {
        mTransaction = null;
    }

    private void backdoorTransactionCommitSucceededClearTransactionalChanges()
    {
        boolean zWasCommitted = !willTossFromTransactionCommit();
        successfulCommitBeforeClear( zWasCommitted );
        for ( AttributeAccessorSCD zSCD : getMetaDataForPO().getAccessorSCDs() )
        {
            //noinspection unchecked
            zSCD.onSuccessfulCommit( this, zWasCommitted );
        }
        mNew = mForcedUpdate = mForcedChangeNotification = false;
        clearChanges();
        if ( zWasCommitted )
        {
            successfulCommit();
        }
    }

    protected void justDeletedInTransaction( DBconnection pDBconnection )
    {
    }

    protected void successfulCommit()
    {
    }

    @SuppressWarnings({"UnusedDeclaration"})
    protected void successfulCommitBeforeClear( boolean pWasCommitted )
    {
    }

    protected void transactionDisposed()
    {
    }

    private PersistentObjectImpl<T> rehydrationComplete( Finder pFinder )
    {
        clearChanges();
        PersistentObjectImpl<T> zResult = this;
        if ( pFinder instanceof NonTransactionalFinder )
        {
            mTransaction = null;
            mNonTransactionalFinder = (NonTransactionalFinder) pFinder;
            zResult.rehydationComplete();
            return zResult;
        }
        if ( pFinder instanceof Transaction )
        {
            mTransaction = (Transaction) pFinder;
            mNonTransactionalFinder = mTransaction.getNonTransactionalFinder();
            zResult = getTransactionBackdoor().addPO( this );
            if ( zResult == this )
            {
                zResult.rehydationComplete();
            }
            return zResult;
        }
        throw new IllegalStateException( "rehydrationComplete, but finder was null" );
    }

    private TransactionBackdoor getTransactionBackdoor()
    {
        if ( mTransaction instanceof TransactionBackdoor )
        {
            return (TransactionBackdoor) mTransaction;
        }
        throw new IllegalStateException( "Transaction(" + mTransaction + "), does NOT implement: TransactionBackdoor" );
    }

    @Override
    public MetaDataForPO getMetaDataForPO()
    {
        return mMetaDataForPO;
    }

    private interface LazyLoadedsTracker
    {
        LazyLoadedsTracker record( String pAttributeName, AbstractLazyLoadTo pLazyLoadTo );

        LazyLoadedsTracker clear();
    }

    private static class LazyLoadedsTrackerNull implements LazyLoadedsTracker
    {
        public static final LazyLoadedsTracker INSTANCE = new LazyLoadedsTrackerNull();

        @Override
        public LazyLoadedsTracker record( String pAttributeName, AbstractLazyLoadTo pLazyLoadTo )
        {
            return new LazyLoadedsTrackerImpl().record( pAttributeName, pLazyLoadTo );
        }

        @Override
        public LazyLoadedsTracker clear()
        {
            return this;
        }
    }

    private static class LazyLoadedsTrackerImpl implements LazyLoadedsTracker
    {
        private Map<String, AbstractLazyLoadTo> mLazyLoadeds = new HashMap<String, AbstractLazyLoadTo>();

        @Override
        public LazyLoadedsTracker record( String pAttributeName, AbstractLazyLoadTo pLazyLoadTo )
        {
            mLazyLoadeds.put( pAttributeName, pLazyLoadTo );
            return this;
        }

        @Override
        public LazyLoadedsTracker clear()
        {
            mLazyLoadeds.clear();
            mLazyLoadeds = null;
            return LazyLoadedsTrackerNull.INSTANCE;
        }
    }

    private interface OriginalValueChangeTracker<T extends PersistentObjectImpl>
    {
        OriginalValueChangeTracker<T> clear();

        int numberOfChanges();

        boolean hasChanges();

        boolean hasChangeFor( String pAttributeName );

        Object getOriginalValueFor( String pAttributeName );

        Object getOriginalValueControlObjectFor( String pAttributeName );

        String[] getChangedAttributeNames();

        OriginalValueChangeTracker<T> recordChange( T pThePo, String pAttributeName, Object pOldValue, Object pNewValue );

        @SuppressWarnings({"UnusedDeclaration"}) PersistentObjectImpl getTheChangedPo();
    }

    private static class OriginalValueChangeTrackerNull<T extends PersistentObjectImpl> implements OriginalValueChangeTracker<T>
    {
        private static final OriginalValueChangeTracker INSTANCE = new OriginalValueChangeTrackerNull();

        @SuppressWarnings({"unchecked"})
        public static <Z extends PersistentObjectImpl> OriginalValueChangeTracker<Z> getInstance()
        {
            return INSTANCE;
        }

        @Override
        public OriginalValueChangeTracker<T> clear()
        {
            return this;
        }

        @Override
        public int numberOfChanges()
        {
            return 0;
        }

        @Override
        public boolean hasChanges()
        {
            return false;
        }

        @Override
        public boolean hasChangeFor( String pAttributeName )
        {
            return false;
        }

        @Override
        public Object getOriginalValueFor( String pAttributeName )
        {
            return null;
        }

        @Override
        public Object getOriginalValueControlObjectFor( String pAttributeName )
        {
            return null;
        }

        @Override
        public String[] getChangedAttributeNames()
        {
            return Utils.EMPTY_STRING_ARRAY;
        }

        @SuppressWarnings({"UnusedDeclaration"})
        public String getOriginalDisplayValue()
        {
            return null;
        }

        @Override
        public PersistentObjectImpl getTheChangedPo()
        {
            return null;
        }

        @Override
        public OriginalValueChangeTracker<T> recordChange( T pThePo, String pAttributeName, Object pOldValue, Object pNewValue )
        {
            OriginalValueChangeTrackerImpl<T> tracker = new OriginalValueChangeTrackerImpl<T>( pThePo );
            tracker.recordChange( pThePo, pAttributeName, pOldValue, pNewValue );
            return tracker;
        }
    }

    private static class OriginalValueChangeTrackerImpl<T extends PersistentObjectImpl> implements OriginalValueChangeTracker<T>
    {
        private Map<String, Object> mAttributeNameToOriginalValues = new HashMap<String, Object>();
        private T mTheChangedPo;

        private OriginalValueChangeTrackerImpl( T pTheChangedPo )
        {
            mTheChangedPo = pTheChangedPo;
        }

        @Override
        public OriginalValueChangeTracker<T> clear()
        {
            mAttributeNameToOriginalValues.clear();
            mAttributeNameToOriginalValues = null;
            return OriginalValueChangeTrackerNull.getInstance();
        }

        @Override
        public int numberOfChanges()
        {
            return mAttributeNameToOriginalValues.size();
        }

        @Override
        public boolean hasChanges()
        {
            return !mAttributeNameToOriginalValues.isEmpty();
        }

        @Override
        public boolean hasChangeFor( String pAttributeName )
        {
            return mAttributeNameToOriginalValues.containsKey( pAttributeName );
        }

        @Override
        public Object getOriginalValueFor( String pAttributeName )
        {
            Object rv = getOriginalValueControlObjectFor( pAttributeName );
            return (rv instanceof ToOneChangeEntry) ? ((ToOneChangeEntry) rv).getPO() : rv;
        }

        @Override
        public Object getOriginalValueControlObjectFor( String pAttributeName )
        {
            return mAttributeNameToOriginalValues.get( pAttributeName );
        }

        @Override
        public String[] getChangedAttributeNames()
        {
            return mAttributeNameToOriginalValues.isEmpty() ? //
                   Utils.EMPTY_STRING_ARRAY : //
                   mAttributeNameToOriginalValues.keySet().toArray( new String[mAttributeNameToOriginalValues.size()] );
        }

        /**
         * @param pThePo needed to support the static instance of NullChangeTracker
         */
        @Override
        public OriginalValueChangeTracker<T> recordChange( T pThePo, String pAttributeName, Object pOldValue, Object pNewValue )
        {
            if ( !mAttributeNameToOriginalValues.containsKey( pAttributeName ) ) // No Original
            {
                mAttributeNameToOriginalValues.put( pAttributeName, pOldValue ); // then add Original
            }
            else
            {
                Object zOriginal = mAttributeNameToOriginalValues.get( pAttributeName );
                if ( Utils.areEqual( zOriginal, pNewValue ) ) // Original value == new Value
                {
                    mAttributeNameToOriginalValues.remove( pAttributeName ); // then pretend we never saw it!
                }
            }
            return this;
        }

        @Override
        public T getTheChangedPo()
        {
            return mTheChangedPo;
        }
    }

    private static class ToOneChangeEntry
    {
        private PersistentObjectImpl mPO;
        private Object mDBkey;

        public ToOneChangeEntry( PersistentObjectImpl pPO, Object pDBkey )
        {
            mPO = pPO;
            mDBkey = pDBkey;
        }

        public PersistentObjectImpl getPO()
        {
            return mPO;
        }

        @Override
        public String toString()
        {
            return (mPO != null) ? mPO.getDisplayValue() : "";
        }

        @Override
        public boolean equals( Object o )
        {
            if ( this == o )
            {
                return true;
            }
            if ( o == null || getClass() != o.getClass() )
            {
                return false;
            }

            ToOneChangeEntry them = (ToOneChangeEntry) o;
            return Utils.areNonArraysEqual( this.mDBkey, them.mDBkey ) && //
                   Utils.areNonArraysEqual( this.mPO, them.mPO );
        }

        @Override
        public int hashCode()
        {
            int result;
            result = (mPO != null ? mPO.hashCode() : 0);
            result = 31 * result + (mDBkey != null ? mDBkey.hashCode() : 0);
            return result;
        }
    }

    protected String fromEncrypted( String pEncryptedText )
    {
        return (pEncryptedText == null) ? null : SymmetricEncryptorManager.Helper.fromEncrypted( getEncryptorManager(), pEncryptedText );
    }

    protected String toEncrypted( String pPlainText )
    {
        return (pPlainText == null) ? null : SymmetricEncryptorManager.Helper.toEncrypted( getEncryptorManager(), pPlainText );
    }

    @SuppressWarnings({"UnusedDeclaration"})
    protected String toLowerCase( String pText )
    {
        return (pText == null) ? null : pText.toLowerCase();
    }

    @SuppressWarnings({"UnusedDeclaration"})
    protected String toUpperCase( String pText )
    {
        return (pText == null) ? null : pText.toUpperCase();
    }

    public static class BackDoor
    {
        @SuppressWarnings({"UnusedDeclaration"})
        public static boolean isRehydrating( PersistentObjectImpl pPersistentObject )
        {
            return pPersistentObject.mRehydrating;
        }

        public static void justDeletedInTransaction( PersistentObjectImpl pPersistentObject, DBconnection pDBconnection )
        {
            pPersistentObject.justDeletedInTransaction( pDBconnection );
        }

        public static void disposeTransactionOn( PersistentObjectImpl pPersistentObject )
        {
            pPersistentObject.transactionDisposed();
        }

        public static void transactionCommitSucceededDropTransactionOn( PersistentObjectImpl pPersistentObject )
        {
            pPersistentObject.backdoorTransactionCommitSucceededDropTransaction();
        }

        public static void transactionCommitSucceededClearTransactionalChangesOn( PersistentObjectImpl pPersistentObject )
        {
            pPersistentObject.backdoorTransactionCommitSucceededClearTransactionalChanges();
        }

        public static <T extends PersistentObjectImpl> T rehydrationComplete( T pPersistentObject, Finder pFinder )
        {
            //noinspection unchecked
            return (T) pPersistentObject.rehydrationComplete( pFinder );
        }

        public static void processLazyLoadMutation( PersistentObjectImpl pPersistentObject, LazyLoadToOneVariable pValueHolder, //
                                                    PersistentObjectImpl pNewThem, //
                                                    String pBackRefAttributeNameOnNewThem )
                throws UnsupportedOperationException
        {
            //noinspection unchecked
            pPersistentObject.processLazyLoadMutation( pValueHolder, pNewThem, pBackRefAttributeNameOnNewThem );
        }

        public static boolean verifyMutabilityOnChangeToOneOn( PersistentObjectImpl pPersistentObject, AbstractAttributeAccessorSCDtoOne pSupplimentedSCDtoOne, PersistentObjectImpl pOldThem, Object pOldKey, PersistentObjectImpl pNewThem, Object pNewKey )
        {
            return pPersistentObject.verifyMutabilityOnChangeToOne( pSupplimentedSCDtoOne, //
                                                                    pOldThem, pOldKey, //
                                                                    pNewThem, pNewKey );
        }

        public static void changeToManyDueToOne( PersistentObjectImpl pPersistentObject, AbstractAttributeAccessorSCDtoOne pToOne )
        {
            pPersistentObject.changeToManyDueToOne( pToOne );
        }

        public static void changeNotifyToManyDueToOne( PersistentObjectImpl pPersistentObject, AbstractAttributeAccessorSCDtoOne pToOne )
        {
            pPersistentObject.changeNotifyToManyDueToOne( pToOne );
        }
    }

    @Override
    public int compareTo( PersistentObject pOther )
    {
        return getPersistentObjectURL().compareTo( pOther.getPersistentObjectURL() );
    }

    @Override
    public Action makeStateChangeAction()
    {
        if ( isDeleteRequested() )
        {
            return Action.DELETED;
        }
        if ( isNew() )
        {
            return Action.CREATED;
        }
        return Action.UPDATED;
    }

    @SuppressWarnings({"UnusedDeclaration"})
    protected static String extractFirstNonBlankLineForDisplayValue( String pText )
    {
        if ( pText != null )
        {
            String[] zLines = Utils.stringToLines( pText );
            for ( String zLine : zLines )
            {
                if ( (zLine = Utils.normalizeCtrlChars( zLine ).trim()).length() != 0 )
                {
                    return zLine;
                }
            }
        }
        return null;
    }

    @Override
    public void rehydationComplete()
    {
    }
}