Introduce generics to DataSource
Also some further JavaDoc revisions
diff --git a/bundles/org.eclipse.rap.addons.autosuggest/src/org/eclipse/rap/addons/autosuggest/AutoSuggest.java b/bundles/org.eclipse.rap.addons.autosuggest/src/org/eclipse/rap/addons/autosuggest/AutoSuggest.java
index f596863..c31177b 100644
--- a/bundles/org.eclipse.rap.addons.autosuggest/src/org/eclipse/rap/addons/autosuggest/AutoSuggest.java
+++ b/bundles/org.eclipse.rap.addons.autosuggest/src/org/eclipse/rap/addons/autosuggest/AutoSuggest.java
@@ -35,7 +35,7 @@
/**
* Instances of this class provide a complete text input suggestion mechanism
* for a given {@link Text} widget. Suggestions may be displayed below the <code>Text</code> widget
- * via a {@link DropDown} widget and optionally inserted automatically on uniqueness.
+ * in a drop-down and optionally auto-completed.
*
* <p>
* All possible suggestions have to be provided by a {@link DataSource}. The
@@ -72,7 +72,7 @@
protected final RemoteObject remoteObject;
/**
- * Constructs a new instance of this class given a <code>Text</code> instance.
+ * Constructs a new <code>AutoSuggest</code> for a given <code>Text</code> widget.
*
* @param text the <code>Text</code> widget for which suggestions are provided (cannot be null)
*
@@ -112,8 +112,9 @@
}
} );
}
+
/**
- * Sets the receiver's dataSource that provides, filters, and formats suggestions
+ * Sets the receiver's dataSource that provides, filters, and formats suggestions.
*
* @param dataSource the DataSource (can be null)
*
@@ -135,7 +136,7 @@
}
/**
- * Sets the maximum number of suggestion items that can be visible simultaneously
+ * Sets the maximum number of suggestion items that can be visible simultaneously.
*
* @param itemCount the new number of items to be visible (default is 5)
*
@@ -150,7 +151,7 @@
}
/**
- * Gets the maximum number of suggestion items that can be visible simultaneously
+ * Gets the maximum number of suggestion items that can be visible simultaneously.
*
* @return the number of items to be visible
*
@@ -165,8 +166,9 @@
}
/**
- * Controls whether a single remaining suggestion or the common part of multiple remaining
- * suggestions are to be inserted into the text automatically. The inserted part will be selected.
+ * Controls whether a single matching suggestion or the common part of multiple matching
+ * suggestions are to be inserted into the text widget automatically.
+ * The inserted text will be selected.
*
* @param value true to enable the feature (default is false)
*
@@ -205,7 +207,7 @@
}
/**
- * Unregisters a {@link SuggestionSelectedListener} to no longer be notified by the receiver.
+ * Unregisters a {@link SuggestionSelectedListener}.
* If the listener is not registered, nothing happens.
*
* @param listener the listener to be removed (may not be null)
@@ -273,7 +275,7 @@
}
/**
- * May be overwritten to control which event types the internal ClientListner receives from
+ * May be overwritten to control which event types the internal ClientListener receives from
* the <code>Text</code> widget. Default are <code>SWT.Modify</code> and <code>SWT.Verify</code>
*
* @see AutoSuggest#getAutoSuggestListener()
diff --git a/bundles/org.eclipse.rap.addons.autosuggest/src/org/eclipse/rap/addons/autosuggest/ColumnDataProvider.java b/bundles/org.eclipse.rap.addons.autosuggest/src/org/eclipse/rap/addons/autosuggest/ColumnDataProvider.java
index b59b48d..3ee94b3 100644
--- a/bundles/org.eclipse.rap.addons.autosuggest/src/org/eclipse/rap/addons/autosuggest/ColumnDataProvider.java
+++ b/bundles/org.eclipse.rap.addons.autosuggest/src/org/eclipse/rap/addons/autosuggest/ColumnDataProvider.java
@@ -11,15 +11,44 @@
package org.eclipse.rap.addons.autosuggest;
/**
- * An implementation of this interface can be attached to a DataSource to provide multiple strings
- * per suggestion. The first string of each suggestion will be the one to be inserted as text.
+ * An implementation of this interface can be attached to a <code>DataSource</code> instance
+ * to display multiple texts per suggestion.
+ *
*
* <p>
- * It is recommended to use this interface in junction with a {@link ColumnTemplate}.
+ * The strings to be displayed in the list are provided using
+ * {@link ColumnDataProvider#getTexts(Object) getTexts}.
+ * The string to be inserted is provided by the
+ * {@link DataProvider#getValue(Object) getValue} method.
* </p>
- */
-public interface ColumnDataProvider extends DataProvider {
+ *
+ * <p>
+ * It is recommended to use this interface in conjunction with a {@link ColumnTemplate}, except
+ * when <code>getTexts</code> always returns only one String.
+ * </p>
+ *
+ * @param <S> the type that represents a single suggestion
+ * @see DataSource#setDataProvider(DataProvider)
+ * @see DataProvider
- String[] getTexts( Object element );
+ */
+public interface ColumnDataProvider<S> extends DataProvider<S> {
+
+ /**
+ * This method returns the texts to be displayed for a given suggestion in the drop-down list
+ * of <code>AutoSuggest</code>.
+ *
+ * <p>
+ * When used with {@link ColumnTemplate}, the nth string
+ * will be displayed in the nth column. If no string is given for the nth column it will be
+ * empty. Without <code>ColumnTempalte</code> all strings will be display together,
+ * separated by spaces.
+ * </p>
+ *
+ * @param the suggestion, may not be null
+ * @return a texts to be displayed, may be of any length but not null
+ * @see DataSource#setTemplate(ColumnTemplate)
+ */
+ String[] getTexts( S suggestion );
}
diff --git a/bundles/org.eclipse.rap.addons.autosuggest/src/org/eclipse/rap/addons/autosuggest/ColumnTemplate.java b/bundles/org.eclipse.rap.addons.autosuggest/src/org/eclipse/rap/addons/autosuggest/ColumnTemplate.java
index a929f59..1d731ba 100644
--- a/bundles/org.eclipse.rap.addons.autosuggest/src/org/eclipse/rap/addons/autosuggest/ColumnTemplate.java
+++ b/bundles/org.eclipse.rap.addons.autosuggest/src/org/eclipse/rap/addons/autosuggest/ColumnTemplate.java
@@ -14,11 +14,7 @@
* Instances of this class can be used to configure a {@link DataSource} to format the suggestions
* provided by a {@link ColumnDataProvider} as a table.
*
- * <p>
- * If used, the first string of a suggestion will not be displayed in the list, while the
- * remaining strings will be placed in their natural order into each column defined by this
- * template.
- * </p>
+ * @see ColumnDataProvider#getTexts(Object)
*/
public class ColumnTemplate {
@@ -27,7 +23,7 @@
/**
* Constructs a new instance of this class given any number of integers.
*
- * @param widths the width of all columns in pixels
+ * @param widths the width of each column in pixel. Any number of widths are allowed, but not negative values
*/
public ColumnTemplate( int... widths ) {
this.widths = widths;
diff --git a/bundles/org.eclipse.rap.addons.autosuggest/src/org/eclipse/rap/addons/autosuggest/DataProvider.java b/bundles/org.eclipse.rap.addons.autosuggest/src/org/eclipse/rap/addons/autosuggest/DataProvider.java
index dc64ef7..a48ce36 100644
--- a/bundles/org.eclipse.rap.addons.autosuggest/src/org/eclipse/rap/addons/autosuggest/DataProvider.java
+++ b/bundles/org.eclipse.rap.addons.autosuggest/src/org/eclipse/rap/addons/autosuggest/DataProvider.java
@@ -10,25 +10,29 @@
******************************************************************************/
package org.eclipse.rap.addons.autosuggest;
+
/**
- * This is the default interface to be implemented to attach data to a {@link DataSource}
+ * Instances of this interface represent a data set used as suggestions.
+ * It provides a set of suggestions and their textual representation.
*
+ * @param <S> the type that represents a single suggestion
* @see DataSource#setDataProvider(DataProvider)
+ * @see ColumnDataProvider
*/
-public interface DataProvider {
+public interface DataProvider<S> {
/**
- * Provides the raw suggestions data
+ * Provides the list of all possible suggestions.
*
- * @return an iterable object containing all suggestions in any arbitrary format
+ * @return the list of suggestions, may be empty but not <code>null</code>
*/
- Iterable<?> getSuggestions();
+ Iterable<S> getSuggestions();
/**
- * Provides a single suggestion text for a raw suggestion
+ * Provides the text that will be inserted when the given suggestion is selected.
*
- * @return a string to be suggested as text input
+ * @return the text to be inserted, never <code>null</code>
*/
- String getValue( Object element );
+ String getValue( S suggestion );
}
diff --git a/bundles/org.eclipse.rap.addons.autosuggest/src/org/eclipse/rap/addons/autosuggest/DataSource.java b/bundles/org.eclipse.rap.addons.autosuggest/src/org/eclipse/rap/addons/autosuggest/DataSource.java
index 5f4c1e5..79300ae 100644
--- a/bundles/org.eclipse.rap.addons.autosuggest/src/org/eclipse/rap/addons/autosuggest/DataSource.java
+++ b/bundles/org.eclipse.rap.addons.autosuggest/src/org/eclipse/rap/addons/autosuggest/DataSource.java
@@ -16,8 +16,8 @@
import org.eclipse.rap.rwt.remote.RemoteObject;
/**
- * Instances of this class represents a set of suggestions that can be used by an
- * {@link AutoSuggest} instance.
+ * Instances of this class represent a set of suggestions that can be used by
+ * {@link AutoSuggest} instances.
*
* <p>
* A single instance can be used by multiple <code>AutoSuggest</code> instances simultaneously.
@@ -41,7 +41,7 @@
private static final String REMOTE_TYPE = "rwt.remote.Model";
private final RemoteObject remoteObject;
- private DataProvider dataProvider;
+ private DataProvider<Object> dataProvider;
private ColumnTemplate template;
/**
@@ -61,7 +61,7 @@
*
* The type of DataProvider set also determines which <code>Template</code> types can be used
* with the same <code>DataSource</code> instance. (i.e. a {@link ColumnDataProvider} can be
- * used with a {@link ColumnTemplate}.) It also changes how the format of the suggestion
+ * used with a {@link ColumnTemplate}.) It also changes the format of the suggestion
* given to a filterScript.
*
* @param dataProvider the DataProvider instance (may not be null)
@@ -71,11 +71,12 @@
* @see DataSource#setTemplate(ColumnTemplate)
* @see DataSource#setFilterScript(String)
*/
- public void setDataProvider( DataProvider dataProvider ) {
+ @SuppressWarnings( "unchecked" )
+ public void setDataProvider( DataProvider<?> dataProvider ) {
if( dataProvider == null ) {
throw new NullPointerException( "Parameter must not be null: dataProvider" );
}
- this.dataProvider = dataProvider;
+ this.dataProvider = ( DataProvider<Object> )dataProvider;
setInitialData();
}
@@ -83,17 +84,16 @@
* Sets a simple script (JavaScript function returning a boolean)
* used to determine if a given suggestion matches a text typed by the user.
*
- * <p>The Script has to be in the following format (example assumes suggestion is given as string):</p>
+ * <p>The script has to be in the following format (example assumes suggestion is given as string):</p>
* <pre>function( suggestion, userText ) {
- * return suggestion.indexOf( userText ) !== -1;"
+ * return suggestion.indexOf( userText ) !== -1;
*}</pre>
* <p>
* The default script is not case-sensitive and can handle suggestions provided by
- * {@link DataProvider} and {@link ColumnDataProvider} interfaces. In case of
- * <code>ColumnDataProvider</code> only the first column is queried.
+ * {@link DataProvider} and {@link ColumnDataProvider} interfaces.
* </p>
*
- * @param script the filterScript (may be null)
+ * @param script the filterScript, or <code>null</code> to use default script
*
* @see DataSource#setDataProvider(DataProvider)
*/
@@ -102,11 +102,11 @@
}
/**
- * Sets a template that determines how suggestions are presented in the dropDown list.
+ * Sets a template that determines how suggestions are presented in the drop-down list.
*
* <p>
* The template has to be able to process the format of suggestions provided by the type of
- * dataProvider {@link DataSource#setDataProvider(DataProvider) attached} to the receiver.
+ * the <code>DataProvider</code> {@link DataSource#setDataProvider(DataProvider) attached} to the receiver.
* </p>
* <p>
* No template is required for the default {@link DataProvider}.
@@ -143,7 +143,7 @@
private JsonArray getColumnData() {
JsonArray array = new JsonArray();
- ColumnDataProvider columnDataProvider = ( ColumnDataProvider )dataProvider;
+ ColumnDataProvider<Object> columnDataProvider = ( ColumnDataProvider<Object> )dataProvider;
for( Object element : dataProvider.getSuggestions() ) {
JsonArray row = new JsonArray().add( dataProvider.getValue( element ) );
String[] texts = columnDataProvider.getTexts( element );
diff --git a/bundles/org.eclipse.rap.addons.autosuggest/src/org/eclipse/rap/addons/autosuggest/SuggestionSelectedListener.java b/bundles/org.eclipse.rap.addons.autosuggest/src/org/eclipse/rap/addons/autosuggest/SuggestionSelectedListener.java
index 54171c1..42593e9 100644
--- a/bundles/org.eclipse.rap.addons.autosuggest/src/org/eclipse/rap/addons/autosuggest/SuggestionSelectedListener.java
+++ b/bundles/org.eclipse.rap.addons.autosuggest/src/org/eclipse/rap/addons/autosuggest/SuggestionSelectedListener.java
@@ -17,7 +17,7 @@
public interface SuggestionSelectedListener {
/**
- * Sent when the user selects a suggestion
+ * Called when the user selects a suggestion
*/
void suggestionSelected();
