Dépôt officiel du code source de l'ERP OpenConcerto

/*

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.

 *

 * Copyright 2011 OpenConcerto, by ILM Informatique. All rights reserved.

 *

 * The contents of this file are subject to the terms of the GNU General Public License Version 3

 * only ("GPL"). You may not use this file except in compliance with the License. You can obtain a

 * copy of the License at http://www.gnu.org/licenses/gpl-3.0.html See the License for the specific

 * language governing permissions and limitations under the License.

 *

 * When distributing the software, include this License Header Notice in each file.

 */

 package org.openconcerto.sql.model;

import org.openconcerto.sql.model.SQLRowValuesCluster.State;

import org.openconcerto.sql.model.SQLRowValuesCluster.ValueChangeListener;

import org.openconcerto.sql.model.SQLTable.FieldGroup;

import org.openconcerto.sql.model.SQLTableEvent.Mode;

import org.openconcerto.sql.model.graph.Link;

import org.openconcerto.sql.model.graph.Link.Direction;

import org.openconcerto.sql.model.graph.Path;

import org.openconcerto.sql.model.graph.SQLKey.Type;

import org.openconcerto.sql.model.graph.Step;

import org.openconcerto.sql.request.Inserter;

import org.openconcerto.sql.request.Inserter.Insertion;

import org.openconcerto.sql.request.Inserter.ReturnMode;

import org.openconcerto.sql.users.UserManager;

import org.openconcerto.sql.utils.ReOrder;

import org.openconcerto.utils.CollectionMap2Itf.SetMapItf;

import org.openconcerto.utils.CollectionUtils;

import org.openconcerto.utils.CompareUtils;

import org.openconcerto.utils.CopyUtils;

import org.openconcerto.utils.ExceptionUtils;

import org.openconcerto.utils.ListMap;

import org.openconcerto.utils.RecursionType;

import org.openconcerto.utils.SetMap;

import org.openconcerto.utils.Tuple2;

import org.openconcerto.utils.cc.IClosure;

import org.openconcerto.utils.cc.ITransformer;

import org.openconcerto.utils.cc.IdentitySet;

import org.openconcerto.utils.cc.LinkedIdentitySet;

import org.openconcerto.utils.cc.TransformedMap;

import org.openconcerto.utils.convertor.NumberConvertor;

import org.openconcerto.utils.convertor.ValueConvertor;

import org.openconcerto.utils.convertor.ValueConvertorFactory;

import java.math.BigDecimal;

import java.sql.Connection;

import java.sql.PreparedStatement;

import java.sql.ResultSet;

import java.sql.SQLException;

import java.sql.Statement;

import java.sql.Timestamp;

import java.util.ArrayList;

import java.util.Arrays;

import java.util.Collection;

import java.util.Collections;

import java.util.EventListener;

import java.util.EventObject;

import java.util.HashMap;

import java.util.HashSet;

import java.util.Iterator;

import java.util.LinkedHashMap;

import java.util.LinkedHashSet;

import java.util.List;

import java.util.ListIterator;

import java.util.Map;

import java.util.Map.Entry;

import java.util.Set;

import net.jcip.annotations.GuardedBy;

/**

 * A class that represent a row of a table that can be modified before being inserted or updated.

 * The row might not actually exists in the database, and it might not define all the fields. One

 * can put SQLRowValues as a foreign key value, so that it will be inserted as well.

 *

 * @author Sylvain CUAZ

 * @see #load(SQLRowAccessor, Set)

 * @see #put(String, Object)

 * @see #insert()

 * @see #update(int)

 */

public final class SQLRowValues extends SQLRowAccessor {

    public static enum ForeignCopyMode {

        /**

         * Copy no SQLRowValues.

         */

        NO_COPY,

        /**

         * Put <code>null</code> instead of the SQLRowValues. This keeps all fields.

         */

        COPY_NULL,

        /**

         * Copy the id of SQLRowValues if any, otherwise don't copy anything. This keeps the maximum

         * of information without any foreign rowValues.

         */

        COPY_ID_OR_RM,

        /**

         * Copy the id of SQLRowValues if any, otherwise copy the row. This keeps all the

         * information.

         */

        COPY_ID_OR_ROW,

        /**

         * Copy every SQLRowValues.

         */

        COPY_ROW

    }

    static public enum CreateMode {

        /**

         * Never create rows.

         */

        CREATE_NONE,

        /**

         * For non-full step, create one row with all links. For example with a step of 3 links :

         * <ul>

         * <li>if they are all filled, do nothing</li>

         * <li>if they are all empty, create one row</li>

         * <li>if one link is filled with a row, add all empty links to it</li>

         * <li>if more than one link is filled (but not all of them), error out as it would leave a

         * hybrid state : neither 2 rows joined by all the links, nor one row per link</li>

         * </ul>

         * Then follow all existing plus created rows.

         */

        CREATE_ONE,

        /**

         * Create one row for each empty link, then follow all existing plus created rows.

         */

        CREATE_MANY

    }

    public static final Object SQL_DEFAULT = new Object() {

        @Override

        public String toString() {

            return SQLRowValues.class.getSimpleName() + ".SQL_DEFAULT";

        }

    };

    /**

     * Empty foreign field value.

     *

     * @see #putEmptyLink(String)

     */

    public static final Object SQL_EMPTY_LINK = new Object() {

        @Override

        public String toString() {

            return SQLRowValues.class.getSimpleName() + ".SQL_EMPTY_LINK";

        }

    };

    static public enum ValidityCheck {

        /**

         * The check is never performed.

         */

        FORBIDDEN {

            @Override

            public boolean shouldCheck(final Boolean asked) {

                return false;

            }

        },

        /**

         * The check is only performed if requested.

         */

        FALSE_BY_DEFAULT {

            @Override

            public boolean shouldCheck(Boolean asked) {

                return asked == null ? false : asked.booleanValue();

            }

        },

        /**

         * The check is performed unless specified.

         */

        TRUE_BY_DEFAULT {

            @Override

            public boolean shouldCheck(Boolean asked) {

                return asked == null ? true : asked.booleanValue();

            }

        },

        /**

         * The check is always performed. This is not generally recommended as some methods of the

         * framework will fail.

         */

        FORCED {

            @Override

            public boolean shouldCheck(Boolean asked) {

                return true;

            }

        };

        public abstract boolean shouldCheck(final Boolean asked);

    }

    @GuardedBy("this")

    private static ValidityCheck checkValidity;

    /**

     * Set how {@link #getInvalid()} should be called before each data modification. Initially set

     * to {@link ValidityCheck#TRUE_BY_DEFAULT}. NOTE : the check is performed outside the

     * transaction and thus not always accurate. Only the DB can make sure of the validity

     * efficiently : with foreign keys and a trigger to check that unarchived rows reference

     * unarchived rows.

     *

     * @param vc the new mode, <code>null</code> to set the default.

     */

    public synchronized static void setValidityChecked(final ValidityCheck vc) {

        checkValidity = vc == null ? ValidityCheck.TRUE_BY_DEFAULT : vc;

    }

    /**

     * Whether or not {@link #getInvalid()} should be called.

     *

     * @param asked what the caller requested.

     * @return <code>true</code> if the validity is checked.

     */

    public synchronized static boolean isValidityChecked(final Boolean asked) {

        return checkValidity.shouldCheck(asked);

    }

    static {

        setValidityChecked(null);

    }

    private static final boolean DEFAULT_ALLOW_BACKTRACK = true;

    // i.e. no re-hash for up to 6 entries (8*0.8=6.4)

    private static final int DEFAULT_VALUES_CAPACITY = 8;

    private static final float DEFAULT_LOAD_FACTOR = 0.8f;

    // Assure there's no copy. Don't just return plannedSize : e.g. for HashMap if it's 15

    // the initial capacity will be 16 (the nearest power of 2) and threshold will be 12.8 (with

    // our load of 0.8) so there would be a rehash at the 13th items.

    private static final int getCapacity(final int plannedSize, final int defaultCapacity) {

        return plannedSize < 0 ? defaultCapacity : Math.max((int) (plannedSize / DEFAULT_LOAD_FACTOR) + 1, 4);

    }

    private static final LinkedHashMap<String, Object> createLinkedHashMap(final int plannedSize) {

        if (plannedSize < 0)

            throw new IllegalArgumentException("Negative capacity");

        return createLinkedHashMap(plannedSize, -1);

    }

    private static final <K, V> LinkedHashMap<K, V> createLinkedHashMap(final int plannedSize, final int defaultCapacity) {

        return new LinkedHashMap<K, V>(getCapacity(plannedSize, defaultCapacity), DEFAULT_LOAD_FACTOR);

    }

    private static final <K> SetMap<K, SQLRowValues> createSetMap(final int plannedSize, final int defaultCapacity) {

        return new SetMap<K, SQLRowValues>(new HashMap<K, Set<SQLRowValues>>(getCapacity(plannedSize, defaultCapacity), DEFAULT_LOAD_FACTOR), org.openconcerto.utils.CollectionMap2.Mode.NULL_FORBIDDEN, false) {

            @Override

            public Set<SQLRowValues> createCollection(Collection<? extends SQLRowValues> coll) {

                // use LinkedHashSet so that the order is preserved, eg we can iterate over LOCALs

                // pointing to a BATIMENT with consistent and predictable (insertion-based) order.

                // use IdentitySet to be able to put two equal instances

                return coll == null ? new LinkedIdentitySet<SQLRowValues>() : new LinkedIdentitySet<SQLRowValues>(coll);

            }

        };

    }

    private final Map<String, Object> values;

    private final Map<String, SQLRowValues> foreigns;

    private final SetMap<SQLField, SQLRowValues> referents;

    private SQLRowValuesCluster graph;

    private ListMap<SQLField, ReferentChangeListener> referentsListener;

    public SQLRowValues(SQLTable t) {

        this(t, -1, -1, -1);

    }

    /**

     * Create a new instance.

     *

     * @param t the table.

     * @param valuesPlannedSize no further allocations will be made until that number of

     *        {@link #getAbsolutelyAll() values}, pass a negative value to use a default.

     * @param foreignsPlannedSize no further allocations will be made until that number of

     *        {@link #getForeigns() foreigns}, pass a negative value to use a default.

     * @param referentsPlannedSize no further allocations will be made until that number of

     *        {@link #getReferentsMap() referents}, pass a negative value to use a default.

     *

     */

    public SQLRowValues(SQLTable t, final int valuesPlannedSize, final int foreignsPlannedSize, final int referentsPlannedSize) {

        super(t);

        // use LinkedHashSet so that the order is preserved, see #walkFields()

        this.values = createLinkedHashMap(valuesPlannedSize, DEFAULT_VALUES_CAPACITY);

        // foreigns order should be coherent with values

        this.foreigns = createLinkedHashMap(foreignsPlannedSize, 4);

        this.referents = createSetMap(referentsPlannedSize, 4);

        // no used much so lazy init

        this.referentsListener = null;

        // Allow to reduce memory for lonely rows, and even for linked rows since before :

        // 1. create a row, create a cluster

        // 2. create a second row, create a second cluster

        // 3. put, the second row uses the first cluster, the second one can be collected

        // Now the second cluster is never created, see SQLRowValuesCluster.add().

        this.graph = null;

    }

    public SQLRowValues(SQLTable t, Map<String, ?> values) {

        this(t, values.size(), -1, -1);

        this.setAll(values);

    }

    public SQLRowValues(SQLRowValues vals) {

        this(vals, ForeignCopyMode.COPY_ROW);

    }

    /**

     * Create a new instance with the same values. If <code>copyForeigns</code> is <code>true</code>

     * the new instance will have exactly the same values, ie it will point to the same

     * SQLRowValues. If <code>copyForeigns</code> is <code>false</code> all SQLRowValues will be

     * left out.

     *

     * @param vals the instance to copy.

     * @param copyForeigns whether to copy foreign SQLRowValues.

     */

    public SQLRowValues(SQLRowValues vals, ForeignCopyMode copyForeigns) {

        // setAll() takes care of foreigns and referents

        this(vals.getTable(), vals.getAllValues(copyForeigns));

    }

    /**

     * Copy this rowValues and all others connected to it. Ie contrary to

     * {@link #SQLRowValues(SQLRowValues)} the result will not point to the same rowValues, but to

     * copy of them.

     *

     * @return a copy of this.

     */

    public final SQLRowValues deepCopy() {

        return this.getGraph().deepCopy(this, false);

    }

    public final SQLRowValues copy(final SQLRowValues graph) {

        return this.getGraph().copy(this, graph).get(this);

    }

    /**

     * Get a frozen version of this. If not already {@link #isFrozen() frozen}, copy this rowValues

     * and all others connected to it and {@link SQLRowValuesCluster#freeze()} the copy. I.e. if the

     * result is to be shared among threads, it still needs to be safely published.

     *

     * @return this if already frozen, otherwise a frozen copy of this.

     */

    public final SQLRowValues toImmutable() {

        if (this.isFrozen())

            return this;

        return this.getGraph().deepCopy(this, true);

    }

    // *** graph

    private void updateLinks(String fieldName, Object old, Object value) {

        // try to avoid getTable().getField() (which takes 1/3 of put() for nothing when there is no

        // rowvalues)

        final boolean oldRowVals = old instanceof SQLRowValues;

        final boolean newRowVals = value instanceof SQLRowValues;

        if (!oldRowVals && !newRowVals)

            return;

        final SQLField f = this.getTable().getField(fieldName);

        if (oldRowVals) {

            final SQLRowValues vals = (SQLRowValues) old;

            vals.referents.removeOne(f, this);

            this.foreigns.remove(fieldName);

            assert this.graph == vals.graph;

            this.graph.remove(this, f, vals);

            vals.fireRefChange(f, false, this);

        }

        if (newRowVals) {

            final SQLRowValues vals = (SQLRowValues) value;

            vals.referents.add(f, this);

            this.foreigns.put(fieldName, vals);

            // prefer vals' graph as add() is faster that way

            final SQLRowValuesCluster usedGraph = this.graph != null && vals.graph == null ? this.graph : vals.getGraph();

            usedGraph.add(this, f, vals);

            assert this.graph == vals.graph;

            vals.fireRefChange(f, true, this);

        }

    }

    /**

     * Return the graph for this instance. NOTE: for single row values the graph is only created on

     * demand.

     *

     * @return the graph.

     */

    public final SQLRowValuesCluster getGraph() {

        return this.getGraph(true);

    }

    final SQLRowValuesCluster getGraph(final boolean create) {

        if (create && this.graph == null)

            this.graph = new SQLRowValuesCluster(this);

        return this.graph;

    }

    /**

     * The number of items in our graph. NOTE: this method doesn't allocate a graph.

     *

     * @return the number of items in our graph.

     * @see SQLRowValuesCluster#size()

     */

    public final int getGraphSize() {

        final SQLRowValuesCluster g = this.getGraph(false);

        return g == null ? 1 : g.size();

    }

    public final Set<SQLTable> getGraphTables() {

        final SQLRowValuesCluster g = this.getGraph(false);

        if (g == null)

            return Collections.singleton(this.getTable());

        else

            return g.getTables();

    }

    public final <T> void walkGraph(T acc, ITransformer<State<T>, T> closure) {

        this.getGraph().walk(this, acc, closure);

    }

    /**

     * Walk through the fields of the rowValues in order. Eg if you added DESIGNATION, ID_BATIMENT

     * pointing to {DESIGNATION}, then INCLURE, <code>closure</code> would be called with

     * LOCAL.DESIGNATION, LOCAL.ID_BATIMENT.DESIGNATION, LOCAL.INCLURE. This can't be done using

     * {@link SQLRowValuesCluster#walk(SQLRowValues, Object, ITransformer, RecursionType)} since it

     * walks through rowValues so if you use {@link RecursionType#BREADTH_FIRST} you'll be passed

     * LOCAL, then BATIMENT and the reverse if you use {@link RecursionType#DEPTH_FIRST}.

     *

     * @param closure what to do on each field.

     */

    public final void walkFields(IClosure<FieldPath> closure) {

        this.walkFields(closure, false);

    }

    public final void walkFields(IClosure<FieldPath> closure, final boolean includeFK) {

        this.getGraph().walkFields(this, closure, includeFK);

    }

    public final SQLRowValues prune(SQLRowValues graph) {

        return this.prune(graph, true);

    }

    /**

     * Prune this graph.

     *

     * @param graph the rows and fields to keep.

     * @param copy <code>true</code> if a pruned copy should be returned, <code>false</code> to

     *        modify this instance in-place.

     * @return a graph no bigger than the passed parameter.

     * @see SQLRowValuesCluster#prune(SQLRowValues, SQLRowValues, boolean)

     * @see SQLRowValuesCluster#pruneWithoutCopy(SQLRowValues, SQLRowValues, boolean)

     */

    public final SQLRowValues prune(SQLRowValues graph, final boolean copy) {

        return copy ? this.getGraph().prune(this, graph) : this.getGraph().pruneWithoutCopy(this, graph);

    }

    /**

     * Fetch if necessary and store in this the foreign row.

     *

     * @param fk a foreign key, eg "ID_FAMILLE_2".

     * @return the foreign row, eg FAMILLE[1].

     */

    public final SQLRowValues grow(String fk) {

        final Object val = this.getContainedObject(fk);

        // if fk is in our map with a null value, nothing to grow

        if (val != null && !(val instanceof SQLRowValues)) {

            final SQLRowValues vals = new SQLRowValues(this.getTable());

            vals.putRowValues(fk).setAllToNull();

            this.grow(vals, true);

        }

        return (SQLRowValues) this.getForeign(fk);

    }

    public final SQLRowValues grow(SQLRowValues graph) {

        return this.grow(graph, true);

    }

    /**

     * Grow this rowValues to match the passed graph. If this was /RECEPTEUR/ : {DESIGNATION="des";

     * ID_LOCAL=2} and <code>graph</code> is /RECEPTEUR/ : {DESIGNATION=null; ID_LOCAL:

     * /LOCAL/:{DESIGNATION=null}}, then now this is /RECEPTEUR/ : {DESIGNATION="des"; ID_LOCAL:

     * /LOCAL/:{ID=2, DESIGNATION="local"}}

     *

     * @param graph the target graph.

     * @param checkFields <code>true</code> if missing fields should be fetched.

     * @return this.

     * @throws IllegalArgumentException if this couldn't be grown.

     */

    public final SQLRowValues grow(SQLRowValues graph, final boolean checkFields) {

        return this.grow(graph, checkFields, false);

    }

    public final SQLRowValues grow(SQLRowValues graph, final boolean checkFields, final boolean growUndefined) {

        graph.getGraph().grow(graph, this, checkFields, growUndefined);

        return this;

    }

    public final boolean graphContains(SQLRowValues graph) {

        return this.getGraph().contains(this, graph) == null;

    }

    void setGraph(SQLRowValuesCluster g) {

        assert g != null;

        this.graph = g;

    }

    public final boolean hasForeigns() {

        // OK since updateLinks() removes empty map entries

        return !this.foreigns.isEmpty();

    }

    public final Map<String, SQLRowValues> getForeigns() {

        return Collections.unmodifiableMap(this.foreigns);

    }

    final int getForeignsSize() {

        return this.foreigns.size();

    }

    final Map<SQLField, SQLRowValues> getForeignsBySQLField() {

        return new TransformedMap<String, SQLField, SQLRowValues>(this.getForeigns(), new ITransformer<String, SQLField>() {

            @Override

            public SQLField transformChecked(String input) {

                return getTable().getField(input);

            }

        }, new ITransformer<SQLField, String>() {

            @Override

            public String transformChecked(SQLField input) {

                return input.getName();

            }

        });

    }

    // package private since the result is modifiable, see below for the public version

    final SetMap<SQLField, SQLRowValues> getReferents() {

        return this.referents;

    }

    public final SetMapItf<SQLField, SQLRowValues> getReferentsMap() {

        return SetMap.unmodifiableMap(this.referents);

    }

    public final boolean hasReferents() {

        // OK since updateLinks() removes empty map entries

        return !this.referents.isEmpty();

    }

    @Override

    public Collection<SQLRowValues> getReferentRows() {

        // remove the backdoor since values() returns a view

        // remove duplicates (e.g. this is a CONTACT referenced by ID_CONTACT_RAPPORT &

        // ID_CONTACT_RDV from the same site)

        return this.referents.createCollection(this.referents.allValues());

    }

    @Override

    public Set<SQLRowValues> getReferentRows(SQLField refField) {

        return Collections.unmodifiableSet(this.referents.getNonNull(refField));

    }

    @Override

    public Collection<SQLRowValues> getReferentRows(SQLTable refTable) {

        // remove duplicates

        final Collection<SQLRowValues> res = this.referents.createCollection(null);

        assert res.isEmpty();

        for (final Map.Entry<SQLField, Set<SQLRowValues>> e : this.referents.entrySet()) {

            if (e.getKey().getTable().equals(refTable))

                res.addAll(e.getValue());

        }

        return res;

    }

    /**

     * Remove all links pointing to this from the referent rows.

     *

     * @return this.

     */

    public final SQLRowValues clearReferents() {

        return this.changeReferents(ForeignCopyMode.NO_COPY);

    }

    public final SQLRowValues changeReferents(final ForeignCopyMode mode) {

        return this.changeReferents(null, false, mode);

    }

    public final SQLRowValues removeReferents(final SQLField f) {

        // don't use changeReferents() as it's less optimal

        for (final SQLRowValues ref : new ArrayList<SQLRowValues>(this.getReferentRows(f))) {

            ref.remove(f.getName());

        }

        return this;

    }

    public final SQLRowValues removeReferentFields(final Collection<SQLField> fields) {

        return this.changeReferents(fields, false);

    }

    public final SQLRowValues retainReferentFields(final Collection<SQLField> fields) {

        return this.changeReferents(fields, true);

    }

    private final SQLRowValues changeReferents(final Collection<SQLField> fields, final boolean retain) {

        return this.changeReferents(fields, retain, ForeignCopyMode.NO_COPY);

    }

    /**

     * Change referents. NOTE : depending on the {@link ForeignCopyMode mode} this method may detach

     * this row from some of its referents.

     *

     * @param fields the fields to change or to exclude from change.

     * @param exclude <code>true</code> if fields passed to this method must be excluded from the

     *        change, <code>false</code> to only change fields passed to this method.

     * @param mode how the referent row will be changed.

     * @return this.

     */

    public final SQLRowValues changeReferents(final Collection<SQLField> fields, final boolean exclude, final ForeignCopyMode mode) {

        if (!isEmpty(fields, exclude) && mode != ForeignCopyMode.COPY_ROW) {

            // copy otherwise ConcurrentModificationException

            for (final Entry<SQLField, Set<SQLRowValues>> e : CopyUtils.copy(this.getReferents()).entrySet()) {

                // fields == null means !retain thanks to the above if

                if (fields == null || fields.contains(e.getKey()) != exclude) {

                    for (final SQLRowValues ref : e.getValue()) {

                        ref.flatten(e.getKey().getName(), mode);

                    }

                }

            }

        }

        return this;

    }

    public SQLRowValues retainReferent(SQLRowValues toRetain) {

        return this.retainReferents(Collections.singleton(toRetain));

    }

    public SQLRowValues retainReferents(Collection<SQLRowValues> toRetain) {

        toRetain = CollectionUtils.toIdentitySet(toRetain);

        // copy otherwise ConcurrentModificationException

        for (final Entry<SQLField, Set<SQLRowValues>> e : CopyUtils.copy(this.getReferents()).entrySet()) {

            for (final SQLRowValues ref : e.getValue()) {

                if (!toRetain.contains(ref))

                    ref.remove(e.getKey().getName());

            }

        }

        return this;

    }

    // *** get

    public int size() {

        return this.values.size();

    }

    @Override

    public final int getID() {

        final Number res = this.getIDNumber(false);

        if (res != null)

            return res.intValue();

        else

            return SQLRow.NONEXISTANT_ID;

    }

    @Override

    public Number getIDNumber() {

        // We never have rows in the DB with NULL primary key, so a null result means no value was

        // specified (or null was programmatically specified)

        return this.getIDNumber(false);

    }

    public final Number getIDNumber(final boolean mustBePresent) {

        final Object res = this.getObject(this.getTable().getKey().getName(), mustBePresent);

        if (res == null) {

            return null;

        } else {

            return (Number) res;

        }

    }

    @Override

    public final Object getObject(String fieldName) {

        return this.values.get(fieldName);

    }

    @Override

    public Map<String, Object> getAbsolutelyAll() {

        return getAllValues(ForeignCopyMode.COPY_ROW);

    }

    protected final Map<String, Object> getAllValues(ForeignCopyMode copyForeigns) {

        return this.getAllValues(copyForeigns, false);

    }

    private final Map<String, Object> getAllValues(ForeignCopyMode copyForeigns, final boolean copy) {

        final Map<String, Object> toAdd;

        if (copyForeigns == ForeignCopyMode.COPY_ROW || this.foreigns.size() == 0) {

            if (copy) {

                toAdd = createLinkedHashMap(this.size());

                toAdd.putAll(this.values);

            } else {

                toAdd = this.values;

            }

        } else {

            final Set<Entry<String, Object>> entrySet = this.values.entrySet();

            toAdd = createLinkedHashMap(entrySet.size());

            for (final Map.Entry<String, Object> e : entrySet) {

                if (!(e.getValue() instanceof SQLRowValues)) {

                    toAdd.put(e.getKey(), e.getValue());

                } else if (copyForeigns == ForeignCopyMode.COPY_NULL) {

                    toAdd.put(e.getKey(), null);

                } else if (copyForeigns != ForeignCopyMode.NO_COPY) {

                    final SQLRowValues foreign = (SQLRowValues) e.getValue();

                    if (foreign.hasID())

                        toAdd.put(e.getKey(), foreign.getIDNumber());

                    else if (copyForeigns == ForeignCopyMode.COPY_ID_OR_ROW)

                        toAdd.put(e.getKey(), foreign);

                }

            }

        }

        return copy ? toAdd : Collections.unmodifiableMap(toAdd);

    }

    /**

     * All current groups of this row.

     *

     * @return the ordered groups.

     * @throws IllegalStateException if a group is incomplete (e.g. a primary key has only one of

     *         its two values).

     */

    public final Set<FieldGroup> getFieldGroups() throws IllegalStateException {

        final Set<String> fields = this.getFields();

        // keep order

        final LinkedHashSet<FieldGroup> set = new LinkedHashSet<FieldGroup>();

        final Map<String, FieldGroup> tableGroups = this.getTable().getFieldGroups();

        for (final String fieldName : fields) {

            final FieldGroup group = tableGroups.get(fieldName);

            // check that groups are complete

            if (set.add(group)) {

                if (!fields.containsAll(group.getFields()))

                    throw new IllegalStateException("Missing fields for " + group + ", current fields : " + fields);

            }

        }

        return set;

    }

    /**

     * Return the foreign row, if any, for the passed field.

     *

     * @param fieldName name of the foreign field.

     * @return if <code>null</code> or a SQLRowValues one was put at <code>fieldName</code>, return

     *         it ; else assume that an ID was put at <code>fieldName</code> and return a new SQLRow

     *         with it.

     * @throws IllegalArgumentException if fieldName is not a foreign field or if it isn't contained

     *         in this instance.

     * @throws ClassCastException if the value is neither a SQLRowValues, nor <code>null</code> nor

     *         a Number.

     */

    @Override

    public final SQLRowAccessor getForeign(String fieldName) throws IllegalArgumentException, ClassCastException {

        return this.getForeign(this.getForeignLink(Collections.singletonList(fieldName)));

    }

    public final SQLRowAccessor getForeign(final Link l) throws IllegalArgumentException {

        if (!l.getSource().equals(this.getTable()))

            throw new IllegalArgumentException(l + " not from " + this);

        final String fieldName = l.getSingleField().getName();

        final Object val = this.getContainedObject(fieldName);

        if (val instanceof SQLRowAccessor) {

            return (SQLRowAccessor) val;

        } else if (val == null) {

            // since we used getContainedObject(), it means that a null was put in our map, not that

            // fieldName wasn't there

            return null;

        } else if (this.isDefault(fieldName)) {

            throw new IllegalStateException(fieldName + " is DEFAULT");

        } else {

            return new SQLRow(l.getTarget(), this.getInt(fieldName));

        }

    }

    public boolean isDefault(String fieldName) {

        return SQL_DEFAULT.equals(this.getObject(fieldName));

    }

    /**

     * Retourne les champs spécifiés par cette instance.

     *

     * @return l'ensemble des noms des champs.

     */

    @Override

    public Set<String> getFields() {

        return Collections.unmodifiableSet(this.values.keySet());

    }

    // avoid Collections.unmodifiableSet() allocation

    @Override

    public boolean contains(String fieldName) {

        return this.values.containsKey(fieldName);

    }

    @Override

    public final SQLRow asRow() {

        if (!this.hasID())

            throw new IllegalStateException(this + " has no ID");

        return new SQLRow(this.getTable(), this.getAllValues(ForeignCopyMode.COPY_ID_OR_RM));

    }

    @Override

    public final SQLRowValues asRowValues() {

        return this;

    }

    // *** set

    /**

     * Whether this can be modified.

     *

     * @return <code>true</code> if this (and its graph) is not modifiable.

     */

    public final boolean isFrozen() {

        final SQLRowValuesCluster g = this.getGraph(false);

        return g != null && g.isFrozen();

    }

    private void checkFrozen() {

        if (this.isFrozen())

            throw new IllegalStateException("Graph is not modifiable");

    }

    /**

     * Retains only the fields in this that are contained in the specified collection. In other

     * words, removes all of its elements that are not contained in the specified collection.

     *

     * @param fields collection containing elements to be retained, <code>null</code> meaning all.

     * @return this.

     */

    public final SQLRowValues retainAll(Collection<String> fields) {

        return this.changeFields(fields, true);

    }

    private final SQLRowValues changeFields(Collection<String> fields, final boolean retain) {

        return this.changeFields(fields, retain, false);

    }

    public final SQLRowValues changeFields(Collection<String> fields, final boolean retain, final boolean protectGraph) {

        if (isEmpty(fields, retain))

            return this;

        // clear all on an empty values == no-op

        if (!retain && fields == null && this.size() == 0)

            return this;

        final Set<String> toRm = new HashSet<String>(this.values.keySet());

        if (protectGraph)

            toRm.removeAll(this.foreigns.keySet());

        // fields == null => !retain => clear()

        if (fields != null) {

            if (retain) {

                toRm.removeAll(fields);

            } else {

                toRm.retainAll(fields);

            }

        }

        // nothing to change

        if (toRm.isEmpty())

            return this;

        // handle links

        final Map<String, FieldGroup> fieldGroups = getTable().getFieldGroups();

        for (final String fieldName : toRm) {

            if (fieldGroups.get(fieldName).getKeyType() == Type.FOREIGN_KEY)

                // name is OK since it is a foreign key

                // value null is also OK

                this._put(fieldName, null, false, ValueOperation.CHECK);

        }

        if (fields == null && !protectGraph) {

            assert !retain && toRm.equals(this.values.keySet());

            this.values.clear();

        } else {

            this.values.keySet().removeAll(toRm);

        }

        // if there's no graph, there can't be any listeners

        final SQLRowValuesCluster graph = this.getGraph(false);

        if (graph != null)

            graph.fireModification(this, toRm);

        return this;

    }

    /**

     * Removes from this all fields that are contained in the specified collection.

     *

     * @param fields collection containing elements to be removed, <code>null</code> meaning all.

     * @return this.

     */

    public final SQLRowValues removeAll(Collection<String> fields) {

        return this.changeFields(fields, false);

    }

    public final void remove(String field) {

        // check arg & handle links

        this.put(field, null);

        // really remove

        assert !this.isFrozen() : "Should already be checked by put(null)";

        this.values.remove(field);

    }

    public final void clear() {

        this.removeAll(null);

    }

    public final void clearPrimaryKeys() {

        checkFrozen();

        this.clearPrimaryKeys(this.values);

        // by definition primary keys are not foreign keys, so no need to updateLinks()

    }

    private Map<String, Object> clearPrimaryKeys(final Map<String, Object> values) {

        return clearFields(values, this.getTable().getPrimaryKeys());

    }

    private Map<String, Object> clearFields(final Map<String, Object> values, final Set<SQLField> fields) {

        return changeFields(values, fields, false);

    }

    private Map<String, Object> changeFields(final Map<String, Object> values, final Set<SQLField> fields, final boolean retain) {

        final Iterator<String> iter = values.keySet().iterator();

        while (iter.hasNext()) {

            final String fieldName = iter.next();

            if (fields.contains(this.getTable().getField(fieldName)) ^ retain)

                iter.remove();

        }

        return values;

    }

    /**

     * Change foreign and referent rows. NOTE : this doesn't change all foreign keys, only those

     * that contain an {@link SQLRowValues}.

     *

     * @param paths the first steps are to be changed or to be excluded from change,

     *        <code>null</code> meaning all.

     * @param exclude <code>true</code> if steps passed to this method must be excluded from the

     *        change, <code>false</code> to only change steps passed to this method.

     * @param mode how the rows will be changed.

     * @return this.

     */

    public final SQLRowValues changeGraph(final Collection<Path> paths, final boolean exclude, ForeignCopyMode mode) {

        if (this.getGraphSize() == 1)

            return this;

        final Set<SQLField> refFields;

        final Set<String> foreignFields;

        if (paths == null) {

            refFields = null;

            foreignFields = null;

        } else {

            refFields = new HashSet<SQLField>();

            foreignFields = new HashSet<String>();

            for (final Path p : paths) {

                if (p.getFirst() != this.getTable())

                    throw new IllegalArgumentException("Path not from this : " + p);

                if (p.length() > 0) {

                    final Step step = p.getStep(0);

                    for (final Link l : step.getLinks()) {

                        if (step.getDirection(l) == Direction.REFERENT)

                            refFields.addAll(l.getFields());

                        else

                            foreignFields.addAll(l.getCols());

                    }

                }

            }

        }

        changeForeigns(foreignFields, exclude, mode);

        changeReferents(refFields, exclude, mode);

        return this;

    }

    public final void detach() {

        // keep the most information

        this.detach(ForeignCopyMode.COPY_ID_OR_RM);

    }