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.List;
017    
018    import org.apache.tapestry.components.IPrimaryKeyConverter;
019    import org.apache.tapestry.form.IPropertySelectionModel;
020    
021    
022    /**
023     * Defines the interface used by the {@link Autocompleter} component to filter
024     * and match values from a potentially large data set. 
025     * 
026     * <p>
027     *  The roots of this model come from the {@link IPropertySelectionModel} interface, adding
028     *  additional logic for filtering where the normal semantics of {@link IPropertySelectionModel} 
029     *  would be prohibitively expensive.
030     * </p>
031     * 
032     * @author jkuhnert
033     */
034    public interface IAutocompleteModel extends IPrimaryKeyConverter
035    {
036    
037        /**
038         * For the given value, provide a user friendly label that will
039         * be presented in a drop down selection list in the browser ui.
040         * 
041         * @param value
042         *          The object to retrieve a label for.
043         * @return
044         *          The label to use for the given value.
045         */
046        String getLabelFor(Object value);
047        
048        /**
049         * Expected to return a list of all possible values, filtering out values that
050         * match the specified String in the <strong>label</strong> representation of the value.
051         * 
052         * @param filter 
053         *          The string to use to filter the values based on the label representation of objects.
054         * 
055         * @return A filtered list of values. Expected to be in the full object form such that
056         *      {@link IPrimaryKeyConverter#getPrimaryKey(Object)} can be called on each returned value.
057         */
058        List getValues(String filter);
059    }