001    // Copyright Jul 30, 2006 The Apache Software Foundation
002    //
003    // Licensed under the Apache License, Version 2.0 (the "License");
004    // you may not use this file except in compliance with the License.
005    // You may obtain a copy of the License at
006    //
007    //     http://www.apache.org/licenses/LICENSE-2.0
008    //
009    // Unless required by applicable law or agreed to in writing, software
010    // distributed under the License is distributed on an "AS IS" BASIS,
011    // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
012    // See the License for the specific language governing permissions and
013    // limitations under the License.
014    package org.apache.tapestry.dojo.form;
015    
016    import java.util.Map;
017    
018    import org.apache.tapestry.components.IPrimaryKeyConverter;
019    
020    
021    /**
022     * Defines the interface used by the {@link Autocompleter} component to filter
023     * and match values from a potentially large data set. 
024     * 
025     * <p>
026     *  The roots of this model come from the {@link IPropertySelectionModel} interface, adding
027     *  additional logic for filtering where the normal semantics of {@link IPropertySelectionModel} 
028     *  would be prohibitively expensive.
029     * </p>
030     * 
031     * @author jkuhnert
032     */
033    public interface IAutocompleteModel extends IPrimaryKeyConverter
034    {
035    
036        /**
037         * For the given value, provide a user friendly label that will
038         * be presented in a drop down selection list in the browser ui.
039         * 
040         * @param value
041         *          The object to retrieve a label for.
042         * @return
043         *          The label to use for the given value.
044         */
045        String getLabelFor(Object value);
046        
047        /**
048         * Used to filter a potentially large list of objects.
049         * 
050         * @param match
051         *          The given partial string that should be matched against object
052         *          <i>labels</i> in the model being managed.
053         * @return
054         *        A {@link Map} containing key/value pairs matching the given input label string. 
055         *        The map should contain a key compatible with {@link IPrimaryKeyConverter#getPrimaryKey(Object)} 
056         *        and value compatible with {@link #getLabelFor(Object)}.
057         */
058        Map filterValues(String match);
059        
060    }