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.request;

import org.openconcerto.sql.FieldExpander;

import org.openconcerto.sql.model.FieldRef;

import org.openconcerto.sql.model.IFieldPath;

import org.openconcerto.sql.model.OrderComparator;

import org.openconcerto.sql.model.SQLField;

import org.openconcerto.sql.model.SQLRowAccessor;

import org.openconcerto.sql.model.SQLRowValues;

import org.openconcerto.sql.model.SQLRowValues.CreateMode;

import org.openconcerto.sql.model.SQLRowValuesListFetcher;

import org.openconcerto.sql.model.SQLSearchMode;

import org.openconcerto.sql.model.SQLSelect;

import org.openconcerto.sql.model.SQLSyntax;

import org.openconcerto.sql.model.SQLSyntax.CaseBuilder;

import org.openconcerto.sql.model.SQLSyntax.DateProp;

import org.openconcerto.sql.model.SQLTable;

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

import org.openconcerto.sql.model.SQLTableModifiedListener;

import org.openconcerto.sql.model.SQLType;

import org.openconcerto.sql.model.Where;

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

import org.openconcerto.utils.CollectionUtils;

import org.openconcerto.utils.Tuple2;

import org.openconcerto.utils.cc.IClosure;

import org.openconcerto.utils.cc.ITransformer;

import java.beans.PropertyChangeListener;

import java.beans.PropertyChangeSupport;

import java.sql.Date;

import java.sql.Time;

import java.sql.Timestamp;

import java.util.ArrayList;

import java.util.Arrays;

import java.util.Collection;

import java.util.Collections;

import java.util.Comparator;

import java.util.HashMap;

import java.util.HashSet;

import java.util.List;

import java.util.Locale;

import java.util.Map;

import java.util.Map.Entry;

import java.util.Set;

import net.jcip.annotations.GuardedBy;

import net.jcip.annotations.ThreadSafe;

@ThreadSafe

public abstract class BaseFillSQLRequest extends BaseSQLRequest {

    private static boolean DEFAULT_SELECT_LOCK = true;

    /**

     * Whether to use "FOR SHARE" in list requests (preventing roles with just SELECT right from

     * seeing the list).

     *

     * @return <code>true</code> if select should obtain a lock.

     * @see SQLSelect#setWaitPreviousWriteTX(boolean)

     */

    public static final boolean getDefaultLockSelect() {

        return DEFAULT_SELECT_LOCK;

    }

    public static final void setDefaultLockSelect(final boolean b) {

        DEFAULT_SELECT_LOCK = b;

    }

    static public void setupForeign(final SQLRowValuesListFetcher fetcher) {

        // include rows having NULL (not undefined ID) foreign keys

        fetcher.setFullOnly(false);

        // treat the same way tables with or without undefined ID

        fetcher.setIncludeForeignUndef(false);

        // be predictable

        fetcher.setReferentsOrdered(true, true);

    }

    static public final boolean addToFetch(final SQLRowValues input, final Path p, final Collection<String> fields) {

        assert p == null || p.isSingleLink() : "Graph size not sufficient to know if graph was modified";

        final int graphSize = input.getGraphSize();

        // don't back track : e.g. if path is SITE -> CLIENT <- SITE we want the siblings of SITE,

        // if we want fields of the primary SITE we pass the path SITE

        final SQLRowValues r = p == null ? input : input.followPathToOne(p, CreateMode.CREATE_ONE, false);

        boolean modified = input.getGraphSize() > graphSize;

        for (final String f : fields) {

            // don't overwrite foreign rows and update modified

            if (!r.getFields().contains(f)) {

                r.put(f, null);

                modified = true;

            }

        }

        return modified;

    }

    private final SQLTable primaryTable;

    @GuardedBy("this")

    private List<Path> order;

    @GuardedBy("this")

    private Where where;

    @GuardedBy("this")

    private Map<IFieldPath, SearchField> searchFields;

    @GuardedBy("this")

    private int searchLimit;

    @GuardedBy("this")

    private ITransformer<SQLSelect, SQLSelect> selTransf;

    @GuardedBy("this")

    private boolean lockSelect;

    private final SQLRowValues graph;

    @GuardedBy("this")

    private SQLRowValues graphToFetch;

    @GuardedBy("this")

    private SQLRowValuesListFetcher frozen;

    {

        // a new instance is never frozen

        this.frozen = null;

    }

    private final PropertyChangeSupport supp = new PropertyChangeSupport(this);

    public BaseFillSQLRequest(final SQLRowValues graph, final Where w) {

        super();

        if (graph == null)

            throw new NullPointerException();

        this.primaryTable = graph.getTable();

        this.setOrder(null);

        this.where = w;

        this.searchFields = Collections.emptyMap();

        this.searchLimit = 35;

        this.selTransf = null;

        this.lockSelect = getDefaultLockSelect();

        this.graph = graph.toImmutable();

        this.graphToFetch = null;

    }

    public BaseFillSQLRequest(final BaseFillSQLRequest req) {

        super();

        this.primaryTable = req.getPrimaryTable();

        synchronized (req) {

            this.order = req.order;

            this.where = req.where;

            this.searchFields = req.searchFields;

            this.searchLimit = req.searchLimit;

            this.selTransf = req.selTransf;

            this.lockSelect = req.lockSelect;

            // use methods since they're both lazy

            this.graph = req.getGraph();

            this.graphToFetch = req.getGraphToFetch();

        }

    }

    public synchronized final boolean isFrozen() {

        return this.frozen != null;

    }

    public final void freeze() {

        this.freeze(this);

    }

    private final synchronized void freeze(final BaseFillSQLRequest from) {

        if (!this.isFrozen()) {

            // compute the fetcher once and for all

            this.frozen = from.getFetcher();

            assert this.frozen.isFrozen();

            this.wasFrozen();

        }

    }

    protected void wasFrozen() {

    }

    protected final void checkFrozen() {

        if (this.isFrozen())

            throw new IllegalStateException("this has been frozen: " + this);

    }

    // not final so we can narrow down the return type

    public BaseFillSQLRequest toUnmodifiable() {

        return this.toUnmodifiableP(this.getClass());

    }

    // should be passed the class created by cloneForFreeze(), i.e. not this.getClass() or this

    // won't support anonymous classes

    protected final <T extends BaseFillSQLRequest> T toUnmodifiableP(final Class<T> clazz) {

        final Class<? extends BaseFillSQLRequest> thisClass = this.getClass();

        if (clazz != thisClass && !(thisClass.isAnonymousClass() && clazz == thisClass.getSuperclass()))

            throw new IllegalArgumentException("Passed class isn't our class : " + clazz + " != " + thisClass);

        final BaseFillSQLRequest res;

        synchronized (this) {

            if (this.isFrozen()) {

                res = this;

            } else {

                res = this.clone(true);

                if (res.getClass() != clazz)

                    throw new IllegalStateException("Clone class mismatch : " + res.getClass() + " != " + clazz);

                // freeze before releasing lock (even if not recommended, allow to modify the state

                // of getSelectTransf() while holding our lock)

                // pass ourselves so that if we are an anonymous class the fetcher created with our

                // overloaded methods is used

                res.freeze(this);

            }

        }

        assert res.getClass() == clazz || res.getClass().getSuperclass() == clazz;

        @SuppressWarnings("unchecked")

        final T casted = (T) res;

        return casted;

    }

    // must be called with our lock

    protected abstract BaseFillSQLRequest clone(boolean forFreeze);

    static protected final SQLRowValues computeGraph(final SQLTable t, final Collection<String> fields, final FieldExpander exp) {

        final SQLRowValues vals = new SQLRowValues(t).putNulls(fields);

        exp.expand(vals);

        return vals.toImmutable();

    }

    /**

     * The graph with fields to be automatically added to the UI.

     *

     * @return the expanded frozen graph.

     */

    public final SQLRowValues getGraph() {

        return this.graph;

    }

    /**

     * The graph to fetch, should be a superset of {@link #getGraph()}. To modify it, see

     * {@link #addToGraphToFetch(Path, Set)} and {@link #changeGraphToFetch(IClosure)}.

     *

     * @return the graph to fetch, frozen.

     */

    public final SQLRowValues getGraphToFetch() {

        synchronized (this) {

            if (this.graphToFetch == null && this.getGraph() != null) {

                assert !this.isFrozen() : "no computation should take place after frozen()";

                final SQLRowValues tmp = this.getGraph().deepCopy();

                this.customizeToFetch(tmp);

                this.setGraphToFetch(tmp, true);

            }

            return this.graphToFetch;

        }

    }

    public final void addToGraphToFetch(final String... fields) {

        this.addToGraphToFetch(Arrays.asList(fields));

    }

    public final void addToGraphToFetch(final Collection<String> fields) {

        this.addToGraphToFetch(null, fields);

    }

    public final void addForeignToGraphToFetch(final String foreignField, final Collection<String> fields) {

        this.addToGraphToFetch(new Path(getPrimaryTable()).addForeignField(foreignField), fields);

    }

    /**

     * Make sure that the fields at the end of the path are fetched.

     *

     * @param p a path.

     * @param fields fields to fetch.

     */

    public final void addToGraphToFetch(final Path p, final Collection<String> fields) {

        this.changeGraphToFetch(new IClosure<SQLRowValues>() {

            @Override

            public void executeChecked(SQLRowValues input) {

                addToFetch(input, p, fields);

            }

        }, false);

    }

    public final void changeGraphToFetch(IClosure<SQLRowValues> cl) {

        this.changeGraphToFetch(cl, true);

    }

    private final void changeGraphToFetch(IClosure<SQLRowValues> cl, final boolean checkNeeded) {

        synchronized (this) {

            checkFrozen();

            final SQLRowValues tmp = this.getGraphToFetch().deepCopy();

            cl.executeChecked(tmp);

            this.setGraphToFetch(tmp, checkNeeded);

        }

        fireWhereChange();

    }

    private final void setGraphToFetch(final SQLRowValues tmp, final boolean checkNeeded) {

        assert Thread.holdsLock(this) && !this.isFrozen();

        if (checkNeeded && !tmp.graphContains(this.getGraph()))

            throw new IllegalArgumentException("New graph too small");

        this.graphToFetch = tmp.toImmutable();

    }

    protected void customizeToFetch(final SQLRowValues graphToFetch) {

    }

    protected synchronized final SQLRowValuesListFetcher getFetcher() {

        if (this.isFrozen())

            return this.frozen;

        // fetch order fields, so that consumers can order an updated row in an existing list

        final SQLRowValues tmp = getGraphToFetch().deepCopy();

        for (final Path orderP : this.getOrder()) {

            final SQLRowValues orderVals = tmp.followPath(orderP);

            if (orderVals != null && orderVals.getTable().isOrdered()) {

                orderVals.put(orderVals.getTable().getOrderField().getName(), null);

            }

        }

        // graphToFetch can be modified freely so don't the use the simple constructor

        // order to have predictable result (this will both order the referent rows and main rows.

        // The latter will be overwritten by our own getOrder())

        return setupFetcher(SQLRowValuesListFetcher.create(tmp, true));

    }

    // allow to pass fetcher since they are mostly immutable (and for huge graphs they are slow to

    // create)

    protected final SQLRowValuesListFetcher setupFetcher(final SQLRowValuesListFetcher fetcher) {

        final String tableName = getPrimaryTable().getName();

        setupForeign(fetcher);

        synchronized (this) {

            fetcher.setOrder(getOrder());

            fetcher.setReturnedRowsUnmodifiable(true);

            fetcher.appendSelTransf(new ITransformer<SQLSelect, SQLSelect>() {

                @Override

                public SQLSelect transformChecked(SQLSelect sel) {

                    sel = transformSelect(sel);

                    if (isLockSelect())

                        sel.addLockedTable(tableName);

                    return sel.andWhere(getWhere());

                }

            });

            // freeze to execute setSelTransf() before leaving the synchronized block

            fetcher.freeze();

        }

        return fetcher;

    }

    protected synchronized final List<Path> getOrder() {

        if (this.order != null)

            return this.order;

        return this.getDefaultOrder();

    }

    public final boolean isTableOrder() {

        return this.getPrimaryTable().isOrdered() && this.getOrder().equals(getTableOrder());

    }

    /**

     * Order the passed rows the same as {@link #getFetcher()}.

     *

     * @param r1 the first row.

     * @param r2 the second row.

     * @return a negative integer, zero, or a positive integer as the first argument is less than,

     *         equal to, or greater than the second.

     */

    public final int order(final SQLRowValues r1, final SQLRowValues r2) {

        if (r1 == r2)

            return 0;

        // same behaviour as SQLSelect

        final Comparator<SQLRowAccessor> comp = OrderComparator.getFallbackToPKInstance();

        for (final Path p : getOrder()) {

            final SQLRowValues o1 = r1.followPath(p);

            final SQLRowValues o2 = r2.followPath(p);

            final int res = comp.compare(o1, o2);

            if (res != 0)

                return res;

        }

        return 0;

    }

    protected List<Path> getDefaultOrder() {

        return getTableOrder();

    }

    protected final List<Path> getTableOrder() {

        return Collections.singletonList(Path.get(getPrimaryTable()));

    }

    /**

     * Change the ordering of this request.

     *

     * @param l the list of tables, <code>null</code> to restore the {@link #getDefaultOrder()

     *        default} .

     */

    public synchronized final void setOrder(List<Path> l) {

        checkFrozen();

        this.order = l == null ? null : Collections.unmodifiableList(new ArrayList<Path>(l));

    }

    public final void setWhere(final Where w) {

        synchronized (this) {

            checkFrozen();

            this.where = w;

        }

        fireWhereChange();

    }

    public synchronized final Where getWhere() {

        return this.where;

    }

    /**

     * Whether this request is searchable.

     *

     * @param b <code>true</code> if the {@link #getFields() local fields} should be used,

     *        <code>false</code> to not be searchable.

     */

    public final void setSearchable(final boolean b) {

        this.setSearchFields(b ? getDefaultSearchFields() : Collections.<SearchField> emptyList());

    }

    protected Collection<SearchField> getDefaultSearchFields() {

        final Set<String> names = CollectionUtils.inter(this.getGraph().getFields(), this.getPrimaryTable().getFieldsNames(VirtualFields.LOCAL_CONTENT));

        return mapOfModesToSearchFields(CollectionUtils.<String, SQLSearchMode> createMap(names));

    }

    /**

     * Set the fields used to search.

     *

     * @param searchFields only rows with these fields containing the terms will match.

     * @see #setSearch(String)

     */

    public final void setSearchFieldsNames(final Collection<String> searchFields) {

        this.setSearchFieldsNames(CollectionUtils.<String, SQLSearchMode> createMap(searchFields));

    }

    protected final Collection<SearchField> mapOfModesToSearchFields(Map<String, SQLSearchMode> searchFields) {

        final List<SearchField> list = new ArrayList<SearchField>();

        for (final Entry<String, SQLSearchMode> e : searchFields.entrySet()) {

            list.add(new SearchField(getPrimaryTable().getField(e.getKey()), e.getValue() == null ? SQLSearchMode.CONTAINS : e.getValue()));

        }

        return list;

    }

    /**

     * Set the fields used to search.

     *

     * @param searchFields for each field to search, how to match.

     * @see #setSearch(String)

     */

    public final void setSearchFieldsNames(Map<String, SQLSearchMode> searchFields) {

        this.setSearchFields(mapOfModesToSearchFields(searchFields));

    }

    public final void setSearchFields(final Collection<SearchField> searchFields) {

        // can be outside the synchronized block, since it can't be reverted

        checkFrozen();

        final Map<IFieldPath, SearchField> copy = new HashMap<IFieldPath, SearchField>();

        for (final SearchField f : searchFields) {

            final SearchField prev = copy.put(f.getField(), f);

            if (prev != null)

                throw new IllegalArgumentException("Duplicate : " + f.getField());

        }

        synchronized (this) {

            this.searchFields = Collections.unmodifiableMap(copy);

        }

        fireWhereChange();

    }

    public Map<IFieldPath, SearchField> getSearchFields() {

        synchronized (this) {

            return this.searchFields;

        }

    }

    public synchronized final boolean isSearchable() {

        return !this.getSearchFields().isEmpty();

    }

    public synchronized final void setSearchLimit(final int limit) {

        this.searchLimit = limit;

    }

    public synchronized final int getSearchLimit() {

        return this.searchLimit;

    }

    public final synchronized void setLockSelect(boolean lockSelect) {

        checkFrozen();

        this.lockSelect = lockSelect;

    }

    public final synchronized boolean isLockSelect() {

        return this.lockSelect;

    }

    public Set<SQLTable> getTables() {

        final Set<SQLTable> res = new HashSet<SQLTable>();

        for (final SQLRowValues v : this.getGraphToFetch().getGraph().getItems())

            res.add(v.getTable());

        return res;

    }

    public final void addTableListener(SQLTableModifiedListener l) {

        for (final SQLTable t : this.getTables()) {

            t.addTableModifiedListener(l);

        }

    }

    public final void removeTableListener(SQLTableModifiedListener l) {

        for (final SQLTable t : this.getTables()) {

            t.removeTableModifiedListener(l);

        }

    }

    protected final List<SQLField> getFields() {

        return this.getPrimaryTable().getFields(this.getGraph().getFields());

    }

    protected SQLSelect transformSelect(final SQLSelect sel) {

        final ITransformer<SQLSelect, SQLSelect> transf = this.getSelectTransf();

        return transf == null ? sel : transf.transformChecked(sel);

    }

    // @param searchQuery null means don't want to search in SQL (i.e. no WHERE, no LIMIT), empty

    // means nothing to search (i.e. no WHERE but LIMIT).

    protected final ITransformer<SQLSelect, SQLSelect> createSearchTransformer(final List<String> searchQuery, final Locale l, final Where forceInclude) {

        if (searchQuery == null)

            return null;

        final Map<IFieldPath, SearchField> searchFields;

        final int searchLimit;

        final boolean searchable;

        synchronized (this) {

            searchFields = this.getSearchFields();

            searchLimit = this.getSearchLimit();

            searchable = this.isSearchable();

        }

        if (!searchable) {

            throw new IllegalArgumentException("Cannot search " + searchQuery);

        }

        // continue even if searchQuery is empty to apply the LIMIT

        final List<String> immutableQuery = Collections.unmodifiableList(new ArrayList<String>(searchQuery));

        return new ITransformer<SQLSelect, SQLSelect>() {

            @Override

            public SQLSelect transformChecked(SQLSelect sel) {

                return transformSelectSearch(sel, searchFields, searchLimit, immutableQuery, l, forceInclude);

            }

        };

    }

    static protected final SQLSelect transformSelectSearch(final SQLSelect sel, final Map<IFieldPath, SearchField> searchFields, final int searchLimit, final List<String> searchQuery, final Locale l,

            final Where forceInclude) {

        final Where w;

        final Set<String> matchScore = new HashSet<String>();

        if (!searchQuery.isEmpty()) {

            final SQLSyntax syntax = sel.getSyntax();

            Where where = null;

            for (final String searchTerm : searchQuery) {

                Where termWhere = null;

                for (final SearchField searchField : searchFields.values()) {

                    final FieldRef selF = sel.followFieldPath(searchField.getField());

                    final SQLSearchMode mode = searchField.getMode();

                    final List<String> formatted = searchField.format(selF, l);

                    final String fieldWhere = createWhere(syntax, formatted, mode, searchTerm);

                    termWhere = Where.createRaw(fieldWhere).or(termWhere);

                    if (searchField.getScore() > 0 || !searchField.getHigherModes().isEmpty()) {

                        final CaseBuilder caseBuilder = syntax.createCaseWhenBuilder().setElse("0");

                        for (final Tuple2<SQLSearchMode, Integer> hm : searchField.getHigherModes()) {

                            caseBuilder.addWhen(createWhere(syntax, formatted, hm.get0(), searchTerm), String.valueOf(hm.get1()));

                        }

                        if (searchField.getScore() > 0) {

                            caseBuilder.addWhen(fieldWhere, String.valueOf(searchField.getScore()));

                        }

                        matchScore.add(caseBuilder.build());

                    }

                }

                where = Where.and(termWhere, where);

            }

            // only use forceInclude when there's a restriction otherwise the include transforms

            // itself into a restrict

            if (where != null)

                where = where.or(forceInclude);

            w = where;

        } else {

            w = null;

        }

        sel.andWhere(w);

        if (forceInclude != null)

            matchScore.add("case when " + forceInclude + " then 10000 else 0 end");

        if (!matchScore.isEmpty())

            sel.getOrder().add(0, CollectionUtils.join(matchScore, " + ") + " DESC");

        if (searchLimit >= 0)

            sel.setLimit(searchLimit);

        return sel;

    }

    static protected final String createWhere(final SQLSyntax syntax, final List<String> formatted, final SQLSearchMode mode, final String searchQuery) {

        return CollectionUtils.join(formatted, " OR ", new ITransformer<String, String>() {

            @Override

            public String transformChecked(String sqlExpr) {

                return createWhere(sqlExpr, mode, syntax, searchQuery);

            }

        });

    }

    static public final List<String> defaultFormat(final FieldRef selF, final Locale l) {

        final SQLType type = selF.getField().getType();

        final SQLSyntax syntax = SQLSyntax.get(selF.getField());

        if (type.getJavaType() == String.class) {

            return Collections.singletonList(selF.getFieldRef());

        } else if (type.getJavaType() == Boolean.class) {

            final org.openconcerto.utils.i18n.TM utilsTM = org.openconcerto.utils.i18n.TM.getInstance(l);

            return Collections.singletonList(

                    "case when " + selF.getFieldRef() + " then " + syntax.quoteString(utilsTM.translate("true_key")) + " else " + syntax.quoteString(utilsTM.translate("false_key")) + " end");

        } else if (Timestamp.class.isAssignableFrom(type.getJavaType())) {

            final String shortFmt = formatTime(selF, DateProp.SHORT_DATETIME_SKELETON, l, syntax);

            final String longFmt = formatTime(selF, DateProp.LONG_DATETIME_SKELETON, l, syntax);

            return Arrays.asList(shortFmt, longFmt);

        } else if (Time.class.isAssignableFrom(type.getJavaType())) {

            return Collections.singletonList(formatTime(selF, DateProp.TIME_SKELETON, l, syntax));

        } else if (Date.class.isAssignableFrom(type.getJavaType())) {

            final String shortFmt = formatTime(selF, DateProp.SHORT_DATE_SKELETON, l, syntax);

            final String longFmt = formatTime(selF, DateProp.LONG_DATE_SKELETON, l, syntax);

            return Arrays.asList(shortFmt, longFmt);

        } else {

            return Collections.singletonList(syntax.cast(selF.getFieldRef(), String.class));

        }

    }

    static public final String formatTime(final FieldRef selF, final List<String> simpleFormat, final Locale l, final SQLSyntax syntax) {

        return syntax.getFormatTimestampSimple(selF.getFieldRef(), DateProp.getBestPattern(simpleFormat, l), l);

    }

    static protected final String createWhere(final String sqlExpr, final SQLSearchMode mode, final SQLSyntax syntax, final String searchQuery) {

        return "lower(" + sqlExpr + ") " + mode.generateSQL(syntax, searchQuery.toLowerCase());

    }

    static public class SearchField {

        private final IFieldPath field;

        private final SQLSearchMode mode;

        private final int score;

        private final List<Tuple2<SQLSearchMode, Integer>> higherModes;

        public SearchField(IFieldPath field, SQLSearchMode mode) {

            this(field, mode, 1);

        }

        /**

         * Create a new search field.

         *

         * @param field which field to search.

         * @param mode how to search.

         * @param score the score (>0) to attribute if the field matches. Allow to rank fields

         *        between themselves.

         */

        public SearchField(IFieldPath field, SQLSearchMode mode, int score) {

            this(field, mode, score, -1, -1);

        }

        public SearchField(final IFieldPath field, final SQLSearchMode mode, final int score, final int score2, final int score3) {

            super();

            if (field.getField().getFieldGroup().getKeyType() != null)

                throw new IllegalArgumentException("Field is a key : " + field);

            this.field = field;

            this.mode = mode;

            /*

             * for now we could pass <code>1</code> so that a row with more matches is higher ranked

             * (e.g. if searching "a" ["ant", "cat"] is better than ["ant", "horse"]), or

             * <code>0</code> to ignore the match count. But this only works because we have

             * separate WHERE and ORDER BY ; if we had a computed column with "WHERE score > 0 ORDER

             * BY score" this would be complicated.

             */

            if (score < 1)

                throw new IllegalArgumentException("Invalid score : " + score);

            this.score = score;

            final List<SQLSearchMode> higherModes = field.getField().getType().getJavaType() == String.class ? this.mode.getHigherModes() : Collections.<SQLSearchMode> emptyList();

            if (higherModes.isEmpty()) {

                this.higherModes = Collections.emptyList();

            } else {

                if (higherModes.size() > 2)

                    throw new IllegalStateException("Too many higher modes " + higherModes);

                final List<Tuple2<SQLSearchMode, Integer>> tmp = new ArrayList<Tuple2<SQLSearchMode, Integer>>(2);

                tmp.add(Tuple2.create(higherModes.get(0), score3 < 1 ? Math.max((int) (this.score * 1.5), this.score + 2) : score3));

                if (higherModes.size() > 1)

                    tmp.add(Tuple2.create(higherModes.get(1), score2 < 1 ? Math.max((int) (this.score * 1.2), this.score + 1) : score2));

                this.higherModes = Collections.unmodifiableList(tmp);

            }

        }

        public final IFieldPath getField() {

            return this.field;

        }

        public final SQLSearchMode getMode() {

            return this.mode;

        }

        public final int getScore() {

            return this.score;

        }

        public List<Tuple2<SQLSearchMode, Integer>> getHigherModes() {

            return this.higherModes;

        }

        protected List<String> format(final FieldRef selF, final Locale l) {

            if (getField().getField() != selF.getField())

                throw new IllegalArgumentException("Wrong field");

            return defaultFormat(selF, l);

        }

    }

    public final synchronized ITransformer<SQLSelect, SQLSelect> getSelectTransf() {

        return this.selTransf;

    }

    /**

     * Allows to transform the SQLSelect returned by getFillRequest().

     *

     * @param transf the transformer to apply, needs to be thread-safe.

     */

    public final void setSelectTransf(final ITransformer<SQLSelect, SQLSelect> transf) {

        synchronized (this) {

            checkFrozen();

            this.selTransf = transf;

        }

        this.fireWhereChange();

    }

    public final SQLTable getPrimaryTable() {

        return this.primaryTable;

    }

    protected final void fireWhereChange() {

        // don't call unknown code with our lock

        assert !Thread.holdsLock(this);

        this.supp.firePropertyChange("where", null, null);

    }

    public final void addWhereListener(final PropertyChangeListener l) {

        this.supp.addPropertyChangeListener("where", l);

    }

    public final void rmWhereListener(final PropertyChangeListener l) {

        this.supp.removePropertyChangeListener("where", l);

    }

    @Override

    public String toString() {

        return this.getClass().getName() + " on " + this.getPrimaryTable();

    }

}